pydantic-collab
pydantic-collab is a Python library for building AI agent teams that collaborate through handoffs, tool calls, and shared memory. It solves the problem of coordinating multiple specialized agents in complex workflows without human intervention. It is for developers using Pydantic-AI who need multi-agent orchestration.
✨ Key features
- Tool calls and handoffs between agents
- Pre-built topologies: Pipeline, Star, Mesh, custom
- Shared agent memory for persistent context
- Topology visualization as an image
- Pydantic-AI native with Logfire observability
- Configurable context passing and prompt builder
🎯 Use cases
- Multi-stage workflows like incident triage and response
- Specialist teams with coordinator and domain experts
- Tasks requiring different perspectives (engineering, legal, security)
- Iterative refinement loops like drafter-critic
- Vendor evaluation with cross-consultation among reviewers
📦 Installation
🧰 Requirements: Requires Python and installation of pydantic-collab; model names like openai:gpt-5.2-pro imply API keys for the respective providers.
pip install pydantic-collab
For visualization, install with extra dependencies:
pip install pydantic-collab[viz]
🚀 Usage
from pydantic_collab import PipelineCollab, CollabAgent
collab = PipelineCollab(
agents=[
CollabAgent(name="Triager", system_prompt="Classify the support ticket by product area and urgency (P0-P3). Extract the core issue."),
CollabAgent(name="Responder", system_prompt="Draft a helpful response. Acknowledge the issue, provide next steps or workarounds."),
],
model="anthropic:claude-sonnet-4-5",
)
result = collab.run_sync("User email: 'I can't export my data to CSV, the button just spins forever. I need this for a board meeting tomorrow!'")
print(result.output)
❓ FAQ
What is the difference between tool calls and handoffs?
Tool calls (agent_calls) let an agent get help while staying in control, and the caller continues after the call. Handoffs (agent_handoffs) transfer control completely, and the caller stops.
How do I share memory between agents?
Use AgentMemory objects and assign them to agents with permissions like 'rw' or 'r' via the memory parameter. Agents can read and write to shared memory during a run.
Can I visualize the agent topology?
Yes, call collab.visualize_topology() to open an image, or pass save_path and show=False to save it to a file. Requires installing pydantic-collab[viz].
How do I add custom tools for agents?
Define async functions and decorate them with @collab.tool_plain. You can restrict tools to specific agents by passing agents=("AgentName",) to the decorator.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.