How to Configure AgentServer with Custom Options like max_queue_size in Jido

To configure AgentServer with custom options like max_queue_size, pass a keyword list or map to Jido.AgentServer.start_link/1, where options are validated by Jido.AgentServer.Options.new/1 and stored in the server's internal state.

Jido.AgentServer is the core GenServer that runs Jido agents in the agentjido/jido repository. All runtime behavior—from queue management to error handling—is driven by the options passed at startup. Understanding how to configure these options allows you to optimize agent performance for production workloads.

Understanding AgentServer Configuration Options

The options schema is defined in lib/jido/agent_server/options.ex and validated through Options.new/1. When starting an AgentServer, you can pass any combination of these parameters:

Option	Description	Default
:max_queue_size	Upper bound for the directive queue length. When exceeded, new directives are dropped with a :queue_overflow warning.	10_000
:error_policy	Error handling strategy: :log_only, :stop_on_error, {:emit_signal, cfg}, {:max_errors, n}, or a custom 2-arity function.	:log_only
:debug	Enables an in-memory ring-buffer of recent events for troubleshooting.	false
:idle_timeout	Milliseconds of inactivity before hibernation or stop (:infinity disables).	:infinity
:register_global	Registers the agent ID in the global Jido.Registry on start.	true

How to Configure max_queue_size and Other Options

Basic Configuration with max_queue_size

Pass options directly to start_link/1 as a keyword list:

{:ok, pid} =
  Jido.AgentServer.start_link(
    agent: MyApp.Agent,
    id: "my-agent",
    max_queue_size: 5_000  # Lower from default 10,000

  )

Loading Configuration from a Map

When loading settings from application config or external sources, use a map:

config = %{
  agent: MyApp.Agent,
  jido: MyApp.Jido,          # Custom Jido instance (optional)

  max_queue_size: 2_000,
  error_policy: {:max_errors, 3},
  debug: true,
  idle_timeout: 60_000        # 1 minute of inactivity → hibernate

}

{:ok, pid} = Jido.AgentServer.start_link(config)

Runtime Configuration Inspection

Verify effective settings after startup:

{:ok, state} = Jido.AgentServer.state(pid)
IO.inspect(state.max_queue_size)   # => 5_000

IO.inspect(state.debug)            # => false

How Configuration Flows Through the System

Understanding the internal flow helps debug configuration issues. The options travel through three key modules:

1. Public API Entry Point (lib/jido/agent_server.ex, lines 22-25)

The start_link/1 function extracts GenServer-specific options (like :name) and forwards the rest:

def start_link(opts) do
  {genserver_opts, agent_opts} = extract_genserver_opts(opts)
  GenServer.start_link(__MODULE__, agent_opts, genserver_opts)
end

2. Validation and Normalization (lib/jido/agent_server.ex, lines 54-58)

During init/1, options are validated through Options.new/1:

with {:ok, options} <- Options.new(opts),
     {:ok, agent_mod, agent} <- resolve_agent(options),
     {:ok, state} <- State.from_options(options, agent_mod, agent) do

3. State Construction and Enforcement (lib/jido/agent_server/state.ex, lines 40-44 and 86-92)

The State.from_options/3 function stores max_queue_size in the internal struct. The State.enqueue/3 function enforces the limit:

# State storage (state.ex lines 40-44)

%{
  max_queue_size: opts.max_queue_size,
  # ...

}

# Queue enforcement (state.ex lines 86-92)

def enqueue(%State{} = state, directive, opts) do
  if queue_length(state) >= state.max_queue_size do
    {:error, :queue_overflow}
  else
    # ... add to queue

  end
end

Handling Queue Overflow and Runtime Monitoring

When the directive queue exceeds max_queue_size, the server returns {:error, :queue_overflow}. Handle this in your application code:

case Jido.AgentServer.call(pid, some_signal) do
  {:ok, agent} -> 
    :ok
    
  {:error, :queue_overflow} ->
    Logger.warning("Agent queue full – consider increasing :max_queue_size")
    :retry_later
end

Enable the :debug option to access the in-memory ring buffer for troubleshooting queue buildup without affecting production performance.

Summary

• Configuration entry point: Pass options to Jido.AgentServer.start_link/1 as keyword lists or maps.
• Validation: Options are validated by Jido.AgentServer.Options.new/1 before the server starts.
• Key options: max_queue_size (default 10,000), error_policy, debug, and idle_timeout control core behaviors.
• Internal flow: Options flow from agent_server.ex through state.ex, where max_queue_size is enforced during State.enqueue/3.
• Overflow handling: When the queue limit is reached, operations return {:error, :queue_overflow}.

Frequently Asked Questions

What is the default max_queue_size in Jido AgentServer?

The default max_queue_size is 10,000 directives. This value is defined in lib/jido/agent_server/options.ex and represents the upper bound before new directives are dropped with a :queue_overflow warning.

How do I change AgentServer options at runtime?

AgentServer options are immutable after startup. To change configuration values like max_queue_size, you must stop the current server with Jido.AgentServer.stop/1 and start a new instance with the updated options via start_link/1.

What happens when the directive queue exceeds max_queue_size?

When the queue reaches the configured limit, State.enqueue/3 in lib/jido/agent_server/state.ex returns {:error, :queue_overflow}. The calling process receives this error tuple, allowing you to implement backoff strategies or logging rather than crashing the agent.

Where are AgentServer options defined in the source code?

The option schema, defaults, and validation logic are defined in lib/jido/agent_server/options.ex. The Options.new/1 function validates incoming maps or keyword lists against this schema before the server initializes in lib/jido/agent_server.ex.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}