Merge main

Author: dmontagu

.github/workflows/after-ci.yml

@@ -41,7 +41,7 @@ jobs:
 
   deploy-docs-preview:
     runs-on: ubuntu-latest
-    if: github.event.workflow_run.event == 'pull_request'
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.pull_requests[0] != null
     environment:
       name: deploy-docs-preview
 

docs/ag-ui.md

@@ -213,9 +213,8 @@ which allows for custom events and state updates.
 from ag_ui.core import CustomEvent, EventType, StateSnapshotEvent
 from pydantic import BaseModel
 
-from pydantic_ai import Agent, RunContext
+from pydantic_ai import Agent, RunContext, ToolReturn
 from pydantic_ai.ag_ui import StateDeps
-from pydantic_ai.messages import ToolReturn
 
 
 class DocumentState(BaseModel):

docs/agents.md

@@ -116,14 +116,15 @@ import asyncio
 from collections.abc import AsyncIterable
 from datetime import date
 
-from pydantic_ai import Agent, RunContext
-from pydantic_ai.messages import (
+from pydantic_ai import (
+    Agent,
     AgentStreamEvent,
     FinalResultEvent,
     FunctionToolCallEvent,
     FunctionToolResultEvent,
     PartDeltaEvent,
     PartStartEvent,
+    RunContext,
     TextPartDelta,
     ThinkingPartDelta,
     ToolCallPartDelta,
@@ -392,13 +393,14 @@ import asyncio
 from dataclasses import dataclass
 from datetime import date
 
-from pydantic_ai import Agent, RunContext
-from pydantic_ai.messages import (
+from pydantic_ai import (
+    Agent,
     FinalResultEvent,
     FunctionToolCallEvent,
     FunctionToolResultEvent,
     PartDeltaEvent,
     PartStartEvent,
+    RunContext,
     TextPartDelta,
     ThinkingPartDelta,
     ToolCallPartDelta,

docs/api/models/function.md

@@ -11,7 +11,7 @@ Here's a minimal example:
 
 ```py {title="function_model_usage.py" call_name="test_my_agent" noqa="I001"}
 from pydantic_ai import Agent
-from pydantic_ai.messages import ModelMessage, ModelResponse, TextPart
+from pydantic_ai import ModelMessage, ModelResponse, TextPart
 from pydantic_ai.models.function import FunctionModel, AgentInfo
 
 my_agent = Agent('openai:gpt-4o')

docs/builtin-tools.md

@@ -9,6 +9,7 @@ Pydantic AI supports the following builtin tools:
 - **[`WebSearchTool`][pydantic_ai.builtin_tools.WebSearchTool]**: Allows agents to search the web
 - **[`CodeExecutionTool`][pydantic_ai.builtin_tools.CodeExecutionTool]**: Enables agents to execute code in a secure environment
 - **[`UrlContextTool`][pydantic_ai.builtin_tools.UrlContextTool]**: Enables agents to pull URL contents into their context
+- **[`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool]**: Enables agents to use memory
 
 These tools are passed to the agent via the `builtin_tools` parameter and are executed by the model provider's infrastructure.
 
@@ -160,6 +161,89 @@ result = agent.run_sync('What is this? https://ai.pydantic.dev')
 # > A Python agent framework for building Generative AI applications.
 ```
 
+## Memory Tool
+
+The [`MemoryTool`][pydantic_ai.builtin_tools.MemoryTool] enables your agent to use memory.
+
+### Provider Support
+
+| Provider | Supported | Notes |
+|----------|-----------|-------|
+| Anthropic | ✅ | Requires a tool named `memory` to be defined that implements [specific sub-commands](https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool#tool-commands). You can use a subclass of [`anthropic.lib.tools.BetaAbstractMemoryTool`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/tools/_beta_builtin_memory_tool.py) as documented below. |
+| Google | ❌ | |
+| OpenAI | ❌ | |
+| Groq | ❌ | |
+| Bedrock | ❌ | |
+| Mistral | ❌ | |
+| Cohere | ❌ | |
+| HuggingFace | ❌ | |
+
+### Usage
+
+The Anthropic SDK provides an abstract [`BetaAbstractMemoryTool`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/lib/tools/_beta_builtin_memory_tool.py) class that you can subclass to create your own memory storage solution (e.g., database, cloud storage, encrypted files, etc.). Their [`LocalFilesystemMemoryTool`](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py) example can serve as a starting point.
+
+The following example uses a subclass that hard-codes a specific memory. The bits specific to Pydantic AI are the `MemoryTool` built-in tool and the `memory` tool definition that forwards commands to the `call` method of the `BetaAbstractMemoryTool` subclass.
+
+```py title="anthropic_memory.py"
+from typing import Any
+
+from anthropic.lib.tools import BetaAbstractMemoryTool
+from anthropic.types.beta import (
+    BetaMemoryTool20250818CreateCommand,
+    BetaMemoryTool20250818DeleteCommand,
+    BetaMemoryTool20250818InsertCommand,
+    BetaMemoryTool20250818RenameCommand,
+    BetaMemoryTool20250818StrReplaceCommand,
+    BetaMemoryTool20250818ViewCommand,
+)
+
+from pydantic_ai import Agent
+from pydantic_ai.builtin_tools import MemoryTool
+
+
+class FakeMemoryTool(BetaAbstractMemoryTool):
+    def view(self, command: BetaMemoryTool20250818ViewCommand) -> str:
+        return 'The user lives in Mexico City.'
+
+    def create(self, command: BetaMemoryTool20250818CreateCommand) -> str:
+        return f'File created successfully at {command.path}'
+
+    def str_replace(self, command: BetaMemoryTool20250818StrReplaceCommand) -> str:
+        return f'File {command.path} has been edited'
+
+    def insert(self, command: BetaMemoryTool20250818InsertCommand) -> str:
+        return f'Text inserted at line {command.insert_line} in {command.path}'
+
+    def delete(self, command: BetaMemoryTool20250818DeleteCommand) -> str:
+        return f'File deleted: {command.path}'
+
+    def rename(self, command: BetaMemoryTool20250818RenameCommand) -> str:
+        return f'Renamed {command.old_path} to {command.new_path}'
+
+    def clear_all_memory(self) -> str:
+        return 'All memory cleared'
+
+fake_memory = FakeMemoryTool()
+
+agent = Agent('anthropic:claude-sonnet-4-5', builtin_tools=[MemoryTool()])
+
+
+@agent.tool_plain
+def memory(**command: Any) -> Any:
+    return fake_memory.call(command)
+
+
+result = agent.run_sync('Remember that I live in Mexico City')
+print(result.output)
+"""
+Got it! I've recorded that you live in Mexico City. I'll remember this for future reference.
+"""
+
+result = agent.run_sync('Where do I live?')
+print(result.output)
+#> You live in Mexico City.
+```
+
 ## API Reference
 
 For complete API documentation, see the [API Reference](api/builtin_tools.md).

docs/cli.md

@@ -114,8 +114,8 @@ _(You'll need to add `asyncio.run(main())` to run `main`)_
 Both `Agent.to_cli()` and `Agent.to_cli_sync()` support a `message_history` parameter, allowing you to continue an existing conversation or provide conversation context:
 
 ```python {title="agent_with_history.py" test="skip"}
-from pydantic_ai import Agent
-from pydantic_ai.messages import (
+from pydantic_ai import (
+    Agent,
     ModelMessage,
     ModelRequest,
     ModelResponse,

docs/direct.md

@@ -16,8 +16,8 @@ The following functions are available:
 Here's a simple example demonstrating how to use the direct API to make a basic request:
 
 ```python title="direct_basic.py"
+from pydantic_ai import ModelRequest
 from pydantic_ai.direct import model_request_sync
-from pydantic_ai.messages import ModelRequest
 
 # Make a synchronous request to the model
 model_response = model_request_sync(
@@ -44,9 +44,8 @@ from typing import Literal
 
 from pydantic import BaseModel
 
-from pydantic_ai import ToolDefinition
+from pydantic_ai import ModelRequest, ToolDefinition
 from pydantic_ai.direct import model_request
-from pydantic_ai.messages import ModelRequest
 from pydantic_ai.models import ModelRequestParameters
 
 
@@ -110,8 +109,8 @@ As with [agents][pydantic_ai.Agent], you can enable OpenTelemetry/Logfire instru
 ```python {title="direct_instrumented.py" hl_lines="1 6 7"}
 import logfire
 
+from pydantic_ai import ModelRequest
 from pydantic_ai.direct import model_request_sync
-from pydantic_ai.messages import ModelRequest
 
 logfire.configure()
 logfire.instrument_pydantic_ai()
@@ -133,8 +132,8 @@ You can also enable OpenTelemetry on a per call basis:
 ```python {title="direct_instrumented.py" hl_lines="1 6 12"}
 import logfire
 
+from pydantic_ai import ModelRequest
 from pydantic_ai.direct import model_request_sync
-from pydantic_ai.messages import ModelRequest
 
 logfire.configure()
 

docs/durable_execution/dbos.md

@@ -123,7 +123,7 @@ Other than that, any agent and toolset will just work!
 
 ### Agent Run Context and Dependencies
 
-DBOS checkpoints workflow inputs/outputs and step outputs into a database using `jsonpickle`. This means you need to make sure [dependencies](../dependencies.md) object provided to [`DBOSAgent.run()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run] or [`DBOSAgent.run_sync()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run_sync], and tool outputs can be serialized using jsonpickle. You may also want to keep the inputs and outputs small (under \~2 MB). PostgreSQL and SQLite support up to 1 GB per field, but large objects may impact performance.
+DBOS checkpoints workflow inputs/outputs and step outputs into a database using [`pickle`](https://docs.python.org/3/library/pickle.html). This means you need to make sure [dependencies](../dependencies.md) object provided to [`DBOSAgent.run()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run] or [`DBOSAgent.run_sync()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run_sync], and tool outputs can be serialized using pickle. You may also want to keep the inputs and outputs small (under \~2 MB). PostgreSQL and SQLite support up to 1 GB per field, but large objects may impact performance.
 
 ### Streaming
 
@@ -153,6 +153,6 @@ You can customize DBOS's retry policy using [step configuration](#step-configura
 
 ## Observability with Logfire
 
-DBOS automatically generates OpenTelemetry spans for each workflow and step execution, and Pydantic AI emits spans for each agent run, model request, and tool invocation. You can send these spans to [Pydantic Logfire](../logfire.md) to get a full, end-to-end view of what's happening in your application.
+DBOS can be configured to generate OpenTelemetry spans for each workflow and step execution, and Pydantic AI emits spans for each agent run, model request, and tool invocation. You can send these spans to [Pydantic Logfire](../logfire.md) to get a full, end-to-end view of what's happening in your application.
 
 For more information about DBOS logging and tracing, please see the [DBOS docs](https://docs.dbos.dev/python/tutorials/logging-and-tracing) for details.

docs/graph.md

@@ -359,8 +359,7 @@ from dataclasses import dataclass, field
 
 from pydantic import BaseModel, EmailStr
 
-from pydantic_ai import Agent, format_as_xml
-from pydantic_ai.messages import ModelMessage
+from pydantic_ai import Agent, ModelMessage, format_as_xml
 from pydantic_graph import BaseNode, End, Graph, GraphRunContext
 
 
@@ -662,7 +661,7 @@ from pydantic_graph import (
     GraphRunContext,
 )
 from pydantic_ai import Agent, format_as_xml
-from pydantic_ai.messages import ModelMessage
+from pydantic_ai import ModelMessage
 
 ask_agent = Agent('openai:gpt-4o', output_type=str, instrument=True)
 
@@ -756,7 +755,7 @@ from pathlib import Path
 
 from pydantic_graph import End
 from pydantic_graph.persistence.file import FileStatePersistence
-from pydantic_ai.messages import ModelMessage  # noqa: F401
+from pydantic_ai import ModelMessage  # noqa: F401
 
 from ai_q_and_a_graph import Ask, question_graph, Evaluate, QuestionState, Answer
 

docs/mcp/client.md

@@ -13,7 +13,7 @@ pip/uv-add "pydantic-ai-slim[mcp]"
 
 ## Usage
 
-Pydantic AI comes with two ways to connect to MCP servers:
+Pydantic AI comes with three ways to connect to MCP servers:
 
 - [`MCPServerStreamableHTTP`][pydantic_ai.mcp.MCPServerStreamableHTTP] which connects to an MCP server using the [Streamable HTTP](https://modelcontextprotocol.io/introduction#streamable-http) transport
 - [`MCPServerSSE`][pydantic_ai.mcp.MCPServerSSE] which connects to an MCP server using the [HTTP SSE](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) transport
@@ -72,14 +72,14 @@ _(This example is complete, it can be run "as is" — you'll need to add `asynci
 
 **What's happening here?**
 
-- The model is receiving the prompt "how many days between 2000-01-01 and 2025-03-18?"
-- The model decides "Oh, I've got this `run_python_code` tool, that will be a good way to answer this question", and writes some python code to calculate the answer.
+- The model receives the prompt "What is 7 plus 5?"
+- The model decides "Oh, I've got this `add` tool, that will be a good way to answer this question"
 - The model returns a tool call
-- Pydantic AI sends the tool call to the MCP server using the SSE transport
-- The model is called again with the return value of running the code
+- Pydantic AI sends the tool call to the MCP server using the Streamable HTTP transport
+- The model is called again with the return value of running the `add` tool (12)
 - The model returns the final answer
 
-You can visualise this clearly, and even see the code that's run by adding three lines of code to instrument the example with [logfire](https://logfire.pydantic.dev/docs):
+You can visualise this clearly, and even see the tool call, by adding three lines of code to instrument the example with [logfire](https://logfire.pydantic.dev/docs):
 
 ```python {title="mcp_sse_client_logfire.py" test="skip"}
 import logfire
@@ -88,10 +88,6 @@ logfire.configure()
 logfire.instrument_pydantic_ai()
 ```
 
-Will display as follows:
-
-![Logfire run python code](../img/logfire-run-python-code.png)
-
 ### SSE Client
 
 [`MCPServerSSE`][pydantic_ai.mcp.MCPServerSSE] connects over HTTP using the [HTTP + Server Sent Events transport](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/transports/#http-with-sse) to a server.
@@ -216,10 +212,10 @@ async def main():
 
 _(This example is complete, it can be run "as is" — you'll need to add `asyncio.run(main())` to run `main`)_
 
-## Tool call customisation
+## Tool call customization
 
 The MCP servers provide the ability to set a `process_tool_call` which allows
-the customisation of tool call requests and their responses.
+the customization of tool call requests and their responses.
 
 A common use case for this is to inject metadata to the requests which the server
 call needs: