View Source Jido.Command.Manager (Jido v1.0.0-rc.4)

Manages command registration and dispatch for Agents.

The Command Manager maintains an immutable state of registered commands and their specifications, handling validation and dispatch of commands to the appropriate handlers.

Usage 

# Create a new manager
manager = Manager.new()

# Register command modules
{:ok, manager} = Manager.register(manager, MyApp.ChatCommand)
{:ok, manager} = Manager.register(manager, MyApp.ImageCommand)

# Dispatch commands
{:ok, actions} = Manager.dispatch(manager, :generate_text, agent, %{
  prompt: "Hello!"
})

Command Validation

All commands are validated at registration time:

  • Command names must be unique across all modules
  • Command specs must include description and schema
  • Parameter schemas are validated using NimbleOptions

Error Handling

The manager provides detailed error messages for:

  • Invalid command specifications
  • Duplicate command registration
  • Missing commands
  • Invalid parameters
  • Command execution failures

Summary

Types

command_entry()
command_info()
dispatch_error()
t()

Manager state containing

Functions

dispatch(manager, command, agent, params \\ %{})

Dispatches a command to its registered handler.

new()

Creates a new Manager instance

register(manager, command_module)

Registers a command module with the manager. Validates command specifications and stores them for dispatch.

registered_commands(manager)

Returns list of registered commands with their specifications

registered_modules(manager)

Returns list of registered command modules

setup(modules, opts \\ [])

Sets up a new Command Manager with the given command modules. Optionally registers the Default command set first if specified.

Types

command_entry()

@type command_entry() :: {module(), keyword()}

command_info()

@type command_info() :: %{
  module: module(),
  description: String.t(),
  schema: NimbleOptions.t() | nil
}

dispatch_error()

@type dispatch_error() ::
  {:error, :command_not_found | :invalid_params | :execution_failed, String.t()}

t()

@type t() :: %Jido.Command.Manager{commands: %{optional(atom()) => command_info()}}

Manager state containing:

  • commands: Map of command names to their full specifications

Functions

dispatch(manager, command, agent, params \\ %{})

@spec dispatch(t(), atom(), Jido.Agent.t(), map()) ::
  {:ok, [Jido.Agent.action()]} | dispatch_error()

Dispatches a command to its registered handler.

Parameters

  • manager: The Manager state
  • command: Atom name of command to execute
  • agent: Current Agent state
  • params: Command parameters (will be validated)

Returns

  • {:ok, actions} - List of actions to execute
  • {:error, reason} - Detailed error description

Examples 

iex> Manager.dispatch(manager, :generate_text, agent, %{
...>   prompt: "Hello!"
...> })
{:ok, [{TextGeneration, %{prompt: "Hello!"}}]}

iex> Manager.dispatch(manager, :unknown, agent, %{})
{:error, :command_not_found, "Command :unknown not found"}

new()

@spec new() :: t()

Creates a new Manager instance

register(manager, command_module)

@spec register(t(), module()) :: {:ok, t()} | {:error, String.t()}

Registers a command module with the manager. Validates command specifications and stores them for dispatch.

Returns {:ok, updated_manager} or {:error, reason}

registered_commands(manager)

@spec registered_commands(t()) :: [{atom(), keyword()}]

Returns list of registered commands with their specifications

registered_modules(manager)

@spec registered_modules(t()) :: [module()]

Returns list of registered command modules

setup(modules, opts \\ [])

@spec setup(
  [module()],
  keyword()
) :: {:ok, t()} | {:error, String.t()}

Sets up a new Command Manager with the given command modules. Optionally registers the Default command set first if specified.

Parameters

  • modules: List of command modules to register
  • opts: Options for setup
    • register_default: Whether to register Jido.Commands.Default first (default: true)

Returns

  • {:ok, manager} - Successfully initialized manager
  • {:error, reason} - Error during initialization