Merge branch 'main' into dmontagu/new-graph-api

Author: dmontagu

.gitignore

@@ -20,3 +20,4 @@ node_modules/
 .coverage*
 /test_tmp/
 .mcp.json
+.claude/

README.md

@@ -57,7 +57,7 @@ Integrates the [Model Context Protocol](https://ai.pydantic.dev/mcp/client), [Ag
 Easily lets you flag that certain tool calls [require approval](https://ai.pydantic.dev/deferred-tools#human-in-the-loop-tool-approval) before they can proceed, possibly depending on tool call arguments, conversation history, or user preferences.
 
 8. **Durable Execution**:
-Enables you to build [durable agents](https://ai.pydantic.dev/temporal) that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability.
+Enables you to build [durable agents](https://ai.pydantic.dev/durable_execution/overview/) that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability.
 
 9. **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.

docs/ag-ui.md

@@ -204,18 +204,18 @@ user experiences with frontend user interfaces.
 
 ### Events
 
-Pydantic AI tools can send
-[AG-UI events](https://docs.ag-ui.com/concepts/events) simply by defining a tool
-which returns a (subclass of)
-[`BaseEvent`](https://docs.ag-ui.com/sdk/python/core/events#baseevent), which allows
-for custom events and state updates.
+Pydantic AI tools can send [AG-UI events](https://docs.ag-ui.com/concepts/events) simply by returning a
+[`ToolReturn`](tools-advanced.md#advanced-tool-returns) object with a
+[`BaseEvent`](https://docs.ag-ui.com/sdk/python/core/events#baseevent) (or a list of events) as `metadata`,
+which allows for custom events and state updates.
 
 ```python {title="ag_ui_tool_events.py"}
 from ag_ui.core import CustomEvent, EventType, StateSnapshotEvent
 from pydantic import BaseModel
 
 from pydantic_ai import Agent, RunContext
 from pydantic_ai.ag_ui import StateDeps
+from pydantic_ai.messages import ToolReturn
 
 
 class DocumentState(BaseModel):
@@ -233,27 +233,35 @@ app = agent.to_ag_ui(deps=StateDeps(DocumentState()))
 
 
 @agent.tool
-async def update_state(ctx: RunContext[StateDeps[DocumentState]]) -> StateSnapshotEvent:
-    return StateSnapshotEvent(
-        type=EventType.STATE_SNAPSHOT,
-        snapshot=ctx.deps.state,
+async def update_state(ctx: RunContext[StateDeps[DocumentState]]) -> ToolReturn:
+    return ToolReturn(
+        return_value='State updated',
+        metadata=[
+            StateSnapshotEvent(
+                type=EventType.STATE_SNAPSHOT,
+                snapshot=ctx.deps.state,
+            ),
+        ],
     )
 
 
 @agent.tool_plain
-async def custom_events() -> list[CustomEvent]:
-    return [
-        CustomEvent(
-            type=EventType.CUSTOM,
-            name='count',
-            value=1,
-        ),
-        CustomEvent(
-            type=EventType.CUSTOM,
-            name='count',
-            value=2,
-        ),
-    ]
+async def custom_events() -> ToolReturn:
+    return ToolReturn(
+        return_value='Count events sent',
+        metadata=[
+            CustomEvent(
+                type=EventType.CUSTOM,
+                name='count',
+                value=1,
+            ),
+            CustomEvent(
+                type=EventType.CUSTOM,
+                name='count',
+                value=2,
+            ),
+        ]
+    )
 ```
 
 Since `app` is an ASGI application, it can be used with any ASGI server:

docs/agents.md

@@ -280,7 +280,6 @@ async def main():
     [
         UserPromptNode(
             user_prompt='What is the capital of France?',
-            instructions=None,
             instructions_functions=[],
             system_prompts=(),
             system_prompt_functions=[],
@@ -343,7 +342,6 @@ async def main():
         [
             UserPromptNode(
                 user_prompt='What is the capital of France?',
-                instructions=None,
                 instructions_functions=[],
                 system_prompts=(),
                 system_prompt_functions=[],

docs/builtin-tools.md

@@ -26,25 +26,38 @@ making it ideal for queries that require up-to-date data.
 
 | Provider | Supported | Notes |
 |----------|-----------|-------|
-| OpenAI | ✅ | Full feature support |
+| OpenAI Responses | ✅ | Full feature support. To include search results on the [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart], set the `openai_include_web_search_sources` setting to `True` on [`OpenAIResponsesModelSettings`][pydantic_ai.models.openai.OpenAIResponsesModelSettings]. |
 | Anthropic | ✅ | Full feature support |
+| Google | ✅ | No parameter support. No [`BuiltinToolCallPart`][pydantic_ai.messages.BuiltinToolCallPart] or [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart] is generated when streaming. Using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
 | Groq | ✅ | Limited parameter support. To use web search capabilities with Groq, you need to use the [compound models](https://console.groq.com/docs/compound). |
-| Google | ✅ | No parameter support. Google does not support using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time. To use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+| OpenAI Chat Completions | ❌ | Not supported |
 | Bedrock | ❌ | Not supported |
 | Mistral | ❌ | Not supported |
 | Cohere | ❌ | Not supported |
 | HuggingFace | ❌ | Not supported |
 
 ### Usage
 
-```py title="web_search_basic.py"
+```py title="web_search_anthropic.py"
 from pydantic_ai import Agent, WebSearchTool
 
 agent = Agent('anthropic:claude-sonnet-4-0', builtin_tools=[WebSearchTool()])
 
 result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
-# > Scientists have developed a universal AI detector that can identify deepfake videos.
+print(result.output)
+#> Scientists have developed a universal AI detector that can identify deepfake videos.
+```
+
+With OpenAI, you must use their responses API to access the web search tool.
+
+```py title="web_search_openai.py"
+from pydantic_ai import Agent, WebSearchTool
+
+agent = Agent('openai-responses:gpt-4.1', builtin_tools=[WebSearchTool()])
 
+result = agent.run_sync('Give me a sentence with the biggest news in AI this week.')
+print(result.output)
+#> Scientists have developed a universal AI detector that can identify deepfake videos.
 ```
 
 ### Configuration Options
@@ -98,9 +111,9 @@ in a secure environment, making it perfect for computational tasks, data analysi
 
 | Provider | Supported | Notes |
 |----------|-----------|-------|
-| OpenAI | ✅ | |
+| OpenAI | ✅ | To include outputs on the [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart], set the `openai_include_code_execution_outputs` setting to `True` on [`OpenAIResponsesModelSettings`][pydantic_ai.models.openai.OpenAIResponsesModelSettings]. |
 | Anthropic | ✅ | |
-| Google | ✅ | Google does not support using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time. To use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+| Google | ✅ | Using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
 | Groq | ❌ | |
 | Bedrock | ❌ | |
 | Mistral | ❌ | |
@@ -127,7 +140,7 @@ allowing it to pull up-to-date information from the web.
 
 | Provider | Supported | Notes |
 |----------|-----------|-------|
-| Google | ✅ | Google does not support using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time. To use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
+| Google | ✅ | No [`BuiltinToolCallPart`][pydantic_ai.messages.BuiltinToolCallPart] or [`BuiltinToolReturnPart`][pydantic_ai.messages.BuiltinToolReturnPart] is currently generated; please submit an issue if you need this. Using built-in tools and user tools (including [output tools](output.md#tool-output)) at the same time is not supported; to use structured output, use [`PromptedOutput`](output.md#prompted-output) instead. |
 | OpenAI | ❌ | |
 | Anthropic | ❌ | |
 | Groq | ❌ | |

docs/deferred-tools.md

@@ -132,17 +132,21 @@ print(result.all_messages())
     ),
     ModelRequest(
         parts=[
-            ToolReturnPart(
-                tool_name='delete_file',
-                content='Deleting files is not allowed',
-                tool_call_id='delete_file',
-                timestamp=datetime.datetime(...),
-            ),
             ToolReturnPart(
                 tool_name='update_file',
                 content="File 'README.md' updated: 'Hello, world!'",
                 tool_call_id='update_file_readme',
                 timestamp=datetime.datetime(...),
+            )
+        ]
+    ),
+    ModelRequest(
+        parts=[
+            ToolReturnPart(
+                tool_name='delete_file',
+                content='Deleting files is not allowed',
+                tool_call_id='delete_file',
+                timestamp=datetime.datetime(...),
             ),
             ToolReturnPart(
                 tool_name='update_file',

docs/durable_execution/dbos.md

@@ -153,21 +153,6 @@ You can customize DBOS's retry policy using [step configuration](#step-configura
 
 ## Observability with Logfire
 
-When using [Pydantic Logfire](../logfire.md), we **recommend disabling DBOS's built-in OpenTelemetry tracing**.
-DBOS automatically wraps workflow and step execution in spans, while Pydantic AI and Logfire already emit spans for the same function calls, model requests, and tool invocations. Without disabling DBOS tracing, these operations may appear twice in your trace tree.
+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.
 
-To disable DBOS traces and logs, you can set `disable_otlp=True` in `DBOSConfig`. For example:
-
-
-```python {title="dbos_no_traces.py" test="skip"}
-from dbos import DBOS, DBOSConfig
-
-dbos_config: DBOSConfig = {
-    'name': 'pydantic_dbos_agent',
-    'system_database_url': 'sqlite:///dbostest.sqlite',
-    'disable_otlp': True  # (1)!
-}
-DBOS(config=dbos_config)
-```
-
-1. If `True`, disables OpenTelemetry tracing and logging for DBOS. Default is `False`.
+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/durable_execution/temporal.md

@@ -172,7 +172,7 @@ As workflows and activities run in separate processes, any values passed between
 
 To account for these limitations, tool functions and the [event stream handler](#streaming) running inside activities receive a limited version of the agent's [`RunContext`][pydantic_ai.tools.RunContext], and it's your responsibility to make sure that the [dependencies](../dependencies.md) object provided to [`TemporalAgent.run()`][pydantic_ai.durable_exec.temporal.TemporalAgent.run] can be serialized using Pydantic.
 
-Specifically, only the `deps`, `retries`, `tool_call_id`, `tool_name`, `tool_call_approved`, `retry`, and `run_step` fields are available by default, and trying to access `model`, `usage`, `prompt`, `messages`, or `tracer` will raise an error.
+Specifically, only the `deps`, `retries`, `tool_call_id`, `tool_name`, `tool_call_approved`, `retry`, `max_retries` and `run_step` fields are available by default, and trying to access `model`, `usage`, `prompt`, `messages`, or `tracer` will raise an error.
 If you need one or more of these attributes to be available inside activities, you can create a [`TemporalRunContext`][pydantic_ai.durable_exec.temporal.TemporalRunContext] subclass with custom `serialize_run_context` and `deserialize_run_context` class methods and pass it to [`TemporalAgent`][pydantic_ai.durable_exec.temporal.TemporalAgent] as `run_context_type`.
 
 ### Streaming