pypi-pydantic-ai

1
# Pydantic AI
2

3
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.
4

5
## Package Information
6

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

12
## Core Imports
13

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

18
Common imports for building agents:
19

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

25
For structured outputs:
26

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

32
## Basic Usage
33

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

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

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

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

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

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

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

68
## Architecture
69

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

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

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

82
## Capabilities
83

84
### Core Agent Framework
85

86
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.
87

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

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

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

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

131
### Model Integration
132

133
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.
134

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

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

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

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

163
### Tools and Function Calling
164

165
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.
166

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

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

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

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

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

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

204
### Messages and Media
205

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

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

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

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

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

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

238
### Output Types and Validation
239

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

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

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

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

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

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

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

261
### Streaming and Async
262

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

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

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

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

283
### Settings and Configuration
284

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

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

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

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

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