A unified agent orchestration hub that manages heterogeneous AI agents via YAML and exposes them through standardized protocols (ACP/MCP/OpenAI API).
AgentPool is an AI agent orchestration framework developed by phil65, designed to solve heterogenous agent fragmentation, protocol silos, and configuration complexity.
Core Capabilities#
Unified Multi-type Agent Management#
- Native Agents: Pydantic-AI based agents with rich built-in tools
- Claude Code Agents: Direct Claude Code integration for complex refactoring
- Codex Agents: Codex integration with advanced reasoning for code editing
- ACP Agents: External agent integration via ACP protocol (e.g., Goose)
- AG-UI Agents: Custom agents supporting AG-UI protocol
Multi-protocol Exposure#
| Protocol | CLI Command | Use Case |
|---|---|---|
| ACP | agentpool serve-acp | IDE integration, bidirectional communication with tool confirmation |
| OpenCode | agentpool serve-opencode | OpenCode TUI/Desktop, remote filesystem |
| MCP | agentpool serve-mcp | Expose tools to other agents |
| AG-UI | agentpool serve-agui | AG-UI compatible frontends |
| OpenAI API | agentpool serve-api | OpenAI API replacement layer |
Orchestration Capabilities#
- Parallel Teams:
mode: parallel, multi-agent parallel execution - Sequential Chains:
mode: sequential, pipeline-style ordered execution - Python Composition:
agent1 & agent2(parallel),agent1 | agent2(sequential)
Toolset#
File access (local/remote), code pattern analysis (tree-sitter multi-language), Composio integration, execution environment, search, notifications, sub-agent delegation.
Architecture#
| Layer | Technology |
|---|---|
| Agent Framework | Pydantic-AI (pydantic-ai-slim) |
| Web Service | FastAPI + Uvicorn |
| Protocol Support | MCP (fastmcp), ACP, AG-UI, A2A |
| Data Persistence | SQLAlchemy + SQLModel + Alembic |
| Config Parsing | yamling + Pydantic validation |
| CLI | Typer |
| Observability | structlog + logfire |
Module Structure: agentpool (core), agentpool_cli, agentpool_server, agentpool_toolsets, acp, codex_adapter, etc.
Installation & Quick Start#
uv tool install agentpool
Minimal config agents.yml:
agents:
assistant:
type: native
model: openai:gpt-4o
system_prompt: "You are a helpful assistant."
agentpool run assistant "Hello!"
agentpool serve-acp agents.yml
Python API#
from agentpool import AgentPool
async with AgentPool("agents.yml") as pool:
agent = pool.get_agent("assistant")
result = await agent.run("Hello")
async for event in agent.run_stream("Tell me a story"):
print(event)
Multi-agent Configuration Example#
agents:
coordinator:
type: native
model: openai:gpt-4o
tools:
- type: subagent
system_prompt: "Coordinate tasks between available agents."
claude:
type: claude_code
description: "Claude Code for complex refactoring"
codex:
type: codex
model: gpt-5.1-codex-max
reasoning_effort: medium
goose:
type: acp
provider: goose
teams:
review_pipeline:
mode: sequential
members: [analyzer, reviewer, formatter]
parallel_coders:
mode: parallel
members: [claude, goose]
Key Abstractions: MessageNode unified abstraction - all agents/teams/chains share the same interface; YAML-driven configuration with Pydantic backend providing JSON Schema for IDE autocompletion and validation.
Requirements: Python >=3.13, available on PyPI.