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
Functions
Sends a synchronous command to an agent.
Sends an asynchronous action command to an agent.
Callback used by the generated start_link/0
function.
This is where we actually call Jido.Supervisor.start_link.
Retrieves a running Agent by its ID.
Pipe-friendly version of get_agent_by_id that raises on errors.
Gets the PubSub topic for an agent.
Sends a management command to an agent.
Retrieves a prompt file from the priv/prompts directory by its name.
Types
Callbacks
@callback config() :: keyword()
Functions
Sends a synchronous command to an agent.
Parameters
agent
: Agent pid or return value from get_agent_by_idcommand
: The command to executeparams
: Optional map of command parametersopts
: 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!"}}
Sends an asynchronous action command to an agent.
Parameters
agent
: Agent pid or return value from get_agent_by_idcommand
: The command to executeparams
: 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
@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.
Retrieves a running Agent by its ID.
Parameters
id
: String or atom ID of the agent to retrieveopts
: 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>}
Pipe-friendly version of get_agent_by_id that raises on errors.
Parameters
id
: String or atom ID of the agent to retrieveopts
: Optional keyword list of options::registry
: Override the default agent registry
Returns
pid
if agent is found- Raises
RuntimeError
if agent not found
Examples
iex> "my-agent" |> Jido.get_agent_by_id!() |> Jido.act(:command)
:ok
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"}
Sends a management command to an agent.
Parameters
agent
: Agent pid or return value from get_agent_by_idcommand
: The command to executeparams
: 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
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