AgentPool

A unified agent orchestration hub that lets you configure and manage heterogeneous AI agents via YAML and expose them through standardized protocols.

Documentation

The Problem

You want to use multiple AI agents together - Claude Code for refactoring, a custom analysis agent, maybe Goose for specific tasks. But each has different APIs, protocols, and integration patterns. Coordinating them means writing glue code for each combination.

The Solution

AgentPool acts as a protocol bridge. Define all your agents in one YAML file - whether they're native (PydanticAI-based), external ACP agents (Claude Code, Codex, Goose), or AG-UI agents. Then expose them all through ACP or AG-UI protocols, letting them cooperate, delegate, and communicate through a unified interface.

flowchart TB
    subgraph AgentPool
        subgraph config[YAML Configuration]
            native[Native Agents<br/>PydanticAI]
            acp_agents[ACP Agents<br/>Claude Code, Goose, Codex]
            agui_agents[AG-UI Agents]
            workflows[Teams & Workflows]
        end
        
        subgraph interface[Unified Agent Interface]
            delegation[Inter-agent delegation]
            routing[Message routing]
            context[Shared context]
        end
        
        config --> interface
    end
    
    interface --> acp_server[ACP Server]
    interface --> opencode_server[OpenCode Server]
    interface --> agui_server[AG-UI Server]
    
    acp_server --> clients1[Zed, Toad, ACP Clients]
    opencode_server --> clients2[OpenCode TUI/Desktop]
    agui_server --> clients3[AG-UI Clients]

Loading

Quick Start

uv tool install agentpool[default]

Minimal Configuration

# agents.yml
agents:
  assistant:
    type: native
    model: openai:gpt-4o
    system_prompt: "You are a helpful assistant."

# Run via CLI
agentpool run assistant "Hello!"

# Or start as ACP server (for Zed, Toad, etc.)
agentpool serve-acp agents.yml

Integrating External Agents

The real power comes from mixing agent types:

agents:
  # Native PydanticAI-based agent
  coordinator:
    type: native
    model: openai:gpt-4o
    toolsets:
      - type: subagent  # Can delegate to all other agents
    system_prompt: "Coordinate tasks between available agents."

  # Claude Code agent (direct integration)
  claude:
    type: claude
    description: "Claude Code for complex refactoring"

  # ACP protocol agents
  goose:
    type: acp
    provider: goose
    description: "Goose for file operations"

  codex:
    type: acp
    provider: codex
    description: "OpenAI Codex agent"

  # AG-UI protocol agent
  agui_agent:
    type: agui
    url: "http://localhost:8000"
    description: "Custom AG-UI agent"

Now coordinator can delegate work to any of these agents, and all are accessible through the same interface.

Key Features

Multi-Agent Coordination

Agents can form teams (parallel) or chains (sequential):

teams:
  review_pipeline:
    mode: sequential
    members: [analyzer, reviewer, formatter]

  parallel_coders:
    mode: parallel
    members: [claude, goose]

async with AgentPool("agents.yml") as pool:
    # Parallel execution
    team = pool.get_agent("analyzer") & pool.get_agent("reviewer")
    results = await team.run("Review this code")

    # Sequential pipeline
    chain = analyzer | reviewer | formatter
    result = await chain.run("Process this")

Rich YAML Configuration

Everything is configurable - models, tools, connections, triggers, storage:

agents:
  analyzer:
    type: native
    model:
      type: fallback
      models: [openai:gpt-4o, anthropic:claude-sonnet-4-0]
    toolsets:
      - type: subagent
      - type: resource_access
    mcp_servers:
      - "uvx mcp-server-filesystem"
    knowledge:
      paths: ["docs/**/*.md"]
    connections:
      - type: node
        name: reporter
        filter_condition:
          type: word_match
          words: [error, warning]

Server Protocols

AgentPool can expose your agents through multiple server protocols:

Server	Command	Use Case
ACP	agentpool serve-acp	IDE integration (Zed, Toad) - bidirectional communication with tool confirmations
OpenCode	agentpool serve-opencode	OpenCode TUI/Desktop - supports remote filesystems via fsspec
MCP	agentpool serve-mcp	Expose tools to other agents
AG-UI	agentpool serve-agui	AG-UI compatible frontends
OpenAI API	agentpool serve-api	Drop-in OpenAI API replacement

The ACP server is ideal for IDE integration - it provides real-time tool confirmations and session management. The OpenCode server enables the OpenCode TUI to control AgentPool agents, including agents operating on remote environments (Docker, SSH, cloud sandboxes).

Additional Capabilities

• Structured Output: Define response schemas inline or import Python types
• Storage & Analytics: Track all interactions with configurable providers
• File Abstraction: UPath-backed operations work on local and remote sources
• Triggers: React to file changes, webhooks, or custom events
• Streaming TTS: Voice output support for all agents

Usage Patterns

CLI

agentpool run agent_name "prompt"           # Single run
agentpool serve-acp config.yml              # ACP server for IDEs
agentpool serve-opencode config.yml         # OpenCode TUI server
agentpool serve-mcp config.yml              # MCP server
agentpool watch --config agents.yml         # React to triggers
agentpool history stats --group-by model    # View analytics

Programmatic

from agentpool import AgentPool

async with AgentPool("agents.yml") as pool:
    agent = pool.get_agent("assistant")

    # Simple run
    result = await agent.run("Hello")

    # Streaming
    async for event in agent.run_stream("Tell me a story"):
        print(event)

    # Multi-modal
    result = await agent.run("Describe this", Path("image.jpg"))

Documentation

For complete documentation including advanced configuration, connection patterns, and API reference, visit phil65.github.io/agentpool.