@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>}

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

Sends a command to an agent.

Parameters

• agent: Agent pid or return value from get_agent
• action: The action to execute
• args: Optional map of action arguments
• opts: Optional keyword list of options

Returns

Returns the result of command execution.

Examples

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

@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.

See Jido.Discovery.get_action_by_slug/1.

@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>}

@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

• pid if agent is found
• Raises RuntimeError if agent not found

Examples

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

See Jido.Discovery.get_agent_by_slug/1.

@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{...}}

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

Gets the status of an agent.

Parameters

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

Returns

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

Examples

iex> {:ok, status} = Jido.get_agent_status("my-agent")
{:ok, :idle}

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

Gets the supervisor for an agent.

Parameters

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

Returns

• {:ok, supervisor_pid} with the agent's supervisor pid
• {:error, reason} if supervisor couldn't be retrieved

Examples

iex> {:ok, supervisor} = Jido.get_agent_supervisor("my-agent")
{:ok, #PID<0.124.0>}

@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

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("my-agent")
iex> {:ok, topic} = Jido.get_agent_topic(agent)
{:ok, "jido.agent.my-agent"}

See Jido.Discovery.get_sensor_by_slug/1.

See Jido.Discovery.list_actions/1.

See Jido.Discovery.list_agents/1.

See Jido.Discovery.list_sensors/1.

@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