Jido

Jido is an autonomous agent framework for Elixir, built for workflows and multi-agent systems.

<!-- package.jido.framework -->

Define agents, connect them to actions, signals, and directives, and run them with supervision and fault tolerance built in.

The name "Jido" (自動) comes from the Japanese word meaning "automatic" or "automated", where 自 (ji) means "self" and 動 (dō) means "movement".

Learn more about Jido at jido.run.

Overview

Jido helps you build agent systems as ordinary Elixir and OTP software.

• Agents hold state and implement cmd/2
• Actions do work and transform that state
• Signals route events into the system
• Directives describe effects for the runtime to execute

The purity boundary is the agent's decision logic: Jido keeps agent decisions and state transitions explicit, actions may be pure or effectful, and directives are for effects you want the runtime to own.

Use Jido when software needs to inspect context, choose among multiple steps, coordinate with other agents, and keep running reliably over time.

AI is optional. The core package gives you the agent architecture and runtime; companion packages such as jido_ai add model integration when you need it.

At the core, Jido agents are immutable data structures with a single command function:

defmodule MyAgent do
  use Jido.Agent,
    name: "my_agent",
    description: "My custom agent",
    schema: [
      count: [type: :integer, default: 0]
    ]
end

{agent, directives} = MyAgent.cmd(agent, action)

State changes are explicit data transformations. If an action needs a result back immediately to continue reasoning or update state, it may perform that work itself. If the workflow has already decided on an outbound effect and wants the runtime or integration layer to own delivery, return a directive.

<!-- package.jido.pure_cmd package.jido.runtime_separation -->

The Jido Ecosystem

Jido is the core package of the Jido ecosystem. The ecosystem is built around the core Jido Agent behavior and offer several opt-in packages to extend the core behavior.

| Package | Description | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | req_llm | HTTP client for LLM APIs | | jido_action | Composable, validated actions with AI tool integration | | jido_signal | CloudEvents-based message envelope and supporting utilities for routing and pub/sub messaging | | jido | Core agent framework with state management, directives, and runtime | | jido_ai | AI/LLM integration for agents |

For demos and examples of what you can build with the Jido Ecosystem, see https://jido.run. For the package map and support levels, see https://jido.run/ecosystem.

Why Jido?

OTP primitives are excellent. You can build agent systems with raw GenServer. But when building multiple cooperating agents, you'll reinvent:

| Raw OTP | Jido Formalizes | | ----------------------------------- | --------------------------------------- | | Ad-hoc message shapes per GenServer | Signals as standard envelope | | Business logic mixed in callbacks | Actions as reusable command pattern | | Implicit effects scattered in code | Directives as typed effect descriptions | | Custom child tracking per server | Built-in parent/child hierarchy | | Process exit = completion | State-based completion semantics |

Jido isn't "better GenServer" - it's a formalized agent pattern built on GenServer.

Key Features

Immutable Agent Architecture

• Functional agent state model inspired by Elm/Redux
• cmd/2 as the core operation: actions in, updated agent + directives out
• Schema-validated state with NimbleOptions or Zoi

Directive-Based Effects

• Actions transform state and may perform required work
• Directives describe runtime-owned external effects
• Built-in directives: Emit, Spawn, SpawnAgent, StopChild, StartSensor, StopSensor, Schedule, Stop
• Protocol-based extensibility for custom directives

OTP Runtime Integration

• GenServer-based AgentServer for production deployment
• Parent-child agent hierarchies with lifecycle management
• Signal routing with configurable strategies
• Instance-scoped supervision plus logical partitions for multi-tenant deployments

Composable Plugins

• Reusable capability modules that extend agents
• State isolation per plugin with automatic schema merging
• Lifecycle hooks for initialization and signal handling

Execution Strategies

• Direct execution for simple workflows
• FSM (Finite State Machine) strategy for state-driven workflows
• Extensible strategy protocol for custom execution patterns

Multi-Agent Orchestration

• Multi-agent workflows with configurable strategies
• Plan-based orchestration for complex workflows
• Durable groups of agents with named topology, hierarchical runtime ownership, nested pod nodes, and partition-safe tenancy boundaries

Installation

Using Igniter (Recommended)

The fastest way to get started is with Igniter:

mix igniter.install jido

This automatically:

• Adds Jido to your dependencies
• Creates a MyApp.Jido instance module (use Jido, otp_app: :my_app)
• Creates configuration in config/config.exs
• Adds MyApp.Jido to your supervision tree

Generate an example agent to get started:

mix igniter.install jido --example

Manual Installation

Add jido to your list of dependencies in mix.exs:

def deps do
  [
    {:jido, "~> 2.0"}
  ]
end

Then define a Jido instance module and add it to your supervision tree:

# In lib/my_app/jido.ex
defmodule MyApp.Jido do
  use Jido, otp_app: :my_app
end

# In config/config.exs
config :my_app, MyApp.Jido,
  max_tasks: 1000,
  agent_pools: []

# In your application.ex
children = [
  MyApp.Jido
]

Supervisor.start_link(children, strategy: :one_for_one)

Quick Start

1. Define an Agent

defmodule MyApp.CounterAgent do
  use Jido.Agent,
    name: "counter",
    description: "A simple counter agent",
    schema: [
      count: [type: :integer, default: 0]
    ],
    signal_routes: [
      {"increment", MyApp.Actions.Increment}
    ]
end

2. Define an Action

defmodule MyApp.Actions.Increment do
  use Jido.Action,
    name: "increment",
    description: "Increments the counter by a given amount",
    schema: [
      amount: [type: :integer, default: 1]
    ]

  def run(params, context) do
    current = context.state[:count] || 0
    {:ok, %{count: current + params.amount}}
  end
end

3. Execute Commands

# Create an agent
agent = MyApp.CounterAgent.new()

# Execute an action - returns updated agent + directives
{agent, directives} = MyApp.CounterAgent.cmd(agent, {MyApp.Actions.Increment, %{amount: 5}})

# Check the state
agent.state.count
# => 5

4. Run with AgentServer

# Start the agent server
{:ok, pid} = MyApp.Jido.start_agent(MyApp.CounterAgent, id: "counter-1")

# Send signals to the running agent (synchronous)
# Signal types must be declared in signal_routes
{:ok, agent} = Jido.AgentServer.call(pid, Jido.Signal.new!("increment", %{amount: 10}, source: "/user"))

# Look up the agent by ID
pid = MyApp.Jido.whereis("counter-1")

# List all running agents
agents = MyApp.Jido.list_agents()

Core Concepts

The cmd/2 Contract

The fundamental operation in Jido:

{agent, directives} = MyAgent.cmd(agent, action)

Key invariants:

• The returned agent is always complete - no "apply directives" step needed
• directives describe runtime-owned external effects only - they never modify agent state
• Agent decision logic stays explicit and testable; deterministic actions produce deterministic cmd/2 results

Use this rule of thumb for side effects:

• If the step needs a result back now to continue reasoning or update state, an effectful action is acceptable.
• If the workflow has already decided on an outbound effect and wants the runtime or integration layer to own delivery, return a directive.

Actions vs Directives vs State Operations

| Actions | Directives | State Operations | | ------------------------------------------ | ------------------------------------- | ------------------------------- | | Transform state, may perform side effects | Describe runtime-owned effec