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.9.22

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.9.22
File Size Uploaded Provenance Actions
agentpool-2.9.22.tar.gz 10.9 MB Without provenance Details for agentpool-2.9.22.tar.gz

Built distribution (wheel)

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

Total release size: 22.1 MB

Release files / agentpool-2.9.22.tar.gz

Download URL agentpool-2.9.22.tar.gz
Size 10.9 MB
Tags Source
SHA-256 checksum
How to use checksums
2e6b948fdce4aa2e00cbd5ec6eefe0cbf62a03e665547c38b3eb9a6e1bde11ae
BLAKE2b-256 checksum
How to use checksums
3b6549811d4ca8dab05dd07143ece235fb3b420564e85bc8a7f480bcf8b5b25f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

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

Download URL agentpool-2.9.22-py3-none-any.whl
Size 11.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f78a6bba4b2b9c1bc3f7278400b3d64ef34722de07257797e7bc67789070a981
BLAKE2b-256 checksum
How to use checksums
326d66911293b92daf4c1f19d373d4aa56d668aba2fd55d5933dacafb392ef46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for agentpool 2.9.22

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.9.22 This release

2 release files No 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