Jido.Runner.Simple (Jido v1.2.0)
View SourceA simple runner that executes a single instruction from an Agent's instruction queue.
Overview
The Simple Runner follows a sequential execution model:
- Dequeues a single instruction from the agent's pending queue
- Executes the instruction via its action module
- Processes the result (either a state update, directive or both)
- Applies state changes if configured
- Returns the updated agent with the execution results and server directives
Features
- Single instruction execution
- Support for directives and state results
- Atomic execution guarantees
- Comprehensive error handling
- Debug logging at key execution points
- Optional state application
Error Handling
- Invalid instructions are rejected
- Action execution failures return error results
- Queue empty condition handled gracefully
- All errors preserve the original agent state
Summary
Functions
Executes a single instruction from the Agent's pending instructions queue.
Types
@type run_opts() :: [ apply_directives?: boolean(), log_level: atom(), timeout: non_neg_integer() ]
@type run_result() :: {:ok, Jido.Agent.t(), list()} | {:error, Jido.Error.t()}
Functions
@spec run(Jido.Agent.t(), run_opts()) :: run_result()
Executes a single instruction from the Agent's pending instructions queue.
Execution Process
- Dequeues the oldest instruction from the agent's queue
- Creates a new Result struct to track execution
- Executes the instruction through its action module
- Processes any directives from the execution
- Optionally applies state changes
- Returns the updated agent with execution results and server directives
Parameters
agent
- The agent struct containing:pending_instructions
- Queue of pending instructionsstate
- Current agent stateid
- Agent identifier
opts
- Optional keyword list of execution options:apply_directives?
- When true (default), applies directives during executiontimeout
- Timeout in milliseconds for action execution (merged with instruction opts)log_level
- Log level for debugging output
Returns
{:ok, updated_agent, directives}
- Successful execution with:- Updated state map (for state results)
- Updated pending instructions queue
- Any server directives from the execution
{:error, reason}
- Execution failed with:- String error for queue empty condition
- Error struct with details for execution failures
Examples
# Successful state update
{:ok, updated_agent, directives} = Runner.Simple.run(agent_with_state_update)
# Execute without applying directives
{:ok, updated_agent, directives} = Runner.Simple.run(agent_with_state_update, apply_directives?: false)
# Execute with custom timeout (runner opts are merged with instruction opts)
{:ok, updated_agent, directives} = Runner.Simple.run(agent, timeout: 60_000)
# Empty queue - returns agent unchanged
{:ok, agent, []} = Runner.Simple.run(agent_with_empty_queue)
# Execution error
{:error, error} = Runner.Simple.run(agent_with_failing_action)
Option Merging
- Runner options are merged with each instruction's options
- Instruction options take precedence over runner options
- This allows per-instruction customization while providing defaults
Error Handling
- Returns
{:error, "No pending instructions"}
for empty queue - Returns
{:error, error}
with error details for execution failures - All errors preserve the original agent state
- Failed executions do not affect the remaining queue
Logging
Debug logs are emitted at key points:
- Runner start with agent ID
- Instruction dequeue result
- Execution setup and action invocation
- Result processing and categorization