cianfhoghlaim/cianchosaint / .agents/skills/pydantic/building-pydantic-ai-agents
building-pydantic-ai-agents
VerifiedBuild AI agents with Pydantic AI — tools, capabilities (including on-demand loading), structured output, streaming, testing, and multi-agent patterns. Use when the user mentions Pydantic AI, imports pydantic_ai, or asks to build an AI agent, add tools/capabilities, defer capability loading, stream output, define agents from YAML, or test agent behavior.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| references/AGENTS-CORE.md | markdown | 4.1 KB |
| references/ARCHITECTURE.md | markdown | 11.9 KB |
| references/CAPABILITIES-AND-HOOKS.md | markdown | 3.5 KB |
| references/COMMON-TASKS.md | markdown | 4.7 KB |
| references/INPUT-AND-HISTORY.md | markdown | 3.7 KB |
| references/NATIVE-TOOLS.md | markdown | 2.6 KB |
| references/ON-DEMAND-CAPABILITIES.md | markdown | 7.4 KB |
| references/ORCHESTRATION-AND-INTEGRATIONS.md | markdown | 3.2 KB |
| references/TESTING-AND-DEBUGGING.md | markdown | 2.4 KB |
| references/TOOLS-ADVANCED.md | markdown | 6.1 KB |
| references/TOOLS-CORE.md | markdown | 3.5 KB |
references/CAPABILITIES-AND-HOOKS.md
View on GitHub# Capabilities and Hooks
Read this file when the user wants reusable agent behavior, provider-adaptive tools, or lifecycle interception.
## Add Capabilities to an Agent
Capabilities bundle reusable behavior and compose automatically.
```python
from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking, WebSearch
agent = Agent(
'anthropic:claude-opus-4-6',
capabilities=[
Thinking(effort='high'),
WebSearch(),
],
)
```
Provider-adaptive capabilities to reach for first:
- `Thinking`
- `WebSearch`
- `WebFetch`
- `ImageGeneration`
- `MCP`
Use capabilities when the user wants behavior that should survive model/provider changes.
## Enable Thinking Across Providers
Use the unified `Thinking` capability or the `thinking` model setting.
```python
from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking
agent = Agent('anthropic:claude-opus-4-6', capabilities=[Thinking(effort='high')])
agent = Agent('anthropic:claude-opus-4-6', model_settings={'thinking': 'high'})
```
Supported effort values:
- `True`
- `False`
- `'minimal'`
- `'low'`
- `'medium'`
- `'high'`
- `'xhigh'`
## Intercept Agent Lifecycle with Hooks
Use `Hooks` for decorator-based lifecycle interception.
```python
from pydantic_ai import Agent, RunContext, ToolDefinition
from pydantic_ai.capabilities import ValidatedToolArgs
from pydantic_ai.capabilities.hooks import Hooks
from pydantic_ai.messages import ToolCallPart
from pydantic_ai.models import ModelRequestContext
hooks = Hooks()
@hooks.on.before_model_request
async def log_request(ctx: RunContext, request_context: ModelRequestContext) -> ModelRequestContext:
print(f'Sending {len(request_context.messages)} messages')
return request_context
@hooks.on.before_tool_execute(tools=['send_email'])
async def audit_tool(
ctx: RunContext[None],
*,
call: ToolCallPart,
tool_def: ToolDefinition,
args: ValidatedToolArgs,
) -> ValidatedToolArgs:
print(f'Executing {call.tool_name}')
return args
agent = Agent('openai:gpt-5.2', capabilities=[hooks])
```
Important hook families:
- run-level hooks
- node-level hooks
- model-request hooks
- tool-validation hooks
- tool-execution hooks
- event-stream hooks
Use hooks when the user wants observability, auditing, or light interception without adding a new abstraction.
## Build a Custom Capability
Subclass `AbstractCapability` when the user wants reusable behavior that combines tools, hooks, instructions, or model settings into one package.
Reach for a custom capability when:
- the same bundle should be reused across multiple agents
- `Hooks` alone is not enough
- the behavior should be installable or declarative
Keep custom capabilities focused. If the user only needs one tool or one hook, do not introduce a capability.
For every capability, consider whether `defer_loading=True` would improve the system by keeping instructions and tool schemas out of the eager context. Keep it eager only when the model benefits from that capability on most turns, when its hooks/settings must always apply, or when deferral would make capability selection unreliable.
## Defer Capability Loading
For capabilities on demand, load [Capabilities on Demand](./ON-DEMAND-CAPABILITIES.md). Use it when the user mentions deferred capabilities, capability progressive disclosure, `defer_loading=True` on a capability, or `load_capability`; also use it proactively when an agent design includes optional instructions, specialist workflows, long-tail tools, or context the model does not need on most turns.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |