View Source Jido.Runner.Simple (Jido v1.0.0)

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 directive, syscall or state update)
  4. Returns a Result struct containing the execution outcome

Features

  • Single instruction execution
  • Support for directives, syscalls and state results
  • Atomic execution guarantees
  • Comprehensive error handling
  • Debug logging at key execution points

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

dbug(_, _ \\ [], _ \\ [])
error(_, _ \\ [], _ \\ [])
run(agent, opts \\ [])

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

Types

run_opts()

@type run_opts() :: keyword()

run_result()

@type run_result() ::
  {:ok, Jido.Runner.Result.t()} | {:error, Jido.Error.t() | String.t()}

Functions

dbug(_, _ \\ [], _ \\ [])

(macro)

error(_, _ \\ [], _ \\ [])

(macro)

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 the execution result (directive, syscall or state)
  5. Returns the final Result struct

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:
    • Currently unused but reserved for future extensions

Returns

  • {:ok, %Result{}} - Successful execution with:
    • result_state - Updated state map (for state results)
    • directives - List of directives (for directive results)
    • syscalls - List of syscalls (for syscall results)
    • status - Set to :ok
    • error - Set to nil
  • {:error, reason} - Execution failed with:
    • String error for queue empty condition
    • Result struct with error details for execution failures

Examples 

# Successful state update
{:ok, %Result{result_state: %{status: :complete}}} =
  Runner.Simple.run(agent_with_state_update)

# Successful directive
{:ok, %Result{directives: [%EnqueueDirective{...}]}} =
  Runner.Simple.run(agent_with_directive)

# Successful syscall
{:ok, %Result{syscalls: [%SpawnSyscall{...}]}} =
  Runner.Simple.run(agent_with_syscall)

# Empty queue error
{:error, "No pending instructions"} =
  Runner.Simple.run(agent_with_empty_queue)

# Execution error
{:error, %Result{error: error, status: :error}} =
  Runner.Simple.run(agent_with_failing_action)

Error Handling

  • Returns {:error, "No pending instructions"} for empty queue
  • Returns {:error, %Result{}} 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