# How to Configure AgentServer with Custom Options like max_queue_size in Jido

> Learn how to configure AgentServer with custom options like max_queue_size in Jido. Pass a keyword list or map to Jido.AgentServer.start_link/1 for your server's internal state.

- Repository: [agentjido/jido](https://github.com/agentjido/jido)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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](https://github.com/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`](https://github.com/agentjido/jido/blob/main/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:

```elixir
{: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:

```elixir
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:

```elixir
{: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`](https://github.com/agentjido/jido/blob/main/lib/jido/agent_server.ex), lines 22-25)

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

```elixir
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`](https://github.com/agentjido/jido/blob/main/lib/jido/agent_server.ex), lines 54-58)

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

```elixir
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`](https://github.com/agentjido/jido/blob/main/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:

```elixir

# 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:

```elixir
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`](https://github.com/agentjido/jido/blob/main/agent_server.ex) through [`state.ex`](https://github.com/agentjido/jido/blob/main/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`](https://github.com/agentjido/jido/blob/main/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`](https://github.com/agentjido/jido/blob/main/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`](https://github.com/agentjido/jido/blob/main/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`](https://github.com/agentjido/jido/blob/main/lib/jido/agent_server.ex).