Jido (Jido v2.0.0-rc.1)

自動 (Jido) - A foundational framework for building autonomous, distributed agent systems in Elixir.

Quick Start

Create a Jido supervisor in your application:

defmodule MyApp.Jido do
  use Jido, otp_app: :my_app
end

Add to your supervision tree:

children = [MyApp.Jido]

Start and manage agents:

{:ok, pid} = MyApp.Jido.start_agent(MyAgent, id: "agent-1")
pid = MyApp.Jido.whereis("agent-1")
agents = MyApp.Jido.list_agents()
:ok = MyApp.Jido.stop_agent("agent-1")

Core Concepts

Jido agents are immutable data structures. The core operation is cmd/2:

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

Agents — Immutable structs updated via commands
Actions — Functions that transform agent state (may perform side effects)
Directives — Descriptions of external effects (signals, processes, etc.)

For Tests

Use JidoTest.Case for isolation:

defmodule MyAgentTest do
  use JidoTest.Case, async: true

  test "agent works", %{jido: jido} do
    {:ok, pid} = Jido.start_agent(jido, MyAgent)
    # ...
  end
end

See Jido.Agent for defining agents and Jido.Await for coordination.

Summary

Types

agent_id()

Functions

__using__(opts)

Creates a Jido supervisor module.

agent_count(jido_instance)

Returns the count of running agents in a Jido instance.

agent_pool_name(name, pool_name)

Returns the AgentPool name for a specific pool in a Jido instance.

agent_supervisor_name(name)

Returns the AgentSupervisor name for a Jido instance.

alive?(server)

Check if an agent process is alive and responding.

await(server, timeout_ms \\ 10000, opts \\ [])

Wait for an agent to reach a terminal status.

await_all(servers, timeout_ms \\ 10000, opts \\ [])

Wait for all agents to reach terminal status.

await_any(servers, timeout_ms \\ 10000, opts \\ [])

Wait for any agent to reach terminal status.

await_child(server, child_tag, timeout_ms \\ 30000, opts \\ [])

Wait for a child agent to reach a terminal status.

cancel(server, opts \\ [])

Request graceful cancellation of an agent.

generate_id()

Generate a unique identifier.

get_action_by_slug(slug)

Gets an Action by its slug.

get_child(parent_server, child_tag)

Get a specific child's PID by tag.

get_children(parent_server)

Get the PIDs of all children of a parent agent.

get_sensor_by_slug(slug)

Gets a Sensor by its slug.

get_skill_by_slug(slug)

Gets a Skill by its slug.

list_actions(opts \\ [])

Lists discovered Actions with optional filtering.

list_agents(jido_instance)

Lists all agents running in a Jido instance.

list_demos(opts \\ [])

Lists discovered Demos with optional filtering.

list_sensors(opts \\ [])

Lists discovered Sensors with optional filtering.

list_skills(opts \\ [])

Lists discovered Skills with optional filtering.

refresh_discovery()

Refreshes the Discovery catalog.

registry_name(name)

Returns the Registry name for a Jido instance.

scheduler_name(name)

Returns the Scheduler name for a Jido instance.

start_agent(jido_instance, agent, opts \\ [])

Starts an agent under a specific Jido instance.

start_link(opts)

Starts a Jido instance supervisor.

stop_agent(jido_instance, pid)

Stops an agent by pid or id.

task_supervisor_name(name)

Returns the TaskSupervisor name for a Jido instance.

whereis(jido_instance, id)

Looks up an agent by ID in a Jido instance's registry.

Types

agent_id()

@type agent_id() :: String.t() | atom()

Functions

using(opts)

(macro)

Creates a Jido supervisor module.

Options

:otp_app - Required. Your application name (e.g., :my_app).

Example

defmodule MyApp.Jido do
  use Jido, otp_app: :my_app
end

Then add to your supervision tree in lib/my_app/application.ex:

children = [MyApp.Jido]

Optionally configure in config/config.exs to customize defaults:

config :my_app, MyApp.Jido,
  max_tasks: 2000,
  agent_pools: []

agent_count(jido_instance)

@spec agent_count(atom()) :: non_neg_integer()

Returns the count of running agents in a Jido instance.

Examples

count = Jido.agent_count(MyApp.Jido)
# => 5

agent_pool_name(name, pool_name)

@spec agent_pool_name(atom(), atom()) :: atom()

Returns the AgentPool name for a specific pool in a Jido instance.

agent_supervisor_name(name)

@spec agent_supervisor_name(atom()) :: atom()

Returns the AgentSupervisor name for a Jido instance.

alive?(server)

Check if an agent process is alive and responding.

See Jido.Await.alive?/1 for details.

await(server, timeout_ms \\ 10000, opts \\ [])

Wait for an agent to reach a terminal status.

See Jido.Await.completion/3 for details.

await_all(servers, timeout_ms \\ 10000, opts \\ [])

Wait for all agents to reach terminal status.

See Jido.Await.all/3 for details.

await_any(servers, timeout_ms \\ 10000, opts \\ [])

Wait for any agent to reach terminal status.

See Jido.Await.any/3 for details.

await_child(server, child_tag, timeout_ms \\ 30000, opts \\ [])

Wait for a child agent to reach a terminal status.

See Jido.Await.child/4 for details.

cancel(server, opts \\ [])

Request graceful cancellation of an agent.

See Jido.Await.cancel/2 for details.

generate_id()

Generate a unique identifier.

Delegates to Jido.Util.generate_id/0.

get_action_by_slug(slug)

Gets an Action by its slug.

get_child(parent_server, child_tag)

Get a specific child's PID by tag.

See Jido.Await.get_child/2 for details.

get_children(parent_server)

Get the PIDs of all children of a parent agent.

See Jido.Await.get_children/1 for details.

get_sensor_by_slug(slug)

Gets a Sensor by its slug.

get_skill_by_slug(slug)

Gets a Skill by its slug.

list_actions(opts \\ [])

Lists discovered Actions with optional filtering.

list_agents(jido_instance)

@spec list_agents(atom()) :: [{String.t(), pid()}]

Lists all agents running in a Jido instance.

Returns a list of {id, pid} tuples.

Examples

agents = Jido.list_agents(MyApp.Jido)
# => [{"agent-1", #PID<0.123.0>}, {"agent-2", #PID<0.124.0>}]

list_demos(opts \\ [])

Lists discovered Demos with optional filtering.

list_sensors(opts \\ [])

Lists discovered Sensors with optional filtering.

list_skills(opts \\ [])

Lists discovered Skills with optional filtering.

refresh_discovery()

Refreshes the Discovery catalog.

registry_name(name)

@spec registry_name(atom()) :: atom()

Returns the Registry name for a Jido instance.

scheduler_name(name)

@spec scheduler_name(atom()) :: atom()

Returns the Scheduler name for a Jido instance.

start_agent(jido_instance, agent, opts \\ [])

@spec start_agent(atom(), module() | struct(), keyword()) ::
  DynamicSupervisor.on_start_child()

Starts an agent under a specific Jido instance.

Examples

{:ok, pid} = Jido.start_agent(MyApp.Jido, MyAgent)
{:ok, pid} = Jido.start_agent(MyApp.Jido, MyAgent, id: "custom-id")

start_link(opts)

Starts a Jido instance supervisor.

Options

:name - Required. The name of this Jido instance (e.g., MyApp.Jido)

Example

{:ok, pid} = Jido.start_link(name: MyApp.Jido)

stop_agent(jido_instance, pid)

@spec stop_agent(atom(), pid() | String.t()) :: :ok | {:error, :not_found}

Stops an agent by pid or id.

Examples

:ok = Jido.stop_agent(MyApp.Jido, pid)
:ok = Jido.stop_agent(MyApp.Jido, "agent-id")

task_supervisor_name(name)

@spec task_supervisor_name(atom()) :: atom()

Returns the TaskSupervisor name for a Jido instance.

whereis(jido_instance, id)

@spec whereis(atom(), String.t()) :: pid() | nil

Looks up an agent by ID in a Jido instance's registry.

Returns the pid if found, nil otherwise.

Examples

pid = Jido.whereis(MyApp.Jido, "agent-123")