Jido behaviour (Jido v1.1.0-rc.2)

View Source

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

This module provides the main interface for interacting with Jido components, including:

  • Managing and interacting with Agents through a high-level API
  • Listing and retrieving Actions, Sensors, and Domains
  • Filtering and paginating results
  • Generating unique slugs for components

Agent Interaction Examples 

# Find and act on an agent
"agent-id"
|> Jido.get_agent_by_id()
|> Jido.act(:command, %{param: "value"})

# Act asynchronously
{:ok, agent} = Jido.get_agent_by_id("agent-id")
Jido.act_async(agent, :command)

# Send management commands
{:ok, agent} = Jido.get_agent_by_id("agent-id")
Jido.manage(agent, :pause)

Summary

Types

component_metadata()
server()

Callbacks

config()

Functions

clone_agent(source_id, new_id, opts \\ [])

Clones an existing agent with a new ID.

ensure_started(jido_module)

Callback used by the generated start_link/0 function. This is where we actually call Jido.Supervisor.start_link.

get_action_by_slug(slug)

See Jido.Discovery.get_action_by_slug/1.

get_agent(id, opts \\ [])

Retrieves a running Agent by its ID.

get_agent!(id, opts \\ [])

Pipe-friendly version of get_agent that raises on errors.

get_agent_by_slug(slug)

See Jido.Discovery.get_agent_by_slug/1.

get_agent_state(pid)

Gets the current state of an agent.

get_demo_by_slug(slug)

See Jido.Discovery.get_demo_by_slug/1.

get_sensor_by_slug(slug)

See Jido.Discovery.get_sensor_by_slug/1.

get_skill_by_slug(slug)

See Jido.Discovery.get_skill_by_slug/1.

list_actions(opts \\ [])

See Jido.Discovery.list_actions/1.

list_agents(opts \\ [])

See Jido.Discovery.list_agents/1.

list_demos(opts \\ [])

See Jido.Discovery.list_demos/1.

list_sensors(opts \\ [])

See Jido.Discovery.list_sensors/1.

list_skills(opts \\ [])

See Jido.Discovery.list_skills/1.

resolve_pid(pid)

Types

component_metadata()

@type component_metadata() :: %{
  module: module(),
  name: String.t(),
  description: String.t(),
  slug: String.t(),
  category: atom() | nil,
  tags: [atom()] | nil
}

server()

@type server() ::
  pid() | atom() | binary() | {name :: atom() | binary(), registry :: module()}

Callbacks

config()

@callback config() :: keyword()

Functions

clone_agent(source_id, new_id, opts \\ [])

@spec clone_agent(String.t() | atom(), String.t() | atom(), keyword()) ::
  {:ok, pid()} | {:error, term()}

Clones an existing agent with a new ID.

Parameters

  • source_id: ID of the agent to clone
  • new_id: ID for the new cloned agent
  • opts: Optional keyword list of options to override for the new agent

Returns

  • {:ok, pid} with the new agent's process ID
  • {:error, reason} if cloning fails

Examples 

iex> {:ok, new_pid} = Jido.clone_agent("source-agent", "cloned-agent")
{:ok, #PID<0.125.0>}

ensure_started(jido_module)

@spec ensure_started(module()) :: Supervisor.on_start()

Callback used by the generated start_link/0 function. This is where we actually call Jido.Supervisor.start_link.

get_action_by_slug(slug)

See Jido.Discovery.get_action_by_slug/1.

get_agent(id, opts \\ [])

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

Retrieves a running Agent by its ID.

Parameters

  • id: String or atom ID of the agent to retrieve
  • opts: Optional keyword list of options:
    • :registry: Override the default agent registry

Returns

  • {:ok, pid} if agent is found and running
  • {:error, :not_found} if agent doesn't exist

Examples 

iex> {:ok, agent} = Jido.get_agent("my-agent")
{:ok, #PID<0.123.0>}

# Using a custom registry
iex> {:ok, agent} = Jido.get_agent("my-agent", registry: MyApp.Registry)
{:ok, #PID<0.123.0>}

get_agent!(id, opts \\ [])

@spec get_agent!(
  String.t() | atom(),
  keyword()
) :: pid()

Pipe-friendly version of get_agent that raises on errors.

Parameters

  • id: String or atom ID of the agent to retrieve
  • opts: Optional keyword list of options:
    • :registry: Override the default agent registry

Returns

Examples 

iex> "my-agent" |> Jido.get_agent!() |> Jido.cmd(:command)
:ok

get_agent_by_slug(slug)

See Jido.Discovery.get_agent_by_slug/1.

get_agent_state(pid)

@spec get_agent_state(pid() | {:ok, pid()} | String.t()) ::
  {:ok, term()} | {:error, term()}

Gets the current state of an agent.

Parameters

  • agent_or_id: Agent pid, ID, or return value from get_agent

Returns

  • {:ok, state} with the agent's current state
  • {:error, reason} if state couldn't be retrieved

Examples 

iex> {:ok, state} = Jido.get_agent_state("my-agent")
{:ok, %Jido.Agent.Server.State{...}}

get_demo_by_slug(slug)

See Jido.Discovery.get_demo_by_slug/1.

get_sensor_by_slug(slug)

See Jido.Discovery.get_sensor_by_slug/1.

get_skill_by_slug(slug)

See Jido.Discovery.get_skill_by_slug/1.

list_actions(opts \\ [])

See Jido.Discovery.list_actions/1.

list_agents(opts \\ [])

See Jido.Discovery.list_agents/1.

list_demos(opts \\ [])

See Jido.Discovery.list_demos/1.

list_sensors(opts \\ [])

See Jido.Discovery.list_sensors/1.

list_skills(opts \\ [])

See Jido.Discovery.list_skills/1.

resolve_pid(pid)

@spec resolve_pid(server()) :: {:ok, pid()} | {:error, :server_not_found}