View Source Jido.Agent behaviour (Jido v1.0.0-rc.4)

Defines an Agent within the Jido system.

An Agent represents a higher-level entity that can plan and execute a series of Actions. Agents are defined at compile-time and provide a consistent interface for planning, executing, and managing complex workflows. Agents can be extended with Command plugins that package pre-defined sequences of Actions.

Features

  • Compile-time configuration validation
  • Runtime input parameter validation
  • Consistent error handling and formatting
  • Extensible lifecycle hooks
  • JSON serialization support
  • Plugin support for pre-defined sequences of Actions
  • Dynamic planning and execution of Action sequences

Usage

To define a new Agent, use the Jido.Agent behavior in your module:

defmodule MyAgent do
  use Jido.Agent,
    name: "my_agent",
    description: "Performs a complex workflow",
    category: "processing",
    tags: ["example", "demo"],
    vsn: "1.0.0",
    commands: [MyCommand1, MyCommand2]
    schema: [
      input: [type: :string, required: true]
    ]
end

Optional Overrides

Implementing modules must define the following callback:

  • c:plan/1: Generates a plan (sequence of Actions) for the Agent to execute.

Summary

Types

action()
t()

Callbacks

on_after_run(agent, result)

Called after successful command execution. Allows post-processing of execution results.

on_after_validate_state(state)

Called after state validation but before saving changes. Allows post-processing of validated state.

on_before_plan(agent, command, params)

Called before planning commands, allows preprocessing of command parameters and potential command routing/transformation.

on_before_run(agent, actions)

Called after command planning but before execution. Allows inspection/modification of planned actions.

on_before_validate_state(state)

Called before validating any state changes to the Agent. Allows custom preprocessing of state attributes.

on_error(agent, error, context)

Called when any error occurs during the agent lifecycle. Provides error handling and recovery strategies.

Functions

new()

Raises an error indicating that Agents cannot be defined at runtime.

new(map_or_kwlist)

Types

action()

@type action() :: module() | {module(), map()}

t()

@type t() :: %Jido.Agent{
  category: String.t() | nil,
  command_manager: Jido.Command.Manager.t() | nil,
  commands: [atom()] | nil,
  description: String.t() | nil,
  dirty_state?: boolean() | nil,
  id: String.t() | nil,
  name: String.t() | nil,
  pending: :queue.queue(action()) | nil,
  result: term(),
  runner: module() | nil,
  schema: NimbleOptions.schema() | nil,
  state: map(),
  tags: [String.t()] | nil,
  vsn: String.t() | nil
}

Callbacks

on_after_run(agent, result)

@callback on_after_run(agent :: t(), result :: map()) :: {:ok, map()} | {:error, any()}

Called after successful command execution. Allows post-processing of execution results.

on_after_validate_state(state)

@callback on_after_validate_state(state :: map()) :: {:ok, map()} | {:error, any()}

Called after state validation but before saving changes. Allows post-processing of validated state.

on_before_plan(agent, command, params)

@callback on_before_plan(agent :: t(), command :: atom(), params :: map()) ::
  {:ok, {atom(), map()}} | {:error, any()}

Called before planning commands, allows preprocessing of command parameters and potential command routing/transformation.

on_before_run(agent, actions)

@callback on_before_run(agent :: t(), actions :: [{module(), map()}]) ::
  {:ok, [{module(), map()}]} | {:error, any()}

Called after command planning but before execution. Allows inspection/modification of planned actions.

on_before_validate_state(state)

@callback on_before_validate_state(state :: map()) :: {:ok, map()} | {:error, any()}

Called before validating any state changes to the Agent. Allows custom preprocessing of state attributes.

on_error(agent, error, context)

@callback on_error(agent :: t(), error :: any(), context :: map()) ::
  {:ok, t()} | {:error, any()}

Called when any error occurs during the agent lifecycle. Provides error handling and recovery strategies.

Functions

new()

@spec new() :: {:error, Jido.Error.t()}

Raises an error indicating that Agents cannot be defined at runtime.

This function exists to prevent misuse of the Agent system, as Agents are designed to be defined at compile-time only.

Returns

Always returns {:error, reason} where reason is a config error.

Examples 

iex> Jido.Agent.new()
{:error, %Jido.Error{type: :config_error, message: "Agents should not be defined at runtime"}}

new(map_or_kwlist)

@spec new(map() | keyword()) :: {:error, Jido.Error.t()}