Defines an Agent within the Jido system - a compile-time defined entity for managing complex workflows through a sequence of Actions.

Overview

An Agent represents a stateful workflow executor that can plan and execute a series of Actions in a type-safe and composable way. Agents provide a consistent interface for orchestrating complex operations while maintaining state validation, error handling, and extensibility through lifecycle hooks.

Architecture

Key Concepts

• Agents are defined at compile-time using the use Jido.Agent macro
• Each Agent instance is created at server with a guaranteed unique ID
• Agents maintain their own state schema for validation
• Actions are registered with Agents and executed through a Runner
• Lifecycle hooks enable customization of validation, planning and execution flows

• All operations follow a consistent pattern returning {:ok, result} | {:error, reason}

Type Safety & Validation

• Configuration validated at compile-time via NimbleOptions
• Server state changes validated against defined schema
• Action modules checked for behavior implementation
• Consistent return type enforcement across operations

Features

• Compile-time configuration validation
• Server parameter validation via NimbleOptions
• Comprehensive error handling with recovery hooks
• Extensible lifecycle callbacks for all operations
• JSON serialization support for persistence
• Dynamic Action planning and execution
• State management with validation and dirty tracking

Usage

Basic Example

defmodule MyAgent do
  use Jido.Agent,
    name: "my_agent",
    description: "Performs a complex workflow",
    category: "processing",
    tags: ["example", "demo"],
    vsn: "1.0.0",
    schema: [
      input: [type: :string, required: true],
      status: [type: :atom, values: [:pending, :running, :complete]]
    ],
    actions: [MyAction1, MyAction2]
end

# Create and configure agent
{:ok, agent} = MyAgent.new()
{:ok, agent} = MyAgent.set(agent, input: "test data")

# Plan and execute actions
{:ok, agent} = MyAgent.plan(agent, MyAction1, %{value: 1})
{:ok, agent} = MyAgent.run(agent)  # Result stored in agent.result

Customizing Behavior

defmodule CustomAgent do
  use Jido.Agent,
    name: "custom_agent",
    schema: [status: [type: :atom]]

  # Add pre-execution validation
  def on_before_run(agent) do
    if agent.state.status == :ready do
      {:ok, agent}
    else
      {:error, "Agent not ready"}
    end
  end

  # Custom error recovery
  def on_error(agent, error) do
    Logger.warning("Agent error", error: error)
    {:ok, %{agent | state: %{status: :error}}}
  end
end

Callbacks

The following optional callbacks can be implemented to customize agent behavior. All callbacks receive the agent struct and return {:ok, agent} | {:error, reason}.

• on_before_validate_state/1 - Pre-validation processing
• on_after_validate_state/1 - Post-validation processing
• on_before_plan/3 - Pre-planning processing with params
• on_before_run/1 - Pre-execution validation/setup
• on_after_run/2 - Post-execution processing
• on_after_directives/2 - Post-directive application
• on_error/2 - Error handling and recovery

Default implementations pass through the agent unchanged.

Important Notes

Each Agent module defines its own struct type and behavior. Agent functions must be called on matching agent structs:

# Correct usage: agent = MyAgent.new() {:ok, agent} = MyAgent.set(agent, attrs)

# Incorrect usage: agent = MyAgent.new() {:ok, agent} = OtherAgent.set(agent, attrs) # Will fail - type mismatch

Runner Architecture

The Runner executes actions in the agent's pending_instructions queue.

• Default implementation: Jido.Runner.Simple
• Custom runners must implement the Jido.Runner behavior
• Runners handle instruction execution and state management
• Support for different execution strategies (simple, chain, parallel)

Error Handling

Errors are returned as tagged tuples: {:error, reason}

Common error types:

• :validation_error - Schema/parameter validation failures
• :execution_error - Action execution failures
• :directive_error - Directive application failures

See Jido.Action for implementing compatible Actions.

Type Specifications

• t() - The Agent struct type
• instruction() - Single action with params
• instructions() - List of instructions

• agent_result() - {:ok, t()} | {:error, term()}