0
# Pydantic AI
1

2
A comprehensive Python agent framework designed to make building production-grade applications with Generative AI less painful and more ergonomic. Built by the Pydantic team, Pydantic AI offers a FastAPI-like development experience for GenAI applications, featuring model-agnostic support for major LLM providers, seamless Pydantic Logfire integration for debugging and monitoring, type-safe design with powerful static type checking, Python-centric control flow, structured response validation using Pydantic models, optional dependency injection system for testable and maintainable code, streaming capabilities with immediate validation, and graph support for complex application flows.
3

4
## Package Information
5

6
- **Package Name**: pydantic-ai
7
- **Language**: Python
8
- **Installation**: `pip install pydantic-ai`
9
- **Requirements**: Python 3.9+
10

11
## Core Imports
12

13
```python
14
from pydantic_ai import Agent
15
```
16

17
Common imports for building agents:
18

19
```python
20
from pydantic_ai import Agent, RunContext, Tool
21
from pydantic_ai.models import OpenAIModel, AnthropicModel
22
```
23

24
For structured outputs:
25

26
```python
27
from pydantic_ai import Agent, StructuredDict
28
from pydantic import BaseModel
29
```
30

31
## Basic Usage
32

33
```python
34
from pydantic_ai import Agent
35
from pydantic_ai.models import OpenAIModel
36

37
# Create a simple agent
38
agent = Agent(
39
    model=OpenAIModel('gpt-4'),
40
    instructions='You are a helpful assistant.'
41
)
42

43
# Run the agent
44
result = agent.run_sync('What is the capital of France?')
45
print(result.data)
46
# Output: Paris
47

48
# Create an agent with structured output
49
from pydantic import BaseModel
50

51
class CityInfo(BaseModel):
52
    name: str
53
    country: str
54
    population: int
55

56
agent = Agent(
57
    model=OpenAIModel('gpt-4'),
58
    instructions='Extract city information.',
59
    output_type=CityInfo
60
)
61

62
result = agent.run_sync('Tell me about Tokyo')
63
print(result.data.name)  # Tokyo
64
print(result.data.population)  # 37,000,000
65
```
66

67
## Architecture
68

69
Pydantic AI is built around several key components that work together to provide a flexible and type-safe agent framework:
70

71
- **Agent**: The central class that orchestrates interactions between users, models, and tools
72
- **Models**: Abstraction layer supporting 10+ LLM providers (OpenAI, Anthropic, Google, etc.)
73
- **Tools**: Function-based capabilities that agents can call to perform actions
74
- **Messages**: Rich message system supporting text, images, audio, video, and documents
75
- **Output Types**: Flexible output handling including structured data, text, and tool-based outputs
76
- **Run Context**: Dependency injection system for testable and maintainable code
77
- **Streaming**: Real-time response processing with immediate validation
78

79
This architecture enables building production-grade AI applications with full type safety, comprehensive error handling, and seamless integration with the Python ecosystem.
80

81
## Capabilities
82

83
### Core Agent Framework
84

85
The foundational agent system for creating AI agents with typed dependencies, structured outputs, and comprehensive error handling. Includes the main Agent class, run management, and result handling.
86

87
```python { .api }
88
class Agent[AgentDepsT, OutputDataT]:
89
    def __init__(
90
        self,
91
        model: Model | KnownModelName | str | None = None,
92
        *,
93
        output_type: OutputSpec[OutputDataT] = str,
94
        instructions: str | SystemPromptFunc[AgentDepsT] | Sequence[str | SystemPromptFunc[AgentDepsT]] | None = None,
95
        system_prompt: str | Sequence[str] = (),
96
        deps_type: type[AgentDepsT] = NoneType,
97
        name: str | None = None,
98
        model_settings: ModelSettings | None = None,
99
        retries: int = 1,
100
        output_retries: int | None = None,
101
        tools: Sequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] = (),
102
        builtin_tools: Sequence[AbstractBuiltinTool] = (),
103
        prepare_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
104
        prepare_output_tools: ToolsPrepareFunc[AgentDepsT] | None = None,
105
        toolsets: Sequence[AbstractToolset[AgentDepsT] | ToolsetFunc[AgentDepsT]] | None = None,
106
        defer_model_check: bool = False
107
    ): ...
108

109
    def run_sync(
110
        self,
111
        user_prompt: str,
112
        *,
113
        message_history: list[ModelMessage] | None = None,
114
        deps: AgentDepsT = None,
115
        model_settings: ModelSettings | None = None
116
    ) -> AgentRunResult[OutputDataT]: ...
117

118
    async def run(
119
        self,
120
        user_prompt: str,
121
        *,
122
        message_history: list[ModelMessage] | None = None,
123
        deps: AgentDepsT = None,
124
        model_settings: ModelSettings | None = None
125
    ) -> AgentRunResult[OutputDataT]: ...
126
```
127

128
[Core Agent Framework](./agent.md)
129

130
### Model Integration
131

132
Comprehensive model abstraction supporting 10+ LLM providers including OpenAI, Anthropic, Google, Groq, Cohere, Mistral, and more. Provides unified interface with provider-specific optimizations and fallback capabilities.
133

134
```python { .api }
135
class OpenAIModel:
136
    def __init__(
137
        self,
138
        model_name: str,
139
        *,
140
        api_key: str | None = None,
141
        base_url: str | None = None,
142
        openai_client: OpenAI | None = None,
143
        timeout: float | None = None
144
    ): ...
145

146
class AnthropicModel:
147
    def __init__(
148
        self,
149
        model_name: str,
150
        *,
151
        api_key: str | None = None,
152
        base_url: str | None = None,
153
        anthropic_client: Anthropic | None = None,
154
        timeout: float | None = None
155
    ): ...
156

157
def infer_model(model: Model | KnownModelName) -> Model: ...
158
```
159

160
[Model Integration](./models.md)
161

162
### Tools and Function Calling
163

164
Flexible tool system enabling agents to call Python functions, access APIs, execute code, and perform web searches. Supports both built-in tools and custom function definitions with full type safety.
165

166
```python { .api }
167
class Tool[AgentDepsT]:
168
    def __init__(
169
        self,
170
        function: ToolFuncEither[AgentDepsT, Any],
171
        *,
172
        name: str | None = None,
173
        description: str | None = None,
174
        prepare: ToolPrepareFunc[AgentDepsT] | None = None
175
    ): ...
176

177
class RunContext[AgentDepsT]:
178
    deps: AgentDepsT
179
    retry: int
180
    tool_name: str
181

182
    def set_messages(self, messages: list[ModelMessage]) -> None: ...
183

184
class WebSearchTool:
185
    def __init__(
186
        self,
187
        *,
188
        max_results: int = 5,
189
        request_timeout: float = 10.0
190
    ): ...
191

192
class CodeExecutionTool:
193
    def __init__(
194
        self,
195
        *,
196
        timeout: float = 30.0,
197
        allowed_packages: list[str] | None = None
198
    ): ...
199
```
200

201
[Tools and Function Calling](./tools.md)
202

203
### Messages and Media
204

205
Rich message system supporting text, images, audio, video, documents, and binary content. Includes comprehensive streaming support and delta updates for real-time interactions.
206

207
```python { .api }
208
class ImageUrl:
209
    def __init__(
210
        self,
211
        url: str,
212
        *,
213
        alt: str | None = None,
214
        media_type: ImageMediaType | None = None
215
    ): ...
216

217
class AudioUrl:
218
    def __init__(
219
        self,
220
        url: str,
221
        *,
222
        media_type: AudioMediaType | None = None
223
    ): ...
224

225
class ModelRequest:
226
    parts: list[ModelRequestPart]
227
    kind: Literal['request']
228

229
class ModelResponse:
230
    parts: list[ModelResponsePart]
231
    timestamp: datetime
232
    kind: Literal['response']
233
```
234

235
[Messages and Media](./messages.md)
236

237
### Output Types and Validation
238

239
Flexible output handling supporting structured data validation using Pydantic models, text outputs, tool-based outputs, and native model outputs with comprehensive type safety.
240

241
```python { .api }
242
class ToolOutput[OutputDataT]:
243
    tools: list[Tool]
244
    defer: bool = False
245

246
class NativeOutput[OutputDataT]:
247
    ...
248

249
class PromptedOutput[OutputDataT]:
250
    ...
251

252
class TextOutput[OutputDataT]:
253
    converter: TextOutputFunc[OutputDataT] | None = None
254

255
def StructuredDict() -> type[dict[str, Any]]: ...
256
```
257

258
[Output Types and Validation](./output.md)
259

260
### Streaming and Async
261

262
Comprehensive streaming support for real-time interactions with immediate validation, delta updates, and event handling. Includes both async and sync streaming interfaces.
263

264
```python { .api }
265
class AgentStream[AgentDepsT, OutputDataT]:
266
    async def __anext__(self) -> AgentStreamEvent[AgentDepsT, OutputDataT]: ...
267
    
268
    async def get_final_result(self) -> FinalResult[OutputDataT]: ...
269

270
async def run_stream(
271
    self,
272
    user_prompt: str,
273
    *,
274
    message_history: list[ModelMessage] | None = None,
275
    deps: AgentDepsT = None,
276
    model_settings: ModelSettings | None = None
277
) -> AgentStream[AgentDepsT, OutputDataT]: ...
278
```
279

280
[Streaming and Async](./streaming.md)
281

282
### Settings and Configuration
283

284
Model settings, usage tracking, and configuration options for fine-tuning agent behavior, monitoring resource consumption, and setting usage limits.
285

286
```python { .api }
287
class ModelSettings(TypedDict, total=False):
288
    max_tokens: int
289
    temperature: float
290
    top_p: float
291
    timeout: float | Timeout
292
    parallel_tool_calls: bool
293
    seed: int
294
    presence_penalty: float
295
    frequency_penalty: float
296
    logit_bias: dict[str, int]
297
    stop_sequences: list[str]
298
    extra_headers: dict[str, str]
299
    extra_body: object
300

301
class RunUsage:
302
    request_count: int
303
    input_tokens: int | None
304
    output_tokens: int | None
305
    cache_creation_input_tokens: int | None
306
    cache_read_input_tokens: int | None
307
    total_tokens: int | None
308

309
class UsageLimits:
310
    request_limit: int | None = None
311
    input_token_limit: int | None = None
312
    output_token_limit: int | None = None
313
    total_token_limit: int | None = None
314
```
315

316
[Settings and Configuration](./settings.md)