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/TOOLS-CORE.md
View on GitHub# Tools Core
Read this file when the user wants to add function tools, organize toolsets, connect MCP servers, or use explicit common search tools.
## Add Tools to an Agent
Use `@agent.tool_plain` for pure functions and `@agent.tool` for tools that need `RunContext`.
```python
import random
from pydantic_ai import Agent, RunContext
agent = Agent('google:gemini-3-flash-preview', deps_type=str)
@agent.tool_plain
def roll_dice() -> str:
return str(random.randint(1, 6))
@agent.tool
def get_player_name(ctx: RunContext[str]) -> str:
return ctx.deps
```
Use `Tool(fn)` when tools are defined outside the agent file or shared between agents.
## Choosing a Tool Registration Method
Default choices:
- `@agent.tool` when the tool needs deps, usage, retry count, or message history
- `@agent.tool_plain` when the tool is a plain function
- `Tool(...)` in `tools=[...]` when the tool should be reusable across agents
- `FunctionToolset` when multiple related tools should be managed as a group
## Organize or Restrict Which Tools an Agent Can Use
Use toolsets when the user has multiple related tools or wants cross-cutting behavior applied to a group.
Examples:
- `FunctionToolset` for a bundle of Python tools
- MCP servers, which are themselves toolsets
- wrapper toolsets for approval, deferred loading, or other cross-cutting behavior
## Access Usage Stats, Message History, or Retry Count in Tools
Route this to `@agent.tool` with `RunContext`.
Useful `RunContext` fields include:
- `ctx.deps`
- `ctx.usage`
- `ctx.messages`
- `ctx.retry`
## Use MCP Servers
For URL-based MCP servers, use the `MCP` capability — it runs the MCP server locally by default and lets you opt into the model provider's native MCP support with `native=True`. See the [MCP capability docs](https://ai.pydantic.dev/capabilities/#mcp).
```python
from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP
agent = Agent(
'openai:gpt-5.2',
capabilities=[
MCP('https://mcp.example.com/api'), # Streamable HTTP, local-only by default
MCP('https://mcp.example.com/other', native=True), # opt into native with local fallback
],
)
```
The capability's first positional arg is the URL. To pass any other `MCPToolset` input — a `fastmcp.client.transports.*Transport`, pre-built `fastmcp.Client`, in-process `FastMCP` server, or local script path — use the `local=` keyword:
```python
from fastmcp.client.transports import StdioTransport
from pydantic_ai import Agent
from pydantic_ai.capabilities import MCP
agent = Agent(
'openai:gpt-5.2',
capabilities=[MCP(local=StdioTransport(command='python', args=['mcp_server.py']))],
)
```
When you need to manage the toolset lifecycle yourself, share an MCP server across multiple agents, or use FastMCP-specific configuration that doesn't fit the capability shape, use [`MCPToolset`](https://ai.pydantic.dev/mcp/client/) directly and pass it via `toolsets=[...]`.
## Search with DuckDuckGo, Tavily, or Exa
Use common tools when the user wants explicit search tools rather than provider-adaptive capabilities.
```python
from pydantic_ai import Agent
from pydantic_ai.common_tools.duckduckgo import duckduckgo_search_tool
agent = Agent(
'openai:gpt-5.2',
tools=[duckduckgo_search_tool()],
instructions='Search DuckDuckGo for the given query and return the results.',
)
```
Good default split:
- use `WebSearch()` capability when the user wants model-agnostic search with native fallback
- use `duckduckgo_search_tool()` / Tavily / Exa when the user explicitly wants those engines as tools
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 |