@spec actions() :: [module()]

Returns the list of actions from all attached plugins.

@spec capabilities() :: [atom()]

Returns the union of all capabilities from all mounted plugin instances.

Capabilities are atoms describing what the agent can do based on its mounted plugins.

Example

MyAgent.capabilities()
# => [:messaging, :channel_management, :chat, :embeddings]

@spec category() :: String.t() | nil

Returns the agent's category.

@spec cmd(Jido.Agent.t(), Jido.Agent.action()) :: Jido.Agent.cmd_result()

Execute actions against the agent. Pure: (agent, action) -> {agent, directives}

This is the core operation. Actions modify state, directives are external effects. Execution is delegated to the configured strategy (default: Direct).

Action Formats

• MyAction - Action module with no params
• {MyAction, %{param: 1}} - Action with params
• {MyAction, %{param: 1}, %{context: data}} - Action with params and context
• {MyAction, %{param: 1}, %{}, [timeout: 1000]} - Action with opts
• %Instruction{} - Full instruction struct
• [...] - List of any of the above (processed in sequence)

Options

The optional third argument opts is a keyword list merged into all instructions:

• :timeout - Maximum time (in ms) for each action to complete
• :max_retries - Maximum retry attempts on failure
• :backoff - Initial backoff time in ms (doubles with each retry)

Examples

{agent, directives} = SquidMesh.Runtime.DispatchAgent.cmd(agent, MyAction)
{agent, directives} = SquidMesh.Runtime.DispatchAgent.cmd(agent, {MyAction, %{value: 42}})
{agent, directives} = SquidMesh.Runtime.DispatchAgent.cmd(agent, [Action1, Action2])

# With per-call options (merged into all instructions)
{agent, directives} = SquidMesh.Runtime.DispatchAgent.cmd(agent, MyAction, timeout: 5000)

@spec description() :: String.t() | nil

Returns the agent's description.

@spec name() :: String.t()

Returns the agent's name.

@spec new(keyword() | map()) :: Jido.Agent.t()

Creates a new agent with optional initial state.

The agent is fully initialized including strategy state. For the default Direct strategy, this is a no-op. For custom strategies, any state initialization is applied (but directives are only processed by AgentServer).

Examples

agent = SquidMesh.Runtime.DispatchAgent.new()
agent = SquidMesh.Runtime.DispatchAgent.new(id: "custom-id")
agent = SquidMesh.Runtime.DispatchAgent.new(state: %{counter: 10})

@spec plugin_config(module() | {module(), atom()}) :: map() | nil

Returns the configuration for a specific plugin.

Accepts either a module or a {module, as_alias} tuple for multi-instance plugins.

@spec plugin_instances() :: [Jido.Plugin.Instance.t()]

Returns the list of plugin instances attached to this agent.

@spec plugin_routes() :: [{String.t(), module(), integer()}]

Returns the expanded and validated plugin routes.

@spec plugin_schedules() :: [
  Jido.Plugin.Schedules.schedule_spec() | Jido.Agent.Schedules.schedule_spec()
]

Returns the expanded plugin and agent schedules.

@spec plugin_specs() :: [Jido.Plugin.Spec.t()]

Returns the list of plugin specs attached to this agent.

@spec plugin_state(Jido.Agent.t(), module() | {module(), atom()}) :: map() | nil

Returns the state slice for a specific plugin.

Accepts either a module or a {module, as_alias} tuple for multi-instance plugins.

@spec plugins() :: [module()]

Returns the list of plugin modules attached to this agent (deduplicated).

For multi-instance plugins, the module appears once regardless of how many instances are mounted.

Example

MyAgent.plugins()
# => [MyApp.SlackPlugin, MyApp.OpenAIPlugin]

@spec schema() :: Zoi.schema() | keyword()

Returns the merged schema (base + plugin schemas).

@spec set(Jido.Agent.t(), map() | keyword()) :: Jido.Agent.agent_result()

Updates the agent's state by merging new attributes.

Uses deep merge semantics - nested maps are merged recursively.

Examples

{:ok, agent} = SquidMesh.Runtime.DispatchAgent.set(agent, %{status: :running})
{:ok, agent} = SquidMesh.Runtime.DispatchAgent.set(agent, counter: 5)

@spec signal_types() :: [String.t()]

Returns all expanded route signal types from plugin routes.

These are the fully-prefixed signal types that the agent can handle.

Example

MyAgent.signal_types()
# => ["slack.post", "slack.channels.list", "openai.chat"]

@spec strategy() :: module()

Returns the execution strategy module for this agent.

@spec strategy_opts() :: keyword()

Returns the strategy options for this agent.

@spec strategy_snapshot(Jido.Agent.t()) :: Jido.Agent.Strategy.Snapshot.t()

Returns a stable, public view of the strategy's execution state.

Use this instead of inspecting agent.state.__strategy__ directly. Returns a Jido.Agent.Strategy.Snapshot struct with:

• status - Coarse execution status
• done? - Whether strategy reached terminal state
• result - Main output if any
• details - Additional strategy-specific metadata

@spec tags() :: [String.t()]

Returns the agent's tags.

@spec validate(
  Jido.Agent.t(),
  keyword()
) :: Jido.Agent.agent_result()

Validates the agent's state against its schema.

Options

• :strict - When true, only schema-defined fields are kept (default: false)

Examples

{:ok, agent} = SquidMesh.Runtime.DispatchAgent.validate(agent)
{:ok, agent} = SquidMesh.Runtime.DispatchAgent.validate(agent, strict: true)

@spec vsn() :: String.t() | nil

Returns the agent's version.