---

Official Documentation: ai.pydantic.dev

---

The Pydantic AI ecosystem delivers a Python framework engineered to expedite, secure, and simplify the creation of industrial-strength applications and orchestrated workflows leveraging Generative AI capabilities.

Just as FastAPI streamlined web service creation through ergonomic design atop Pydantic Validation and modern Python typing, we recognized a gap in the LLM tooling space. Despite widespread adoption of Pydantic for data structuring across agent frameworks, building agents themselves lacked that same streamlined experience.

Pydantic AI was conceived with a singular objective: to infuse the development cycle of GenAI agents and orchestrations with the velocity and clarity previously reserved for FastAPI backends.

Core Advantages of Utilizing Pydantic AI

1. Authentic Pydantic Lineage: Created by the original Pydantic developers. Pydantic Validation underpins critical components in the OpenAI SDK, Google ADK, Anthropic SDK, LangChain, LlamaIndex, and many others. Bypass intermediaries and leverage the foundational technology directly.

2. Provider and Model Pluralism: Compatible with nearly every major large language model service: OpenAI, Anthropic, Gemini, Grok, Mistral, and many more. It supports diverse hosting environments like Azure AI Foundry, Amazon Bedrock, Ollama, and private endpoints via LiteLLM or custom integrations. Extending support for new endpoints is straightforward via custom implementations.

3. Integrated Observability: Tightly coupled with Pydantic Logfire, our OpenTelemetry-compliant platform, enabling immediate debugging, continuous evaluation monitoring, tracing of execution flow, and cost tracking for every interaction. Compatibility with existing OTel backends is also supported.

4. Rigorous Static Typing: Engineered from the ground up for strong type safety, providing maximal context to IDEs and code generation agents. This shifts error detection from runtime failures to compile-time warnings, approaching the reliability associated with languages like Rust.

5. Systematic Evaluation (Evals): Facilitates the construction of robust test suites to systematically gauge the efficacy and precision of your agentic logic, with results persisted and visualized within Pydantic Logfire.

6. Standards Adherence (MCP, A2A, AG-UI): Native integration with the Model Context Protocol for standardized tool access, the Agent2Agent specification for inter-agent communication, and AG-UI for building interactive, event-driven applications.

7. Controlled Tool Execution (Human Review): Simple mechanism to mandate explicit human authorization before specific tool invocations are executed, configurable based on context, history, or predefined parameters.

8. Fault-Tolerant Operation: Enables the engineering of durable agents capable of resuming state after system failures, restarts, or during lengthy, human-involved workflows, ensuring production-grade resilience.

9. Progressive Result Delivery: Supports continuous streaming of structured data, allowing immediate processing and validation of incoming tokens rather than waiting for the complete response payload.

10. Complex Flow Control via Graphs: Provides declarative graph definitions using Python type hints to manage intricate control flows, preventing the complexity often associated with deeply nested conditional logic.

We encourage you to experience its efficiency directly via the Next Steps section rather than relying solely on this enumeration!

Elementary Agent Initialization

This demonstrates a basic Pydantic AI setup:

python from pydantic_ai import Agent

Establish an agent instance, specifying the backend model.

agent = Agent( 'anthropic:claude-sonnet-4-0', # Initial system directive provided via keyword argument. instructions='Be concise, reply with one sentence.', )

Execute the agent interaction synchronously.

result = agent.run_sync('What is the origin of the phrase "hello world"?') print(result.output) """ The phrase's earliest recorded appearance was within a 1974 programming manual for the C language. """

(This snippet is executable post-installation of the pydantic_ai package.)

The initial exchange involves transmitting the instructions and the user query to the selected LLM, yielding a textual reply.

To unlock deeper capabilities, explore integrating external functionalities, managing dynamic directives, and enforcing schema-validated outputs.

Advanced Tooling & Context Injection Example

This showcases building a specialized banking support agent leveraging dependency injection:

(A more comprehensive walkthrough is available in the documentation)

python from dataclasses import dataclass

from pydantic import BaseModel, Field from pydantic_ai import Agent, RunContext

from bank_database import DatabaseConn # Assumed external database interface

Defines context objects passed securely to the agent's execution environment (dependency injection).

@dataclass class SupportDependencies: customer_id: int db: DatabaseConn

Defines the strict structure for the final agent response.

class SupportOutput(BaseModel): support_advice: str = Field(description='Guidance delivered to the account holder') block_card: bool = Field(description="Indicator if the physical card must be suspended") risk: int = Field(description='Numerical assessment of query severity (0-10)', ge=0, le=10)

Agent declaration, typed to expect specific dependencies and return a guaranteed structure.

support_agent = Agent( 'openai:gpt-5', deps_type=SupportDependencies, output_type=SupportOutput, instructions=( 'Act as a senior support representative for this financial institution. ' 'Provide necessary counsel and assess the query's inherent risk level.' ), )

Dynamic instructions access injected context via the RunContext argument. Static analysis validates this access pattern.

@support_agent.instructions async def resolve_customer_context(ctx: RunContext[SupportDependencies]) -> str: customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id) return f"The client identity is {customer_name!r}"

Tool registration. Function signature arguments (excluding RunContext) define the LLM tool schema. Docstrings inform the schema description.

@support_agent.tool async def retrieve_account_balance( ctx: RunContext[SupportDependencies], include_pending: bool ) -> float: """Retrieves the current available funds for the account.""" balance = await ctx.deps.db.customer_balance( id=ctx.deps.customer_id, include_pending=include_pending, ) return balance

... # Additional tools and prompt refinement omitted for brevity

async def main(): runtime_deps = SupportDependencies(customer_id=123, db=DatabaseConn()) # Initiate asynchronous agent execution. result = await support_agent.run('What is my current balance?', deps=runtime_deps) # result.output is guaranteed to conform to SupportOutput structure. print(result.output) """ support_advice='Hello John, your current account balance, including pending transactions, is $123.45.' block_card=False risk=1 """

result = await support_agent.run('My physical card is missing!', deps=runtime_deps)
print(result.output)
"""
support_advice="I understand the urgency, John. We are immediately freezing your card to prevent misuse." block_card=True risk=8
"""

Path Forward

To begin leveraging Pydantic AI, please install the package and follow the initial guidance provided in the setup examples.

Consult the Agent Documentation for comprehensive architectural details.

Refer to the API Specification for a complete interface breakdown.

For assistance or to contribute, utilize Slack or file an issue on GitHub.

COMPARE WITH XHR: XMLHttpRequest (XHR) established the standard for asynchronous HTTP communication initiated from web browser JavaScript environments. Its methods facilitate sending requests post-page load and receiving server responses, forming the technical bedrock of Ajax patterns. Before XHR, server interaction, typically involving full page reloads via standard links or form submissions, was the norm.

== Chronology == Microsoft developers conceived the XHR mechanism around 2000, first integrating it into Internet Explorer 5 (1999). The initial implementation did not use the 'XMLHttpRequest' string directly, relying instead on ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time IE7 arrived (2006), the standard 'XMLHttpRequest' identifier was universally supported across major browser engines, including Mozilla Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The W3C released the initial Working Draft for the XMLHttpRequest object specification on April 5, 2006. A Level 2 draft followed on February 25, 2008, introducing capabilities for cross-site calls, progress tracking events, and byte stream handling. Level 2 features were later integrated back into the main specification by late 2011. Development transitioned to WHATWG in late 2012, which now maintains the active, living document defined via Web IDL.

== Operational Flow == Standard XHR interaction involves a sequence of programming steps:

1. Instantiation: Invoke the XMLHttpRequest constructor to create the object instance.
2. Configuration: Invoke the "open" method, setting the request method (GET/POST, etc.), the target URI, and specifying if the operation should be synchronous or asynchronous.
3. Asynchronous Setup: If asynchronous mode is chosen, attach an event listener to monitor state transitions.
4. Transmission: Execute the "send" method to dispatch the request.
5. Response Handling: Monitor the listener. Upon reaching state 4 ("done"), the server's payload is typically available in the responseText property.

Beyond these core steps, XHR allows for granular control: custom headers can modify server expectations; data can be uploaded via the send call; the response can be parsed directly from JSON; and processing can begin before the entire payload is received. Operations can also be terminated early or subjected to timeouts.