Pydantic AI 工作流

Installation

uv add pydantic-ai-harness

Extras for specific capabilities:

uv add "pydantic-ai-harness[codemode]"   # CodeMode (adds the Monty sandbox)
uv add "pydantic-ai-harness[logfire]"     # ManagedPrompt (Logfire-managed prompts)

The code-mode extra is also supported as an alias.

Requires Python 3.10+ and pydantic-ai-slim>=1.95.1.

See https://ai.pydantic.dev/logfire/ for setup details.

logfire.configure() logfire.instrument_pydantic_ai()

agent = Agent( 'anthropic:claude-opus-4-7', capabilities=[ # Wraps every tool into a single run_code tool, sandboxed by Monty # (https://github.com/pydantic/monty -- pulled in by the [code-mode] extra). # The model writes Python that calls multiple tools with loops, conditionals, # asyncio.gather, and local filtering -- one model round-trip for N tool calls. CodeMode(), # Connect to any MCP server -- here, the open-source Hacker News server # (https://github.com/cyanheads/hn-mcp-server). native=False forces the # local MCP toolset so CodeMode can wrap the tools; without it, # providers that natively support MCP server connectors execute the tools # server-side and bypass the sandbox. MCP('https://hn.caseyjhand.com/mcp', native=False), # Provider-adaptive web search; native=False routes through the local # DuckDuckGo fallback (the [duckduckgo] extra above) so CodeMode can batch # web searches alongside the HN calls in a single run_code. WebSearch(native=False), ], )

result = agent.run_sync( "Across the top, best, and 'show HN' Hacker News feeds, find the most-discussed " "story with at least 100 points. Pull its comment thread, its submitter's profile, " "and any web coverage. Summarize what you find in one paragraph." ) print(result.output) """ The most-discussed HN story across top/best/show clearing 100 points is "Vibe coding and agentic engineering are getting closer than I'd like" by Simon Willison (748 points, 853 comments, on the Best feed), submitted by long-time HNer e12e. The piece argues that the two modes Willison once kept mentally separate -- throwaway "vibe coding" and disciplined "agentic engineering" -- are blurring, since agents like Claude Code now reliably handle non-trivial tasks like "build a JSON API endpoint that runs a SQL query" with tests and docs on the first pass. The HN thread is unusually substantive, with commenters debating whether LLMs created or merely exposed sloppy engineering practices and warning of a "normalization of deviance" as engineers stop reviewing diffs. """ ```

See this run as a public Logfire trace → Each run_code span fans out into the tool calls the model issued from inside the sandbox -- it's the easiest way to understand what code mode actually did.

See https://ai.pydantic.dev/logfire/ for setup details.

logfire.configure() logfire.instrument_pydantic_ai()

agent = Agent( 'anthropic:claude-opus-4-7', capabilities=[ # --- Tool execution & discovery --- # Wraps every tool into a single run_code, sandboxed by Monty. CodeMode(),

# Progressive tool discovery for large tool sets; discovered tools fold into run_code. ToolSearch(),

# --- Reasoning --- # Provider-adaptive thinking; uses native extended thinking on supporting models. Thinking(effort='xhigh'),

# --- Context management --- # Sliding window + LLM compaction. By @vstorm-co: # https://github.com/vstorm-co/summarization-pydantic-ai # Pydantic AI also ships AnthropicCompaction and OpenAICompaction for # provider-native compaction. ContextManagerCapability(max_tokens=180_000),

# --- Tools --- # Connect to any MCP server -- here, the open-source Hacker News server # (https://github.com/cyanheads/hn-mcp-server). MCP('https://hn.caseyjhand.com/mcp'),

# Provider-adaptive web search; falls back to a local DuckDuckGo implementation. WebSearch(),

# Filesystem + shell. By @vstorm-co: https://github.com/vstorm-co/pydantic-ai-backend ConsoleCapability(),

# --- Memory & persistence --- # Persistent ./MEMORY.md per agent name. By @vstorm-co: # https://github.com/vstorm-co/pydantic-deepagents MemoryCapability(agent_name='harness-example'),

# --- Orchestration --- # Agent skills (Anthropic's spec) by @DougTrajano: # https://github.com/DougTrajano/pydantic-ai-skills # @vstorm-co's pydantic-deep also offers skills loading; the two have different # spec footprints (Doug's is closer to programmatic skills). SkillsCapability(directories=['./skills']),

# Spawn sub-agents with their own toolsets and instructions. By @vstorm-co: # https://github.com/vstorm-co/subagents-pydantic-ai SubAgentCapability(subagents=[ SubAgentConfig( name='researcher', description='Deep research on a topic', instructions='You are a thorough research assistant.', ), ]),

# Track tasks and subtasks; in-memory by default, AsyncPostgresStorage available. # By @vstorm-co: https://github.com/vstorm-co/pydantic-ai-todo TodoCapability(enable_subtasks=True),

# --- Safety & reliability --- # The next four are by @vstorm-co: https://github.com/vstorm-co/pydantic-ai-shields # Per-run cost cap with a callback hook. CostTracking(budget_usd=5.0),

# Reject prompts that look like prompt-injection attempts. InputGuard(guard=lambda p: 'ignore previous instructions' not in p.lower()),

# Block or require approval per tool name. ToolGuard(blocked=['rm'], require_approval=['write_file']),

# Detect API keys/tokens in tool I/O and redact before they reach the model. SecretRedaction(),

# Bail out if the agent gets stuck calling the same tools in a loop. # By @vstorm-co: https://github.com/vstorm-co/pydantic-deepagents StuckLoopDetection(), ], ) ```

This snippet is illustrative, not literally copy-pasteable: a few capabilities have setup requirements (a ./skills directory, a Postgres database for TodoCapability's persistent storage), and the community packages move independently of this one. The capability matrix tracks each one's status. As the harness ships first-party versions, the imports above will collapse onto fewer packages -- but the example will keep working, since the API surface is the same.

Build your own

Capabilities are the primary extension point for Pydantic AI. Any of the existing capabilities in this repo can serve as a reference for building your own.

Publishing as a standalone package? Use the pydantic-ai-<name> naming convention. See Publishing capability packages.

Quick start

uv add "pydantic-ai-slim[anthropic,mcp,duckduckgo,logfire]" "pydantic-ai-harness[code-mode]"

```python import logfire from pydantic_ai import Agent from pydantic_ai.capabilities import MCP, WebSearch from pydantic_ai_harness import CodeMode

Pydantic AI references

• Capabilities -- what capabilities are, built-in capabilities, building your own
• Hooks -- lifecycle hooks reference, ordering, error handling
• Extensibility -- publishing packages, third-party ecosystem
• Toolsets -- building tools for capabilities
• API reference -- full API docs

Community packages, alphabetical:

from pydantic_ai_backends import ConsoleCapability from pydantic_ai_shields import CostTracking, InputGuard, SecretRedaction, ToolGuard from pydantic_ai_skills import SkillsCapability from pydantic_ai_summarization import ContextManagerCapability from pydantic_ai_todo import TodoCapability from pydantic_deep import MemoryCapability, StuckLoopDetection from subagents_pydantic_ai import SubAgentCapability, SubAgentConfig