+
+
@@ -24,62 +24,65 @@
---
-PydanticAI is a Python agent framework designed to make it less painful to build production grade applications with Generative AI.
+### Pydantic AI is a Python agent framework designed to help you quickly, confidently, and painlessly build production grade applications and workflows with Generative AI.
-FastAPI revolutionized web development by offering an innovative and ergonomic design, built on the foundation of [Pydantic](https://docs.pydantic.dev).
-Similarly, virtually every agent framework and LLM library in Python uses Pydantic, yet when we began to use LLMs in [Pydantic Logfire](https://pydantic.dev/logfire), we couldn't find anything that gave us the same feeling.
+FastAPI revolutionized web development by offering an innovative and ergonomic design, built on the foundation of [Pydantic](https://docs.pydantic.dev) and modern Python features like type hints.
-We built PydanticAI with one simple aim: to bring that FastAPI feeling to GenAI app development.
+Yet despite the fact that virtually every agent framework and LLM library in Python uses Pydantic, when we began to use LLMs in [Pydantic Logfire](https://pydantic.dev/logfire), we couldn't find anything that gave us the same feeling.
-## Why use PydanticAI
+We built Pydantic AI with one simple aim: to bring that FastAPI feeling to GenAI app and agent development.
-* __Built by the Pydantic Team__
-Built by the team behind [Pydantic](https://docs.pydantic.dev/latest/) (the validation layer of the OpenAI SDK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more).
+## Why use Pydantic AI
-* __Model-agnostic__
-Supports OpenAI, Anthropic, Gemini, Deepseek, Ollama, Groq, Cohere, and Mistral, and there is a simple interface to implement support for [other models](https://ai.pydantic.dev/models/).
+1. __Built by the Pydantic Team__:
+[Pydantic](https://docs.pydantic.dev/latest/) is the validation layer of the OpenAI SDK, the Google ADK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more. _Why use the derivative when you can go straight to the source?_ :smiley:
-* __Pydantic Logfire Integration__
-Seamlessly [integrates](https://ai.pydantic.dev/logfire/) with [Pydantic Logfire](https://pydantic.dev/logfire) for real-time debugging, performance monitoring, and behavior tracking of your LLM-powered applications.
+2. __Model-agnostic__:
+Supports virtually every [model](https://ai.pydantic.dev/models) and provider under the sun: OpenAI, Anthropic, Gemini, DeepSeek, Ollama, Grok, Cohere, and Mistral; Azure AI Foundry, Amazon Bedrock, Google Vertex AI, Groq, Together AI, Fireworks AI, OpenRouter, and Heroku. If your favorite model or provider is not listed, you can easily implement a [custom model](https://ai.pydantic.dev/models#custom-models).
-* __Type-safe__
-Designed to make [type checking](https://ai.pydantic.dev/agents/#static-type-checking) as powerful and informative as possible for you.
+3. __Seamless Observability__:
+Tightly [integrates](https://ai.pydantic.dev/logfire) with [Pydantic Logfire](https://pydantic.dev/logfire), our general-purpose OpenTelemetry observability platform, for real-time debugging, evals-based performance monitoring, and behavior and cost tracking. If you already have an observability platform that supports OTel, you can use that too.
-* __Python-centric Design__
-Leverages Python's familiar control flow and agent composition to build your AI-driven projects, making it easy to apply standard Python best practices you'd use in any other (non-AI) project.
+4. __Fully Type-safe__:
+Designed to give your IDE or AI coding agent as much context as possible for auto-completion and [type checking](https://ai.pydantic.dev/agents#static-type-checking), moving entire classes of errors from runtime to write-time for a bit of that Rust "if it compiles, it works" feel.
-* __Structured Responses__
-Harnesses the power of [Pydantic](https://docs.pydantic.dev/latest/) to [validate and structure](https://ai.pydantic.dev/output/#structured-output) model outputs, ensuring responses are consistent across runs.
+5. __Powerful Evals__:
+Enables you to systematically test and [evaluate](https://ai.pydantic.dev/evals) the performance and accuracy of the agentic systems you build, and monitor the performance over time in Pydantic Logfire.
-* __Dependency Injection System__
-Offers an optional [dependency injection](https://ai.pydantic.dev/dependencies/) system to provide data and services to your agent's [system prompts](https://ai.pydantic.dev/agents/#system-prompts), [tools](https://ai.pydantic.dev/tools/) and [output validators](https://ai.pydantic.dev/output/#output-validator-functions).
-This is useful for testing and eval-driven iterative development.
+6. __MCP and A2A__:
+Integrates the [Model Context Protocol](https://ai.pydantic.dev/mcp) and [Agent2Agent](https://ai.pydantic.dev/a2a) standards to give your agent access to external tools and data and let it interoperate with other agents.
-* __Streamed Responses__
-Provides the ability to [stream](https://ai.pydantic.dev/output/#streamed-results) LLM outputs continuously, with immediate validation, ensuring rapid and accurate outputs.
+7. __Multi-Modal Input__:
+Lets you easily share images, documents, videos and audio [input](https://ai.pydantic.dev/input) with the LLM to go beyond the limitations of text.
-* __Graph Support__
-[Pydantic Graph](https://ai.pydantic.dev/graph) provides a powerful way to define graphs using typing hints, this is useful in complex applications where standard control flow can degrade to spaghetti code.
+8. __Streamed Outputs__:
+Provides the ability to [stream](https://ai.pydantic.dev/output#streamed-results) structured output continuously, with immediate validation, ensuring real time access to generated data.
+
+9. __Dependency Injection__:
+Offers an optional [dependency injection](https://ai.pydantic.dev/dependencies) system to provide data and services to your agent's [instructions](https://ai.pydantic.dev/agents#instructions), [tools](https://ai.pydantic.dev/tools) and [output functions](https://ai.pydantic.dev/output#output-functions).
+
+10. __Graph Support__:
+Provides a powerful way to define [graphs](https://ai.pydantic.dev/graph) using type hints, for use in complex applications where standard control flow can degrade to spaghetti code.
+
+Realistically though, no list is going to be as convincing as [giving it a try](#next-steps) and seeing how it makes you feel!
## Hello World Example
-Here's a minimal example of PydanticAI:
+Here's a minimal example of Pydantic AI:
```python
from pydantic_ai import Agent
# Define a very simple agent including the model to use, you can also set the model when running the agent.
agent = Agent(
- 'google-gla:gemini-1.5-flash',
- # Register a static system prompt using a keyword argument to the agent.
- # For more complex dynamically-generated system prompts, see the example below.
- system_prompt='Be concise, reply with one sentence.',
+ 'anthropic:claude-sonnet-4-0',
+ # Register static instructions using a keyword argument to the agent.
+ # For more complex dynamically-generated instructions, see the example below.
+ instructions='Be concise, reply with one sentence.',
)
# Run the agent synchronously, conducting a conversation with the LLM.
-# Here the exchange should be very short: PydanticAI will send the system prompt and the user query to the LLM,
-# the model will return a text response. See below for a more complex run.
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
"""
@@ -87,13 +90,15 @@ The first known use of "hello, world" was in a 1974 textbook about the C program
"""
```
-_(This example is complete, it can be run "as is")_
+_(This example is complete, it can be run "as is", assuming you've [installed the `pydantic_ai` package](https://ai.pydantic.dev/install))_
-Not very interesting yet, but we can easily add "tools", dynamic system prompts, and structured responses to build more powerful agents.
+The exchange will be very short: Pydantic AI will send the instructions and the user prompt to the LLM, and the model will return a text response.
+
+Not very interesting yet, but we can easily add [tools](https://ai.pydantic.dev/tools), [dynamic instructions](https://ai.pydantic.dev/agents#instructions), and [structured outputs](https://ai.pydantic.dev/output) to build more powerful agents.
## Tools & Dependency Injection Example
-Here is a concise example using PydanticAI to build a support agent for a bank:
+Here is a concise example using Pydantic AI to build a support agent for a bank:
**(Better documented example [in the docs](https://ai.pydantic.dev/#tools-dependency-injection-example))**
@@ -107,18 +112,23 @@ from bank_database import DatabaseConn
# SupportDependencies is used to pass data, connections, and logic into the model that will be needed when running
-# system prompt and tool functions. Dependency injection provides a type-safe way to customise the behavior of your agents.
+# instructions and tool functions. Dependency injection provides a type-safe way to customise the behavior of your agents.
@dataclass
class SupportDependencies:
customer_id: int
db: DatabaseConn
-# This pydantic model defines the structure of the output returned by the agent.
+# This Pydantic model defines the structure of the output returned by the agent.
class SupportOutput(BaseModel):
- support_advice: str = Field(description='Advice returned to the customer')
- block_card: bool = Field(description="Whether to block the customer's card")
- risk: int = Field(description='Risk level of query', ge=0, le=10)
+ support_advice: str
+ """Advice returned to the customer""" # (14)!
+ block_card: bool
+ """Whether to block the customer's card"""
+ risk: int = Field(ge=0, le=10)
+ """Risk level of query"""
+ # The docstrings of fields on a Pydantic model are passed to the LLM,
+ # so that it has all the context needed to generate a value.
# This agent will act as first-tier support in a bank.
@@ -130,23 +140,23 @@ support_agent = Agent(
# The response from the agent will, be guaranteed to be a SupportOutput,
# if validation fails the agent is prompted to try again.
output_type=SupportOutput,
- system_prompt=(
+ instructions=(
'You are a support agent in our bank, give the '
'customer support and judge the risk level of their query.'
),
)
-# Dynamic system prompts can make use of dependency injection.
+# Dynamic instructions can make use of dependency injection.
# Dependencies are carried via the `RunContext` argument, which is parameterized with the `deps_type` from above.
# If the type annotation here is wrong, static type checkers will catch it.
-@support_agent.system_prompt
+@support_agent.instructions
async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str:
customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id)
return f"The customer's name is {customer_name!r}"
-# `tool` let you register functions which the LLM may call while responding to a user.
+# The `tool` decorator let you register functions which the LLM may call while responding to a user.
# Again, dependencies are carried via `RunContext`, any other arguments become the tool schema passed to the LLM.
# Pydantic is used to validate these arguments, and errors are passed back to the LLM so it can retry.
@support_agent.tool
@@ -187,8 +197,10 @@ async def main():
## Next Steps
-To try PydanticAI yourself, follow the instructions [in the examples](https://ai.pydantic.dev/examples/).
+To try Pydantic AI for yourself, [install it](https://ai.pydantic.dev/install) and follow the instructions [in the examples](https://ai.pydantic.dev/examples/).
+
+Read the [docs](https://ai.pydantic.dev/agents/) to learn more about building applications with Pydantic AI.
-Read the [docs](https://ai.pydantic.dev/agents/) to learn more about building applications with PydanticAI.
+Read the [API Reference](https://ai.pydantic.dev/api/agent/) to understand Pydantic AI's interface.
-Read the [API Reference](https://ai.pydantic.dev/api/agent/) to understand PydanticAI's interface.
+Join [Slack](https://logfire.pydantic.dev/docs/join-slack/) or file an issue on [GitHub](https://github.com/pydantic/pydantic-ai/issues) if you have any questions.
diff --git a/docs/.partials/index-header.html b/docs/.partials/index-header.html
index cdb95a937..85a47be41 100644
--- a/docs/.partials/index-header.html
+++ b/docs/.partials/index-header.html
@@ -1,11 +1,11 @@
+
+
- Agent Framework / shim to use Pydantic with LLMs + LLM Agent Framework, the Pydantic way
- PydanticAI is a Python agent framework designed to make it less painful to - build production grade applications with Generative AI. + Pydantic AI is a Python agent framework designed to help you + quickly, confidently, and painlessly build production grade applications and workflows with Generative AI.
diff --git a/docs/agents.md b/docs/agents.md index 3fe60f7eb..87fc27ca2 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -9,10 +9,10 @@ The [`Agent`][pydantic_ai.Agent] class has full API documentation, but conceptua | **Component** | **Description** | |-----------------------------------------------|-----------------------------------------------------------------------------------------------------------| -| [System prompt(s)](#system-prompts) | A set of instructions for the LLM written by the developer. | +| [Instructions](#instructions) | A set of instructions for the LLM written by the developer. | | [Function tool(s)](tools.md) | Functions that the LLM may call to get information while generating a response. | | [Structured output type](output.md) | The structured datatype the LLM must return at the end of a run, if specified. | -| [Dependency type constraint](dependencies.md) | System prompt functions, tools, and output validators may all use dependencies when they're run. | +| [Dependency type constraint](dependencies.md) | Instructions functions, tools, and output functions may all use dependencies when they're run. | | [LLM model](api/models/base.md) | Optional default LLM model associated with the agent. Can also be specified when running the agent. | | [Model Settings](#additional-configuration) | Optional default model settings to help fine tune requests. Can also be specified when running the agent. | @@ -733,10 +733,10 @@ Note that returning an empty string will result in no instruction message added. Validation errors from both function tool parameter validation and [structured output validation](output.md#structured-output) can be passed back to the model with a request to retry. -You can also raise [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] from within a [tool](tools.md) or [output validator function](output.md#output-validator-functions) to tell the model it should retry generating a response. +You can also raise [`ModelRetry`][pydantic_ai.exceptions.ModelRetry] from within a [tool](tools.md) or [output function](output.md#output-functions) to tell the model it should retry generating a response. -- The default retry count is **1** but can be altered for the [entire agent][pydantic_ai.Agent.__init__], a [specific tool][pydantic_ai.Agent.tool], or an [output validator][pydantic_ai.Agent.__init__]. -- You can access the current retry count from within a tool or output validator via [`ctx.retry`][pydantic_ai.tools.RunContext]. +- The default retry count is **1** but can be altered for the [entire agent][pydantic_ai.Agent.__init__], a [specific tool][pydantic_ai.Agent.tool], or [outputs][pydantic_ai.Agent.__init__]. +- You can access the current retry count from within a tool or output function via [`ctx.retry`][pydantic_ai.tools.RunContext]. Here's an example: diff --git a/docs/index.md b/docs/index.md index 3290e7924..b87a250ac 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,52 +2,56 @@ --8<-- "docs/.partials/index-header.html" -FastAPI revolutionized web development by offering an innovative and ergonomic design, built on the foundation of [Pydantic](https://docs.pydantic.dev). +FastAPI revolutionized web development by offering an innovative and ergonomic design, built on the foundation of [Pydantic](https://docs.pydantic.dev) and modern Python features like type hints. -Similarly, virtually every agent framework and LLM library in Python uses Pydantic, yet when we began to use LLMs in [Pydantic Logfire](https://pydantic.dev/logfire), we couldn't find anything that gave us the same feeling. +Yet despite the fact that virtually every agent framework and LLM library in Python uses Pydantic, when we began to use LLMs in [Pydantic Logfire](https://pydantic.dev/logfire), we couldn't find anything that gave us the same feeling. -We built PydanticAI with one simple aim: to bring that FastAPI feeling to GenAI app development. +We built Pydantic AI with one simple aim: to bring that FastAPI feeling to GenAI app and agent development. -## Why use PydanticAI +## Why use Pydantic AI -* __Built by the Pydantic Team__: -Built by the team behind [Pydantic](https://docs.pydantic.dev/latest/) (the validation layer of the OpenAI SDK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more). +1. __Built by the Pydantic Team__: +[Pydantic](https://docs.pydantic.dev/latest/) is the validation layer of the OpenAI SDK, the Google ADK, the Anthropic SDK, LangChain, LlamaIndex, AutoGPT, Transformers, CrewAI, Instructor and many more. _Why use the derivative when you can go straight to the source?_ :smiley: -* __Model-agnostic__: -Supports OpenAI, Anthropic, Gemini, Deepseek, Ollama, Groq, Cohere, and Mistral, and there is a simple interface to implement support for [other models](models/index.md). +2. __Model-agnostic__: +Supports virtually every [model](models/index.md) and provider under the sun: OpenAI, Anthropic, Gemini, DeepSeek, Ollama, Grok, Cohere, and Mistral; Azure AI Foundry, Amazon Bedrock, Google Vertex AI, Groq, Together AI, Fireworks AI, OpenRouter, and Heroku. If your favorite model or provider is not listed, you can easily implement a [custom model](models/index.md#custom-models). -* __Pydantic Logfire Integration__: -Seamlessly [integrates](logfire.md) with [Pydantic Logfire](https://pydantic.dev/logfire) for real-time debugging, performance monitoring, and behavior tracking of your LLM-powered applications. +3. __Seamless Observability__: +Tightly [integrates](logfire.md) with [Pydantic Logfire](https://pydantic.dev/logfire), our general-purpose OpenTelemetry observability platform, for real-time debugging, evals-based performance monitoring, and behavior and cost tracking. If you already have an observability platform that supports OTel, you can use that too. -* __Type-safe__: -Designed to make [type checking](agents.md#static-type-checking) as powerful and informative as possible for you. +4. __Fully Type-safe__: +Designed to give your IDE or AI coding agent as much context as possible for auto-completion and [type checking](agents.md#static-type-checking), moving entire classes of errors from runtime to write-time for a bit of that Rust "if it compiles, it works" feel. -* __Python-centric Design__: -Leverages Python's familiar control flow and agent composition to build your AI-driven projects, making it easy to apply standard Python best practices you'd use in any other (non-AI) project. +5. __Powerful Evals__: +Enables you to systematically test and [evaluate](evals.md) the performance and accuracy of the agentic systems you build, and monitor the performance over time in Pydantic Logfire. -* __Structured Responses__: -Harnesses the power of [Pydantic](https://docs.pydantic.dev/latest/) to [validate and structure](output.md#structured-output) model outputs, ensuring responses are consistent across runs. +6. __MCP and A2A__: +Integrates the [Model Context Protocol](mcp/index.md) and [Agent2Agent](a2a.md) standards to give your agent access to external tools and data and let it interoperate with other agents. -* __Dependency Injection System__: -Offers an optional [dependency injection](dependencies.md) system to provide data and services to your agent's [system prompts](agents.md#system-prompts), [tools](tools.md) and [output validators](output.md#output-validator-functions). -This is useful for testing and eval-driven iterative development. +7. __Multi-Modal Input__: +Lets you easily share images, documents, videos and audio [input](input.md) with the LLM to go beyond the limitations of text. -* __Streamed Responses__: -Provides the ability to [stream](output.md#streamed-results) LLM responses continuously, with immediate validation, ensuring real time access to validated outputs. +8. __Streamed Outputs__: +Provides the ability to [stream](output.md#streamed-results) structured output continuously, with immediate validation, ensuring real time access to generated data. -* __Graph Support__: -[Pydantic Graph](graph.md) provides a powerful way to define graphs using typing hints, this is useful in complex applications where standard control flow can degrade to spaghetti code. +9. __Dependency Injection__: +Offers an optional [dependency injection](dependencies.md) system to provide data and services to your agent's [instructions](agents.md#instructions), [tools](tools.md) and [output functions](output.md#output-functions). + +10. __Graph Support__: +Provides a powerful way to define [graphs](graph.md) using type hints, for use in complex applications where standard control flow can degrade to spaghetti code. + +Realistically though, no list is going to be as convincing as [giving it a try](#next-steps) and seeing how it makes you feel! ## Hello World Example -Here's a minimal example of PydanticAI: +Here's a minimal example of Pydantic AI: ```python {title="hello_world.py"} from pydantic_ai import Agent agent = Agent( # (1)! - 'google-gla:gemini-1.5-flash', - system_prompt='Be concise, reply with one sentence.', # (2)! + 'anthropic:claude-sonnet-4-0', + instructions='Be concise, reply with one sentence.', # (2)! ) result = agent.run_sync('Where does "hello world" come from?') # (3)! @@ -57,19 +61,19 @@ The first known use of "hello, world" was in a 1974 textbook about the C program """ ``` -1. We configure the agent to use [Gemini 1.5's Flash](api/models/gemini.md) model, but you can also set the model when running the agent. -2. Register a static [system prompt](agents.md#system-prompts) using a keyword argument to the agent. -3. [Run the agent](agents.md#running-agents) synchronously, conducting a conversation with the LLM. +1. We configure the agent to use [Anthropic's Claude Sonnet 4.0](api/models/anthropic.md) model, but you can also set the model when running the agent. +2. Register static [instructions](agents.md#instructions) using a keyword argument to the agent. +3. [Run the agent](agents.md#running-agents) synchronously, starting a conversation with the LLM. -_(This example is complete, it can be run "as is")_ +_(This example is complete, it can be run "as is", assuming you've [installed the `pydantic_ai` package](install.md))_ -The exchange should be very short: PydanticAI will send the system prompt and the user query to the LLM, the model will return a text response. +The exchange will be very short: Pydantic AI will send the instructions and the user prompt to the LLM, and the model will return a text response. -Not very interesting yet, but we can easily add "tools", dynamic system prompts, and structured responses to build more powerful agents. +Not very interesting yet, but we can easily add [tools](tools.md), [dynamic instructions](agents.md#instructions), and [structured outputs](output.md) to build more powerful agents. ## Tools & Dependency Injection Example -Here is a concise example using PydanticAI to build a support agent for a bank: +Here is a concise example using Pydantic AI to build a support agent for a bank: ```python {title="bank_support.py"} from dataclasses import dataclass @@ -87,23 +91,26 @@ class SupportDependencies: # (3)! class SupportOutput(BaseModel): # (13)! - support_advice: str = Field(description='Advice returned to the customer') - block_card: bool = Field(description="Whether to block the customer's card") - risk: int = Field(description='Risk level of query', ge=0, le=10) + support_advice: str + """Advice returned to the customer""" # (14)! + block_card: bool + """Whether to block the customer's card""" + risk: int = Field(ge=0, le=10) + """Risk level of query""" support_agent = Agent( # (1)! 'openai:gpt-4o', # (2)! deps_type=SupportDependencies, output_type=SupportOutput, # (9)! - system_prompt=( # (4)! + instructions=( # (4)! 'You are a support agent in our bank, give the ' 'customer support and judge the risk level of their query.' ), ) -@support_agent.system_prompt # (5)! +@support_agent.instructions # (5)! async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str: customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id) return f"The customer's name is {customer_name!r}" @@ -140,28 +147,30 @@ async def main(): 1. This [agent](agents.md) will act as first-tier support in a bank. Agents are generic in the type of dependencies they accept and the type of output they return. In this case, the support agent has type `#!python Agent[SupportDependencies, SupportOutput]`. 2. Here we configure the agent to use [OpenAI's GPT-4o model](api/models/openai.md), you can also set the model when running the agent. -3. The `SupportDependencies` dataclass is used to pass data, connections, and logic into the model that will be needed when running [system prompt](agents.md#system-prompts) and [tool](tools.md) functions. PydanticAI's system of dependency injection provides a [type-safe](agents.md#static-type-checking) way to customise the behavior of your agents, and can be especially useful when running [unit tests](testing.md) and evals. -4. Static [system prompts](agents.md#system-prompts) can be registered with the [`system_prompt` keyword argument][pydantic_ai.Agent.__init__] to the agent. -5. Dynamic [system prompts](agents.md#system-prompts) can be registered with the [`@agent.system_prompt`][pydantic_ai.Agent.system_prompt] decorator, and can make use of dependency injection. Dependencies are carried via the [`RunContext`][pydantic_ai.tools.RunContext] argument, which is parameterized with the `deps_type` from above. If the type annotation here is wrong, static type checkers will catch it. -6. [`tool`](tools.md) let you register functions which the LLM may call while responding to a user. Again, dependencies are carried via [`RunContext`][pydantic_ai.tools.RunContext], any other arguments become the tool schema passed to the LLM. Pydantic is used to validate these arguments, and errors are passed back to the LLM so it can retry. +3. The `SupportDependencies` dataclass is used to pass data, connections, and logic into the model that will be needed when running [instructions](agents.md#instructions) and [tool](tools.md) functions. Pydantic AI's system of dependency injection provides a [type-safe](agents.md#static-type-checking) way to customise the behavior of your agents, and can be especially useful when running [unit tests](testing.md) and evals. +4. Static [instructions](agents.md#instructions) can be registered with the [`instructions` keyword argument][pydantic_ai.Agent.__init__] to the agent. +5. Dynamic [instructions](agents.md#instructions) can be registered with the [`@agent.instructions`][pydantic_ai.Agent.instructions] decorator, and can make use of dependency injection. Dependencies are carried via the [`RunContext`][pydantic_ai.tools.RunContext] argument, which is parameterized with the `deps_type` from above. If the type annotation here is wrong, static type checkers will catch it. +6. The [`@agent.tool`](tools.md) decorator let you register functions which the LLM may call while responding to a user. Again, dependencies are carried via [`RunContext`][pydantic_ai.tools.RunContext], any other arguments become the tool schema passed to the LLM. Pydantic is used to validate these arguments, and errors are passed back to the LLM so it can retry. 7. The docstring of a tool is also passed to the LLM as the description of the tool. Parameter descriptions are [extracted](tools.md#function-tools-and-schema) from the docstring and added to the parameter schema sent to the LLM. 8. [Run the agent](agents.md#running-agents) asynchronously, conducting a conversation with the LLM until a final response is reached. Even in this fairly simple case, the agent will exchange multiple messages with the LLM as tools are called to retrieve an output. -9. The response from the agent will, be guaranteed to be a `SupportOutput`, if validation fails [reflection](agents.md#reflection-and-self-correction) will mean the agent is prompted to try again. +9. The response from the agent will be guaranteed to be a `SupportOutput`. If validation fails [reflection](agents.md#reflection-and-self-correction), the agent is prompted to try again. 10. The output will be validated with Pydantic to guarantee it is a `SupportOutput`, since the agent is generic, it'll also be typed as a `SupportOutput` to aid with static type checking. -11. In a real use case, you'd add more tools and a longer system prompt to the agent to extend the context it's equipped with and support it can provide. +11. In a real use case, you'd add more tools and longer instructions to the agent to extend the context it's equipped with and support it can provide. 12. This is a simple sketch of a database connection, used to keep the example short and readable. In reality, you'd be connecting to an external database (e.g. PostgreSQL) to get information about customers. 13. This [Pydantic](https://docs.pydantic.dev) model is used to constrain the structured data returned by the agent. From this simple definition, Pydantic builds the JSON Schema that tells the LLM how to return the data, and performs validation to guarantee the data is correct at the end of the run. +14. The docstrings of fields on a Pydantic model are passed to the LLM as part of the structured outputs definition, so that it has all the context needed to generate a value. !!! tip "Complete `bank_support.py` example" The code included here is incomplete for the sake of brevity (the definition of `DatabaseConn` is missing); you can find the complete `bank_support.py` example [here](examples/bank-support.md). ## Instrumentation with Pydantic Logfire +Even a simple agent with just a handful of tools can result in a lot of back-and-forth with the LLM, making it nearly impossible to be confident of what's going on just from reading the code. To understand the flow of the above runs, we can watch the agent in action using Pydantic Logfire. -To do this, we need to set up logfire, and add the following to our code: +To do this, we need to [set up Logfire](logfire.md#using-logfire), and add the following to our code: -```python {title="bank_support_with_logfire.py" hl_lines="6-9 21" test="skip" lint="skip"} +```python {title="bank_support_with_logfire.py" hl_lines="6-10" test="skip" lint="skip"} ... from pydantic_ai import Agent, RunContext @@ -170,7 +179,8 @@ from bank_database import DatabaseConn import logfire logfire.configure() # (1)! -logfire.instrument_asyncpg() # (2)! +logfire.instrument_pydantic_ai() # (2)! +logfire.instrument_asyncpg() # (3)! ... @@ -182,12 +192,12 @@ support_agent = Agent( 'You are a support agent in our bank, give the ' 'customer support and judge the risk level of their query.' ), - instrument=True, ) ``` -1. Configure logfire, this will fail if project is not set up. -2. In our demo, `DatabaseConn` uses [`asyncpg`]() to connect to a PostgreSQL database, so [`logfire.instrument_asyncpg()`](https://magicstack.github.io/asyncpg/current/) is used to log the database queries. +1. Configure the Logfire SDK, this will fail if project is not set up. +2. This will instrument all Pydantic AI agents used from here on out. If you want to instrument only a specific agent, you can pass the [`instrument=True` keyword argument][pydantic_ai.Agent.__init__] to the agent. +3. In our demo, `DatabaseConn` uses [`asyncpg`]() to connect to a PostgreSQL database, so [`logfire.instrument_asyncpg()`](https://magicstack.github.io/asyncpg/current/) is used to log the database queries. That's enough to get the following view of your agent in action: @@ -195,28 +205,28 @@ That's enough to get the following view of your agent in action: See [Monitoring and Performance](logfire.md) to learn more. -## llms.txt +## `llms.txt` -The PydanticAI documentation is available in the [llms.txt](https://llmstxt.org/) format. -This format is defined in Markdown and suited for large language models. +The Pydantic AI documentation is available in the [llms.txt](https://llmstxt.org/) format. +This format is defined in Markdown and suited for LLMs and AI coding assistants and agents. Two formats are available: -- [llms.txt](https://ai.pydantic.dev/llms.txt): a file containing a brief description +- [`llms.txt`](https://ai.pydantic.dev/llms.txt): a file containing a brief description of the project, along with links to the different sections of the documentation. The structure of this file is described in details [here](https://llmstxt.org/#format). -- [llms-full.txt](https://ai.pydantic.dev/llms-full.txt): Similar to the `llms.txt` file, +- [`llms-full.txt`](https://ai.pydantic.dev/llms-full.txt): Similar to the `llms.txt` file, but every link content is included. Note that this file may be too large for some LLMs. -As of today, these files *cannot* be natively leveraged by LLM frameworks or IDEs. Alternatively, -an [MCP server](https://modelcontextprotocol.io/) can be implemented to properly parse the `llms.txt` -file. +As of today, these files are not automatically leveraged by IDEs or coding agents, but they will use it if you provide a link or the full text. ## Next Steps -To try PydanticAI yourself, follow the instructions [in the examples](examples/index.md). +To try Pydantic AI for yourself, [install it](install.md) and follow the instructions [in the examples](examples/index.md). + +Read the [docs](agents.md) to learn more about building applications with Pydantic AI. -Read the [docs](agents.md) to learn more about building applications with PydanticAI. +Read the [API Reference](api/agent.md) to understand Pydantic AI's interface. -Read the [API Reference](api/agent.md) to understand PydanticAI's interface. +Join [Slack](https://logfire.pydantic.dev/docs/join-slack/) or file an issue on [GitHub](https://github.com/pydantic/pydantic-ai/issues) if you have any questions. diff --git a/docs/models/index.md b/docs/models/index.md index c87c41912..55fc7707e 100644 --- a/docs/models/index.md +++ b/docs/models/index.md @@ -28,7 +28,7 @@ PydanticAI also comes with [`TestModel`](../api/models/test.md) and [`FunctionMo for testing and development. To use each model provider, you need to configure your local environment and make sure you have the right -packages installed. +packages installed. If you try to use the model without having done so, you'll be told what to install. ## Models and Providers @@ -59,6 +59,9 @@ If you want to use a different provider or profile, you can instantiate a model ## Custom Models +!!! note + If a model API is compatible with the OpenAI API, you do not need a custom model class and can provide your own [custom provider](openai.md#openai-compatible-models) instead. + To implement support for a model API that's not already supported, you will need to subclass the [`Model`][pydantic_ai.models.Model] abstract base class. For streaming, you'll also need to implement the [`StreamedResponse`][pydantic_ai.models.StreamedResponse] abstract base class. @@ -66,7 +69,6 @@ The best place to start is to review the source code for existing implementation For details on when we'll accept contributions adding new models to PydanticAI, see the [contributing guidelines](../contributing.md#new-model-rules). -If a model API is compatible with the OpenAI API, you do not need a custom model class and can provide your own [custom provider](openai.md#openai-compatible-models) instead. ## Fallback Model diff --git a/examples/pydantic_ai_examples/bank_support.py b/examples/pydantic_ai_examples/bank_support.py index d7fc74a4a..7fb49afd7 100644 --- a/examples/pydantic_ai_examples/bank_support.py +++ b/examples/pydantic_ai_examples/bank_support.py @@ -7,7 +7,7 @@ from dataclasses import dataclass -from pydantic import BaseModel, Field +from pydantic import BaseModel from pydantic_ai import Agent, RunContext @@ -42,16 +42,19 @@ class SupportDependencies: class SupportOutput(BaseModel): - support_advice: str = Field(description='Advice returned to the customer') - block_card: bool = Field(description='Whether to block their card or not') - risk: int = Field(description='Risk level of query', ge=0, le=10) + support_advice: str + """Advice returned to the customer""" + block_card: bool + """Whether to block their card or not""" + risk: int + """Risk level of query""" support_agent = Agent( 'openai:gpt-4o', deps_type=SupportDependencies, output_type=SupportOutput, - system_prompt=( + instructions=( 'You are a support agent in our bank, give the ' 'customer support and judge the risk level of their query. ' "Reply using the customer's name." @@ -59,7 +62,7 @@ class SupportOutput(BaseModel): ) -@support_agent.system_prompt +@support_agent.instructions async def add_customer_name(ctx: RunContext[SupportDependencies]) -> str: customer_name = await ctx.deps.db.customer_name(id=ctx.deps.customer_id) return f"The customer's name is {customer_name!r}" diff --git a/examples/pyproject.toml b/examples/pyproject.toml index 1e7ec0473..9f501dca1 100644 --- a/examples/pyproject.toml +++ b/examples/pyproject.toml @@ -13,7 +13,7 @@ bump = true [project] name = "pydantic-ai-examples" dynamic = ["version", "dependencies"] -description = "Examples of how to use PydanticAI and what it can do." +description = "Examples of how to use Pydantic AI and what it can do." authors = [{ name = "Samuel Colvin", email = "samuel@pydantic.dev" }] license = "MIT" readme = "README.md" diff --git a/mkdocs.yml b/mkdocs.yml index c0602c07a..4e9985642 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ -site_name: PydanticAI -site_description: Agent Framework / shim to use Pydantic with LLMs +site_name: Pydantic AI +site_description: LLM Agent Framework, the Pydantic way strict: true site_url: https://ai.pydantic.dev