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/NATIVE-TOOLS.md
View on GitHub# Native Tools
Read this file when the user wants provider-native tools such as web search, web fetch, code execution, memory, or file search.
Prefer provider-adaptive capabilities like `WebSearch()`, `WebFetch()`, `MCP()`, or `ImageGeneration()` when the user wants a provider-agnostic solution. Use native tools directly when they explicitly want provider-native behavior or provider-specific configuration.
## Give My Agent Web Search or Code Execution
Native tools are wrapped in [`NativeTool`][pydantic_ai.capabilities.NativeTool] and passed via `capabilities=[...]`.
```python
from pydantic_ai import Agent
from pydantic_ai.capabilities import NativeTool
from pydantic_ai.native_tools import WebSearchTool
agent = Agent('openai-responses:gpt-5.2', capabilities=[NativeTool(WebSearchTool())])
result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
print(result.output)
```
For OpenAI web search, use the Responses API model prefix (`openai-responses:`), not `openai:`.
## Native Tool Defaults
Reach for these when the provider supports them:
- `WebSearchTool`
- `WebFetchTool`
- `CodeExecutionTool`
- `ImageGenerationTool`
- `MemoryTool`
- `MCPServerTool`
- `FileSearchTool`
## Dynamic Native Tool Configuration
Prepare native tools from `RunContext` when configuration depends on the current user or request. Wrap the prepare function in `NativeTool(...)`.
```python
from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import NativeTool
from pydantic_ai.native_tools import WebSearchTool
async def prepared_web_search(ctx: RunContext[dict]) -> WebSearchTool | None:
if not ctx.deps.get('location'):
return None
return WebSearchTool(user_location={'city': ctx.deps['location']})
agent = Agent(
'openai-responses:gpt-5.2',
capabilities=[NativeTool(prepared_web_search)],
deps_type=dict,
)
```
## When to Use Native Tools vs Provider-Adaptive Capabilities
Use provider-adaptive capabilities — `WebSearch()`, `WebFetch()`, `MCP()`, `ImageGeneration()` — when:
- the code should work across providers
- you want local fallback when native support is missing
- the user has not committed to a provider yet
```python
from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
agent = Agent('anthropic:claude-sonnet-4-6', capabilities=[WebSearch()])
```
Use native tools (`NativeTool(WebSearchTool(...))`) when:
- the user explicitly wants provider-native behavior
- provider-specific configuration matters (e.g. `WebSearchTool(user_location=...)`)
- the user already picked a provider that supports the tool
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 |