Skip to main content

AgentPool

PyPI License Package status Monthly downloads Python version Github Stars

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, Codex for code editing with advanced reasoning, 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), direct integrations (Claude Code, Codex), external ACP agents (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]
            direct[Direct Integrations<br/>Claude Code, Codex]
            acp_agents[ACP Agents<br/>Goose, etc.]
            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]

Quick Start

uv tool install agentpool

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
    tools:
      - type: subagent  # Can delegate to all other agents
    system_prompt: "Coordinate tasks between available agents."

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

  # Codex agent (direct integration)
  codex:
    type: codex
    model: gpt-5.1-codex-max
    reasoning_effort: medium
    description: "Codex for code editing with advanced reasoning"

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

  # 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]
    tools:
      - 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.

Metadata

Release files for agentpool 2.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentpool 2.10.0
File Size Uploaded Provenance Actions
agentpool-2.10.0.tar.gz 10.8 MB With provenance Details for agentpool-2.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentpool 2.10.0
File Interpreter ABI Platform Actions
agentpool-2.10.0-py3-none-any.whl Python 3 none any Details for agentpool-2.10.0-py3-none-any.whl

Total release size: 21.9 MB

Release files / agentpool-2.10.0.tar.gz

Download URL agentpool-2.10.0.tar.gz
Size 10.8 MB
Tags Source
SHA-256 checksum
How to use checksums
af792b4e959dbd94c0a539773077e01e7c10219702922367d9cf003e15974854
BLAKE2b-256 checksum
How to use checksums
0c3ca631d9c6229eba0d148760df17884cea06db321ce01ca478a9c9f5b872f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / agentpool-2.10.0-py3-none-any.whl

Download URL agentpool-2.10.0-py3-none-any.whl
Size 11.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
5d94484b11c20a48cd9677dd8771c14c3305e2efbf593af80bbc6428eebb6745
BLAKE2b-256 checksum
How to use checksums
f3dbb066ef6eeb1df5d53710fd0ab74262adcc9c09f689e41ff26560bc21b92b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for agentpool 2.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentpool-2.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.10.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page