Back to Details

pydantic-ai-agent-creation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Creating PydanticAI Agents

创建PydanticAI Agent

Quick Start

快速开始

python
from pydantic_ai import Agent
python
from pydantic_ai import Agent

Minimal agent (text output)

Minimal agent (text output)

agent = Agent('openai:gpt-4o') result = agent.run_sync('Hello!') print(result.output) # str
undefined
agent = Agent('openai:gpt-4o') result = agent.run_sync('Hello!') print(result.output) # str
undefined

Model Selection

模型选择

Model strings follow 
provider:model-name
format:
python
undefined
模型字符串遵循
provider:model-name
格式：
python
undefined

OpenAI

OpenAI

agent = Agent('openai:gpt-4o') agent = Agent('openai:gpt-4o-mini')
agent = Agent('openai:gpt-4o') agent = Agent('openai:gpt-4o-mini')

Anthropic

Anthropic

agent = Agent('anthropic:claude-sonnet-4-5') agent = Agent('anthropic:claude-haiku-4-5')
agent = Agent('anthropic:claude-sonnet-4-5') agent = Agent('anthropic:claude-haiku-4-5')

Google

Google

agent = Agent('google-gla:gemini-2.0-flash') agent = Agent('google-vertex:gemini-2.0-flash')
agent = Agent('google-gla:gemini-2.0-flash') agent = Agent('google-vertex:gemini-2.0-flash')

Others: groq:, mistral:, cohere:, bedrock:, etc.

Others: groq:, mistral:, cohere:, bedrock:, etc.

undefined
undefined

Structured Outputs

结构化输出

Use Pydantic models for validated, typed responses:
python
from pydantic import BaseModel
from pydantic_ai import Agent

class CityInfo(BaseModel):
    city: str
    country: str
    population: int

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Tell me about Paris')
print(result.output.city)  # "Paris"
print(result.output.population)  # int, validated
使用Pydantic模型获取经过验证的类型化响应：
python
from pydantic import BaseModel
from pydantic_ai import Agent

class CityInfo(BaseModel):
    city: str
    country: str
    population: int

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Tell me about Paris')
print(result.output.city)  # "Paris"
print(result.output.population)  # int, validated

Agent Configuration

Agent配置

python
agent = Agent(
    'openai:gpt-4o',
    output_type=MyOutput,           # Structured output type
    deps_type=MyDeps,               # Dependency injection type
    instructions='You are helpful.',  # Static instructions
    retries=2,                      # Retry attempts for validation
    name='my-agent',                # For logging/tracing
    model_settings=ModelSettings(   # Provider settings
        temperature=0.7,
        max_tokens=1000
    ),
    end_strategy='early',           # How to handle tool calls with results
)
python
agent = Agent(
    'openai:gpt-4o',
    output_type=MyOutput,           # Structured output type
    deps_type=MyDeps,               # Dependency injection type
    instructions='You are helpful.',  # Static instructions
    retries=2,                      # Retry attempts for validation
    name='my-agent',                # For logging/tracing
    model_settings=ModelSettings(   # Provider settings
        temperature=0.7,
        max_tokens=1000
    ),
    end_strategy='early',           # How to handle tool calls with results
)

Running Agents

运行Agent

Three execution methods:
python
undefined
三种执行方式：
python
undefined

Async (preferred)

Async (preferred)

result = await agent.run('prompt', deps=my_deps)
result = await agent.run('prompt', deps=my_deps)

Sync (convenience)

Sync (convenience)

result = agent.run_sync('prompt', deps=my_deps)
result = agent.run_sync('prompt', deps=my_deps)

Streaming

Streaming

async with agent.run_stream('prompt') as response: async for chunk in response.stream_output(): print(chunk, end='')
undefined
async with agent.run_stream('prompt') as response: async for chunk in response.stream_output(): print(chunk, end='')
undefined

Instructions vs System Prompts

指令与系统提示词

python
undefined
python
undefined

Instructions: Concatenated, for agent behavior

Instructions: Concatenated, for agent behavior

agent = Agent( 'openai:gpt-4o', instructions='You are a helpful assistant. Be concise.' )
agent = Agent( 'openai:gpt-4o', instructions='You are a helpful assistant. Be concise.' )

Dynamic instructions via decorator

Dynamic instructions via decorator

@agent.instructions def add_context(ctx: RunContext[MyDeps]) -> str: return f"User ID: {ctx.deps.user_id}"
@agent.instructions def add_context(ctx: RunContext[MyDeps]) -> str: return f"User ID: {ctx.deps.user_id}"

System prompts: Static, for model context

System prompts: Static, for model context

agent = Agent( 'openai:gpt-4o', system_prompt=['You are an expert.', 'Always cite sources.'] )
undefined
agent = Agent( 'openai:gpt-4o', system_prompt=['You are an expert.', 'Always cite sources.'] )
undefined

Common Patterns

常见模式

Parameterized Agent (Type-Safe)

参数化Agent（类型安全）

python
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    api_key: str
    user_id: int

agent: Agent[Deps, str] = Agent(
    'openai:gpt-4o',
    deps_type=Deps,
)
python
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    api_key: str
    user_id: int

agent: Agent[Deps, str] = Agent(
    'openai:gpt-4o',
    deps_type=Deps,
)

deps is now required and type-checked

deps is now required and type-checked

result = agent.run_sync('Hello', deps=Deps(api_key='...', user_id=123))
undefined
result = agent.run_sync('Hello', deps=Deps(api_key='...', user_id=123))
undefined

No Dependencies (Satisfy Type Checker)

无依赖项（满足类型检查器要求）

python
undefined
python
undefined

Option 1: Explicit type annotation

Option 1: Explicit type annotation

agent: Agent[None, str] = Agent('openai:gpt-4o')
agent: Agent[None, str] = Agent('openai:gpt-4o')

Option 2: Pass deps=None

Option 2: Pass deps=None

result = agent.run_sync('Hello', deps=None)
undefined
result = agent.run_sync('Hello', deps=None)
undefined

Decision Framework

决策框架

ScenarioConfiguration
Simple text responses
Agent(model)
Structured data extraction
Agent(model, output_type=MyModel)
Need external servicesAdd 
deps_type=MyDeps
Validation retries neededIncrease 
retries=3
Debugging/monitoringSet 
instrument=True
场景配置
简单文本响应
Agent(model)
结构化数据提取
Agent(model, output_type=MyModel)
需要外部服务添加
deps_type=MyDeps
需要验证重试增加
retries=3
调试/监控设置
instrument=True