agentpool

# AgentPool [](https://pypi.org/project/agentpool/) [](https://pypi.org/project/agentpool/) [](https://pypi.org/project/agentpool/) [](https://pypi.org/project/agentpool/) [](https://github.com/phil65/agentpool/stars) **A unified agent orchestration hub that lets you configure and manage heterogeneous AI agents via YAML and expose them through standardized protocols.** [Documentation](https://phil65.github.io/agentpool/) ## 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. ```mermaid 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 ```bash uv tool install agentpool ``` ### Minimal Configuration ```yaml # agents.yml agents: assistant: type: native model: openai:gpt-4o system_prompt: "You are a helpful assistant." ``` ```bash # 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: ```yaml 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): ```yaml teams: review_pipeline: mode: sequential members: [analyzer, reviewer, formatter] parallel_coders: mode: parallel members: [claude, goose] ``` ```python 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: ```yaml 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 ```bash 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 ```python 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](https://phil65.github.io/agentpool/).