Jido.Runner.Simple (Jido v1.1.0-rc)

View Source

A simple runner that executes a single instruction from an Agent's instruction queue.

Overview

The Simple Runner follows a sequential execution model:

  1. Dequeues a single instruction from the agent's pending queue
  2. Executes the instruction via its action module
  3. Processes the result (either a state update, directive or both)
  4. Applies state changes if configured
  5. 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

Types

run_opts()
run_result()

Functions

run(agent, opts \\ [])

Executes a single instruction from the Agent's pending instructions queue.

Types

run_opts()

@type run_opts() :: [{:apply_state, boolean()}]

run_result()

@type run_result() :: {:ok, Jido.Agent.t(), list()} | {:error, Jido.Error.t()}

Functions

run(agent, opts \\ [])

@spec run(Jido.Agent.t(), run_opts()) :: run_result()

Executes a single instruction from the Agent's pending instructions queue.

Execution Process

  1. Dequeues the oldest instruction from the agent's queue
  2. Creates a new Result struct to track execution
  3. Executes the instruction through its action module
  4. Processes any directives from the execution
  5. Optionally applies state changes
  6. Returns the updated agent with execution results and server directives

Parameters

  • agent - The agent struct containing:
    • pending_instructions - Queue of pending instructions
    • state - Current agent state
    • id - Agent identifier
  • opts - Optional keyword list of execution options:
    • apply_state - Whether to apply state changes (default: true)

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 state
{:ok, updated_agent, directives} = Runner.Simple.run(agent_with_state_update, apply_state: false)

# 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)

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 workflow invocation
  • Result processing and categorization