The agent manifest is a YAML file that defines your complete agent setup. The configuration is powered by Pydantic and provides excellent validation and IDE support for YAML linters by providing an extensive, detailed schema.

Top-Level Structure¶

Here's the complete manifest structure with all available top-level sections:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

INHERIT: null  # Inheritance references.
name: null  # Optional name for this manifest.
resources: {}  # Resource configurations defining available filesystems.
agents: {}  # Mapping of agent IDs to their configurations.
default_agent: null  # Name of the default/main agent.
file_agents: {}  # Mapping of agent IDs to file-based agent definitions.
teams: {}  # Mapping of team IDs to their configurations.
storage:  # Storage provider configuration.
  providers: null  # List of configured storage providers
  session_store: sql  # Type of session store to use for session persistence.
  default_provider: null  # Name of default provider for history queries.
  agents: null  # Global agent filter. Can be overridden by provider-specific filters.
  filter_mode: and  # How to combine global and provider agent filters:
  log_messages: true  # Whether to log messages.
  log_sessions: true  # Whether to log conversations.
  log_commands: true  # Whether to log command executions.
  title_generation_model: google-gla:gemini-2.5-flash-lite,openrouter:deepseek/deepseek-r1-0528:free  # Model to use for generating conversation titles.
  title_generation_prompt: 'Generate metadata for this conversation request. Provide:  # Prompt template for generating conversation titles.

    - A short, descriptive title (3-7 words)

    - A single emoji that represents the topic

    - An iconify icon name (e.g., ''mdi:code-braces'', ''mdi:database'', ''mdi:bug'')'
observability:  # Observability provider configuration.
  enabled: true  # Whether observability is enabled.
  provider: null  # Single observability provider configuration.
conversion:  # Document conversion configuration.
  providers: null  # List of configured converter providers.
  default_provider: null  # Name of default provider for conversions.
  max_size: null  # Global size limit for all converters.
responses: {}  # Mapping of response names to their definitions.
model_variants: {}  # Named model variants with pre-configured settings.
jobs: {}  # Pre-defined jobs, ready to be used by nodes.
mcp_servers: []  # List of MCP server configurations:
pool_server:  # Pool server configuration.
  type: mcp  # MCP server type.
  serve_nodes: true  # Which nodes to expose as tools:
  serve_prompts: true  # Which prompts to expose:
  transport: stdio  # Transport type to use.
  host: localhost  # Host to bind server to (SSE / Streamable-HTTP only).
  port: 3001  # Port to listen on (SSE / Streamable-HTTP only).
  cors_origins:  # Allowed CORS origins (SSE / Streamable-HTTP only).
  - '*'
  zed_mode: false  # Enable Zed editor compatibility mode.
  enabled: false  # Whether this server is currently enabled.
prompts:  # Prompt library configuration.
  system_prompts: {}  # Mapping of system prompt identifiers to their definitions.
  template: null  # Optional template for combining prompts.
  providers: []  # List of external prompt providers to use.
commands: {}  # Global command shortcuts for prompt injection.
compaction: null  # Compaction configuration for message history management.

Top-Level Sections¶

agents¶

Dictionary of individual agent configurations. Each key is an agent identifier, and the value is the complete agent configuration.

See Agent Configuration for detailed agent setup options.

teams¶

Dictionary of team configurations for multi-agent workflows. Teams can run agents in parallel or sequence.

See Team Configuration for team setup and coordination.

responses¶

Dictionary of shared response type definitions that can be referenced by agents. Supports both inline schema definitions and imported Python types.

See Response Configuration for structured output setup.

storage¶

Configuration for how agent interactions are stored and logged. Supports multiple storage providers.

See Storage Configuration for persistence and logging options.

observability¶

Configuration for monitoring and telemetry collection.

conversion¶

Settings for document and media conversion capabilities.

mcp_servers¶

Global Model Context Protocol server configurations that provide tools and resources to agents.

See MCP Configuration for server setup and integration.

pool_server¶

Configuration for the pool server that exposes agent functionality to external clients.

prompts¶

Global prompt library configuration and management.

See Prompt Configuration for prompt organization.

commands¶

Global command shortcuts that can be used across agents for prompt injection.

jobs¶

Pre-defined reusable tasks with templates, knowledge requirements, and expected outputs.

See Task Configuration for job definitions.

resources¶

Global resource definitions for filesystems, APIs, and data sources that agents can access.

Configuration Resolution¶

AgentPool uses a layered configuration system inspired by OpenCode. Multiple config files are automatically discovered and deep-merged, allowing you to set global preferences while overriding project-specific settings.

Precedence Order¶

Configs are loaded and merged in this order (later sources override earlier ones):

Project Config Discovery¶

Project config is discovered by searching for agentpool.yml (or .yaml, .json, .jsonc) starting from the current directory and traversing up to the nearest git repository root.

Fallback Behavior¶

The built-in fallback config (e.g., acp_assistant.yml) is only loaded if no agents are defined in any of the other layers. This ensures that:

• Users who define their own agents don't get polluted with default agents
• Users without any config still get a working default assistant

Example: Layered Configuration¶

# User preferences applied everywhere
model_variants:
  fast:
    type: string
    identifier: openai:gpt-4o-mini
  smart:
    type: anthropic
    identifier: claude-sonnet-4-5

storage:
  provider: sql
  database_url: sqlite:///~/.local/share/agentpool/history.db

# Project-specific agents (inherits global model_variants and storage)
agents:
  coder:
    model: smart  # References global variant
    system_prompt: "You are an expert Python developer."
    tools:
      - type: file_access
      - type: bash

Environment Variables¶

CLI Commands¶

Use these commands to inspect config resolution:

# Show which configs are found and loaded
agentpool config show

# Show standard config paths
agentpool config paths

# Create a starter config file
agentpool config init           # In current project
agentpool config init global    # In global config dir

File-Level Inheritance (INHERIT)¶

In addition to layered resolution, individual config files can use the INHERIT key to explicitly inherit from another file:

storage:
  log_messages: true
agents:
  base_agent:
    model: "openai:gpt-5"
    retries: 2

INHERIT: base-config.yml
agents:
  my_agent:
    model: openai:gpt-5
    description: "Specialized agent"

AgentPool supports UPaths (universal-pathlib) for INHERIT, allowing pointing to remote configurations (http://path/to/config.yml).

Schema Validation¶

You can get IDE linter support by adding this line at the top of your YAML:

# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json

Usage¶

Load a manifest in your code:

from agentpool import AgentPool

async with AgentPool("agents.yml") as pool:
    agent = pool.get_agent("analyzer")
    result = await agent.run("Analyze this code...")