Core Concepts¶
This section covers the fundamental concepts you need to understand when working with Subagents for Pydantic AI.
Overview¶
The library is built around three core concepts:
- Subagents - Specialized agents that handle specific tasks
- Toolset - The bridge that connects your parent agent to subagents
- Types - Data structures for configuration and communication
How It Works¶
Text Only
┌─────────────────────────────────────────────────────────┐
│ Parent Agent │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Subagent Toolset │ │
│ │ task() │ check_task() │ answer_subagent() │ │
│ └─────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ researcher │ │ writer │ │ coder │ │
│ │ (sync) │ │ (async) │ │ (auto) │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │
│ Message Bus (pluggable) │
└─────────────────────────────────────────────────────────┘
- You define SubAgentConfigs with name, description, and instructions
- The toolset factory creates a toolset with delegation tools
- Your parent agent uses tools like
task()to delegate work - Subagents execute the work and return results
- The message bus handles communication (questions, answers, status)