Jido action that executes a Beam Bots command.
Bridges Jido's action system to BB's command infrastructure: starts the
named command on the robot, awaits its result with BB.Command.await/2,
and maps the outcome into the canonical bb_jido error taxonomy.
Schema
:robot— the robot module (required).:command— the command name as an atom (required).:goal— the goal map passed to the command (default%{}).:timeout— millisecond timeout forBB.Command.await/2(default30_000).
Returns
{:ok, %{command: ..., goal: ..., outcome: ...}}on success.{:error, :safety_disarmed}if the robot rejected the command because it was disarmed, or the command process was stopped by a disarm.{:error, {:command_failed, reason}}for any other command failure or process termination.reasonis passed through exactly once — failures thatBB.Command.await/2already reports as{:command_failed, reason}(crash,:timeout,:noproc) are not wrapped again.
A disarm that happens mid-flight stops the command process, but the
awaited value is still whatever the command's result/1 callback
returns — commands that want callers to see :safety_disarmed in that
case should surface :disarmed (or a {:shutdown, :disarmed} reason)
from result/1.
When routed through an agent, the success map is merged into agent state
by Jido's default strategy — result keys deliberately avoid the plugin's
:robot state key.
Agent-routed execution caveats
When this action runs via a signal route (rather than a direct run/2
call), it executes under Jido.Exec, which has two effects:
Jido.Execenforces its own default 30s execution timeout regardless of the:timeoutparam, and routed signals cannot override it (routed modules become{module, signal.data}with no instruction opts). A:timeoutabove 30s only takes effect if the:jido_action:default_timeoutconfig is raised, or the action is invoked through an explicit instruction whose:optsset aJido.Exec:timeout.- Error tuples are normalised into
Jido.Action.Errorexception structs; the tags above then appear under the error's details rather than as bare tuples.
Summary
Functions
Returns the Action metadata. Alias for to_json/0.
Returns the category of the Action.
Returns the description of the Action.
Returns the name of the Action.
Lifecycle hook called after Action execution.
Lifecycle hook called after output validation.
Lifecycle hook called after parameter validation.
Lifecycle hook called before output validation.
Lifecycle hook called before parameter validation.
Lifecycle hook called when an error occurs.
Returns the output schema of the Action.
Executes the Action with the given parameters and context.
Returns the input schema of the Action.
Returns the tags associated with the Action.
Returns the Action metadata as a JSON-serializable map.
Converts the Action to an LLM-compatible tool format.
Validates the output result for the Action.
Validates the input parameters for the Action.
Returns the version of the Action.
Functions
Returns the Action metadata. Alias for to_json/0.
Returns the category of the Action.
Returns the description of the Action.
Returns the name of the Action.
Lifecycle hook called after Action execution.
Lifecycle hook called after output validation.
Lifecycle hook called after parameter validation.
Lifecycle hook called before output validation.
Lifecycle hook called before parameter validation.
Lifecycle hook called when an error occurs.
Returns the output schema of the Action.
Executes the Action with the given parameters and context.
The run/2 function must be implemented in the module using Jido.Action.
Returns the input schema of the Action.
Returns the tags associated with the Action.
Returns the Action metadata as a JSON-serializable map.
Converts the Action to an LLM-compatible tool format.
Validates the output result for the Action.
Examples
iex> defmodule ExampleAction do
...> use Jido.Action,
...> name: "example_action",
...> output_schema: [
...> result: [type: :string, required: true]
...> ]
...> end
...> ExampleAction.validate_output(%{result: "test", extra: "ignored"})
{:ok, %{result: "test", extra: "ignored"}}
iex> ExampleAction.validate_output(%{extra: "ignored"})
{:error, "Invalid output for Action: Required key :result not found"}Validates the input parameters for the Action.
Examples
iex> defmodule ExampleAction do
...> use Jido.Action,
...> name: "example_action",
...> schema: [
...> input: [type: :string, required: true]
...> ]
...> end
...> ExampleAction.validate_params(%{input: "test"})
{:ok, %{input: "test"}}
iex> ExampleAction.validate_params(%{})
{:error, "Invalid parameters for Action: Required key :input not found"}Returns the version of the Action.