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

View Source

A runner that executes instructions sequentially with support for result chaining and directive-based interruption.

Chain Execution

Instructions are executed in sequence with the output of each instruction becoming the input for the next instruction in the chain. This enables data flow between instructions while maintaining state consistency.

Directive Handling

The chain supports directive-based flow control:

  • Directives are accumulated and added to the final queue
  • State changes and directives can be mixed in the chain
  • Directives do not interrupt chain execution

State Management

  • Initial state flows through the chain
  • Each instruction can modify or extend the state
  • Final state reflects accumulated changes
  • Directives are added to the final queue

Summary

Types

chain_opts()
chain_result()

Functions

run(agent, opts \\ [])

Executes a chain of instructions, handling directives and state transitions.

Types

chain_opts()

@type chain_opts() :: [{:continue_on_directive, boolean()}]

chain_result()

@type chain_result() ::
  {:ok, Jido.Agent.t(), [Jido.Agent.Directive.t()]}
  | {:error, Jido.Error.t() | String.t()}

Functions

run(agent, opts \\ [])

@spec run(Jido.Agent.t(), chain_opts()) :: chain_result()

Executes a chain of instructions, handling directives and state transitions.

Execution Flow

  1. Instructions are executed in sequence
  2. Results from each instruction feed into the next
  3. Directives are accumulated throughout the chain
  4. At the end of the chain:
    • Agent directives are applied to the agent
    • Server directives are returned with the result

Parameters

  • agent: The agent struct containing pending instructions
  • opts: Optional keyword list of execution options:
    • :merge_results - boolean, merges map results into subsequent instruction params (default: true)

Returns

  • {:ok, updated_agent, server_directives} - Chain completed successfully
    • Updated state map
    • Queue containing any directives from execution
    • List of server directives
  • {:error, error} - Chain execution failed
    • Contains error details

Examples 

# Basic chain execution
{:ok, updated_agent, server_directives} = Chain.run(agent)

# Handle execution error
{:error, error} = Chain.run(agent_with_failing_instruction)