View Source Jido behaviour (Jido v1.0.0-rc.4)

Jido is a flexible framework for building distributed AI Agents and Workflows 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)

# Subscribe to agent events
{:ok, topic} = Jido.get_agent_topic("agent-id")
Phoenix.PubSub.subscribe(MyApp.PubSub, topic)

Summary

Types

component_metadata()

Callbacks

config()

Functions

cmd(pid_or_tuple, command \\ :default, params \\ %{}, opts \\ [])

Sends a synchronous command to an agent.

cmd_async(pid_or_tuple, command \\ :default, params \\ %{}, opts \\ [])

Sends an asynchronous action command to an agent.

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_by_id(id, opts \\ [])

Retrieves a running Agent by its ID.

get_agent_by_id!(id, opts \\ [])

Pipe-friendly version of get_agent_by_id that raises on errors.

get_agent_by_slug(slug)

See Jido.Discovery.get_agent_by_slug/1.

get_agent_topic(pid)

Gets the PubSub topic for an agent.

get_command_by_slug(slug)

See Jido.Discovery.get_command_by_slug/1.

get_sensor_by_slug(slug)

See Jido.Discovery.get_sensor_by_slug/1.

list_actions(opts \\ [])

See Jido.Discovery.list_actions/1.

list_agents(opts \\ [])

See Jido.Discovery.list_agents/1.

list_commands(opts \\ [])

See Jido.Discovery.list_commands/1.

list_sensors(opts \\ [])

See Jido.Discovery.list_sensors/1.

manage(pid, command, params)

Sends a management command to an agent.

prompt(name)

Retrieves a prompt file from the priv/prompts directory by its name.

Types

component_metadata()

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

Callbacks

config()

@callback config() :: keyword()

Functions

cmd(pid_or_tuple, command \\ :default, params \\ %{}, opts \\ [])

@spec cmd(pid() | {:ok, pid()}, atom(), map(), keyword()) :: any()

Sends a synchronous command to an agent.

Parameters

  • agent: Agent pid or return value from get_agent_by_id
  • command: The command to execute
  • params: Optional map of command parameters
  • opts: Optional keyword list of options:
    • :apply_state - Whether to apply results to agent state (default: true)

Returns

Returns the result of command execution.

Examples 

iex> {:ok, agent} = Jido.get_agent_by_id("my-agent")
iex> Jido.cmd(agent, :generate_response, %{prompt: "Hello"})
{:ok, %{response: "Hi there!"}}

# Without applying state
iex> Jido.cmd(agent, :generate_response, %{prompt: "Hello"}, apply_state: false)
{:ok, %{response: "Hi there!"}}

cmd_async(pid_or_tuple, command \\ :default, params \\ %{}, opts \\ [])

@spec cmd_async(pid() | {:ok, pid()}, atom(), map(), keyword()) ::
  :ok | {:error, term()}

Sends an asynchronous action command to an agent.

Parameters

  • agent: Agent pid or return value from get_agent_by_id
  • command: The command to execute
  • params: Optional map of command parameters

Returns

  • :ok if command was accepted
  • {:error, reason} if rejected

Examples 

iex> {:ok, agent} = Jido.get_agent_by_id("my-agent")
iex> Jido.act_async(agent, :generate_response, %{prompt: "Hello"})
:ok

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_by_id(id, opts \\ [])

@spec get_agent_by_id(
  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_by_id("my-agent")
{:ok, #PID<0.123.0>}

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

get_agent_by_id!(id, opts \\ [])

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

Pipe-friendly version of get_agent_by_id 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_by_id!() |> Jido.act(:command)
:ok

get_agent_by_slug(slug)

See Jido.Discovery.get_agent_by_slug/1.

get_agent_topic(pid)

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

Gets the PubSub topic for an agent.

Parameters

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

Returns

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

Examples 

iex> {:ok, topic} = Jido.get_agent_topic("my-agent")
{:ok, "jido.agent.my-agent"}

iex> {:ok, agent} = Jido.get_agent_by_id("my-agent")
iex> {:ok, topic} = Jido.get_agent_topic(agent)
{:ok, "jido.agent.my-agent"}

get_command_by_slug(slug)

See Jido.Discovery.get_command_by_slug/1.

get_sensor_by_slug(slug)

See Jido.Discovery.get_sensor_by_slug/1.

list_actions(opts \\ [])

See Jido.Discovery.list_actions/1.

list_agents(opts \\ [])

See Jido.Discovery.list_agents/1.

list_commands(opts \\ [])

See Jido.Discovery.list_commands/1.

list_sensors(opts \\ [])

See Jido.Discovery.list_sensors/1.

manage(pid, command, params)

@spec manage(pid() | {:ok, pid()}, atom(), map()) :: any()

Sends a management command to an agent.

Parameters

  • agent: Agent pid or return value from get_agent_by_id
  • command: The command to execute
  • params: Optional map of command parameters

Returns

Returns the result of command execution.

Examples 

iex> {:ok, agent} = Jido.get_agent_by_id("my-agent")
iex> Jido.manage(agent, :pause)
:ok

prompt(name)

@spec prompt(atom()) :: String.t()

Retrieves a prompt file from the priv/prompts directory by its name.

Parameters

  • name: An atom representing the name of the prompt file (without .txt extension)

Returns

The contents of the prompt file as a string if found, otherwise raises an error.

Examples 

iex> Jido.prompt(:system)
"You are a helpful AI assistant..."

iex> Jido.prompt(:nonexistent)
** (File.Error) could not read file priv/prompts/nonexistent.txt