Build production-ready AI agents with Pydantic AI.
from pai_agent_sdk.agents import create_agent
async with create_agent("openai:gpt-4o") as runtime:
result = await runtime.agent.run("Hello", deps=runtime.ctx)
print(result.output)
With tools and streaming:
from pai_agent_sdk.agents import create_agent, stream_agent
from pai_agent_sdk.toolsets.core.filesystem import tools as fs_tools
from pai_agent_sdk.toolsets.core.shell import tools as shell_tools
async with create_agent(
model="anthropic:claude-sonnet-4",
system_prompt="You are a coding assistant.",
tools=[*fs_tools, *shell_tools],
) as runtime:
async with stream_agent(runtime.agent, "List files", runtime.ctx) as stream:
async for event in stream:
# Handle streaming events
pass
pip install pai-agent-sdk[all]
# Or selective: pip install pai-agent-sdk[docker,web,document]
Inherit from
BaseTool
:
from pai_agent_sdk.toolsets.core.base import BaseTool
from pydantic_ai import RunContext
from pai_agent_sdk.context import AgentContext
class MyTool(BaseTool):
name = "my_tool"
description = "Does something useful"
async def call(self, ctx: RunContext[AgentContext], arg: str) -> str:
return f"Result: {arg}"
Full guide: docs/toolset.md
Export and restore state across restarts:
# Export
state = ctx.export_state()
with open("session.json", "w") as f:
f.write(state.model_dump_json())
# Restore
from pai_agent_sdk.context import ResumableState
state = ResumableState.model_validate_json(open("session.json").read())
async with create_agent("openai:gpt-4o", state=state) as runtime:
# Session restored with history and context
...
Full guide: docs/context.md
Require approval for dangerous tools:
async with create_agent(
model="anthropic:claude-sonnet-4",
tools=[*fs_tools, *shell_tools],
need_user_approve_tools=["shell", "edit"], # These require approval
) as runtime:
...
Full guide: docs/toolset.md
Delegate specialized tasks to child agents:
from pai_agent_sdk.subagents import SubagentConfig
config = SubagentConfig(
name="researcher",
description="Research specialist for web searches",
system_prompt="You are a research specialist...",
tools=["search_with_tavily", "visit_webpage"],
)
async with create_agent(
"anthropic:claude-sonnet-4",
tools=[SearchTool, VisitTool, ViewTool],
subagent_configs=[config],
include_builtin_subagents=True, # debugger, explorer, code-reviewer, searcher
) as runtime:
...
Full guide: docs/subagent.md
Use DockerBrowserSandbox for headless Chrome:
from pai_agent_sdk.sandbox.browser.docker_ import DockerBrowserSandbox
from pai_agent_sdk.toolsets.browser_use import BrowserUseToolset
# See examples/browser_use.py for complete implementation
Full example: examples/browser_use.py
Handle real-time events with lifecycle hooks:
from pai_agent_sdk.agents import stream_agent
from pai_agent_sdk.stream import AgentStartContext, AgentCompleteContext
async def on_start(ctx: AgentStartContext):
print(f"Agent started with prompt: {ctx.user_prompt}")
async def on_complete(ctx: AgentCompleteContext):
print(f"Agent completed in {ctx.duration_ms}ms")
async with stream_agent(
runtime.agent, "Hello", runtime.ctx,
on_agent_start=on_start,
on_agent_complete=on_complete,
) as stream:
async for event in stream:
pass
Full guide: docs/streaming.md
Inter-agent communication and user steering:
# Send message from external code
await ctx.bus.send("user", "Please focus on security issues")
# Agent can read messages via bus tools
Full guide: docs/message-bus.md
# Native pydantic-ai format
"openai:gpt-4o"
"anthropic:claude-sonnet-4"
"gemini:gemini-1.5-pro"
# Gateway mode (via proxy)
"mygateway@openai:gpt-4o"
# Requires: MYGATEWAY_API_KEY, MYGATEWAY_BASE_URL
Check examples/.env.example for all available environment variables
| Variable | Purpose |
|---|
TAVILY_API_KEY
| Web search |
FIRECRAWL_API_KEY
| Web scraping |
GOOGLE_SEARCH_API_KEY
+ GOOGLE_SEARCH_CX
| Google Custom Search |
from pai_agent_sdk.context import ModelConfig, ModelCapability
ModelConfig(
context_window=200_000,
capabilities={ModelCapability.vision},
)
from pai_agent_sdk.context import ToolConfig
ToolConfig(
tavily_api_key="...",
firecrawl_api_key="...",
google_search_api_key="...",
google_search_cx="...",
)
Import from
pai_agent_sdk.toolsets.core.*
:
| Module | Tools |
|---|
filesystem
| view, edit, multi_edit, replace, ls, glob, grep |
shell
| shell (command execution) |
web
| search_with_tavily, search_with_google, visit_webpage, save_web_files |
document
| pdf_convert, office_to_markdown |
content
| validate_json |
context
| thinking, handoff, to_do_read, to_do_write |
enhance
| screenshot |
multimodal
| view (images, video, audio) |
Available via
include_builtin_subagents=True
:
| Name | Purpose | Required Tools |
|---|
| debugger | Root cause analysis | glob, grep, view, ls |
| explorer | Codebase navigation | glob, grep, view, ls |
| code-reviewer | Code quality analysis | glob, grep, view, ls |
| searcher | Web research | search |
Missing API key errors: Set required environment variables or pass via
ToolConfig
.
Tool not available: Check
tool.is_available()
or set
skip_unavailable=True
in Toolset.
Session restore fails: Ensure message history and ResumableState are both saved/restored.
Docker sandbox issues: Ensure Docker daemon is running and user has Docker permissions.