Merge branch 'main' into update-versins

Author: medaminezghal

.github/workflows/ci.yml

@@ -204,6 +204,7 @@ jobs:
           enable-cache: true
 
       - run: uv sync --package pydantic-ai-slim --only-dev
+      - run: rm coverage/.coverage.*-py3.9-* # Exclude 3.9 coverage as it gets the wrong line numbers, causing invalid failures.
       - run: uv run coverage combine coverage
 
       - run: uv run coverage html --show-contexts --title "PydanticAI coverage for ${{ github.sha }}"

docs/a2a.md

@@ -32,7 +32,7 @@ The library is designed to be used with any agentic framework, and is **not excl
 Given the nature of the A2A protocol, it's important to understand the design before using it, as a developer
 you'll need to provide some components:
 
-- [`Storage`][fasta2a.Storage]: to save and load tasks
+- [`Storage`][fasta2a.Storage]: to save and load tasks, as well as store context for conversations
 - [`Broker`][fasta2a.Broker]: to schedule tasks
 - [`Worker`][fasta2a.Worker]: to execute tasks
 
@@ -55,6 +55,28 @@ flowchart TB
 
 FastA2A allows you to bring your own [`Storage`][fasta2a.Storage], [`Broker`][fasta2a.Broker] and [`Worker`][fasta2a.Worker].
 
+#### Understanding Tasks and Context
+
+In the A2A protocol:
+
+- **Task**: Represents one complete execution of an agent. When a client sends a message to the agent, a new task is created. The agent runs until completion (or failure), and this entire execution is considered one task. The final output is stored as a task artifact.
+
+- **Context**: Represents a conversation thread that can span multiple tasks. The A2A protocol uses a `context_id` to maintain conversation continuity:
+  - When a new message is sent without a `context_id`, the server generates a new one
+  - Subsequent messages can include the same `context_id` to continue the conversation
+  - All tasks sharing the same `context_id` have access to the complete message history
+
+#### Storage Architecture
+
+The [`Storage`][fasta2a.Storage] component serves two purposes:
+
+1. **Task Storage**: Stores tasks in A2A protocol format, including their status, artifacts, and message history
+2. **Context Storage**: Stores conversation context in a format optimized for the specific agent implementation
+
+This design allows for agents to store rich internal state (e.g., tool calls, reasoning traces) as well as store task-specific A2A-formatted messages and artifacts.
+
+For example, a PydanticAI agent might store its complete internal message format (including tool calls and responses) in the context storage, while storing only the A2A-compliant messages in the task history.
+
 
 ### Installation
 
@@ -94,3 +116,12 @@ uvicorn agent_to_a2a:app --host 0.0.0.0 --port 8000
 ```
 
 Since the goal of `to_a2a` is to be a convenience method, it accepts the same arguments as the [`FastA2A`][fasta2a.FastA2A] constructor.
+
+When using `to_a2a()`, PydanticAI automatically:
+
+- Stores the complete conversation history (including tool calls and responses) in the context storage
+- Ensures that subsequent messages with the same `context_id` have access to the full conversation history
+- Persists agent results as A2A artifacts:
+  - String results become `TextPart` artifacts and also appear in the message history
+  - Structured data (Pydantic models, dataclasses, tuples, etc.) become `DataPart` artifacts with the data wrapped as `{"result": <your_data>}`
+  - Artifacts include metadata with type information and JSON schema when available

docs/agents.md

@@ -466,26 +466,43 @@ PydanticAI offers a [`settings.ModelSettings`][pydantic_ai.settings.ModelSetting
 This structure allows you to configure common parameters that influence the model's behavior, such as `temperature`, `max_tokens`,
 `timeout`, and more.
 
-There are two ways to apply these settings:
+There are three ways to apply these settings, with a clear precedence order:
 
-1. Passing to `run{_sync,_stream}` functions via the `model_settings` argument. This allows for fine-tuning on a per-request basis.
-2. Setting during [`Agent`][pydantic_ai.agent.Agent] initialization via the `model_settings` argument. These settings will be applied by default to all subsequent run calls using said agent. However, `model_settings` provided during a specific run call will override the agent's default settings.
+1. **Model-level defaults** - Set when creating a model instance via the `settings` parameter. These serve as the base defaults for that model.
+2. **Agent-level defaults** - Set during [`Agent`][pydantic_ai.agent.Agent] initialization via the `model_settings` argument. These are merged with model defaults, with agent settings taking precedence.
+3. **Run-time overrides** - Passed to `run{_sync,_stream}` functions via the `model_settings` argument. These have the highest priority and are merged with the combined agent and model defaults.
 
 For example, if you'd like to set the `temperature` setting to `0.0` to ensure less random behavior,
 you can do the following:
 
 ```py
 from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.settings import ModelSettings
 
-agent = Agent('openai:gpt-4o')
+# 1. Model-level defaults
+model = OpenAIModel(
+    'gpt-4o',
+    settings=ModelSettings(temperature=0.8, max_tokens=500)  # Base defaults
+)
+
+# 2. Agent-level defaults (overrides model defaults by merging)
+agent = Agent(model, model_settings=ModelSettings(temperature=0.5))
 
+# 3. Run-time overrides (highest priority)
 result_sync = agent.run_sync(
-    'What is the capital of Italy?', model_settings={'temperature': 0.0}
+    'What is the capital of Italy?',
+    model_settings=ModelSettings(temperature=0.0)  # Final temperature: 0.0
 )
 print(result_sync.output)
 #> Rome
 ```
 
+The final request uses `temperature=0.0` (run-time), `max_tokens=500` (from model), demonstrating how settings merge with run-time taking precedence.
+
+!!! note "Model Settings Support"
+    Model-level settings are supported by all concrete model implementations (OpenAI, Anthropic, Google, etc.). Wrapper models like `FallbackModel`, `WrapperModel`, and `InstrumentedModel` don't have their own settings - they use the settings of their underlying models.
+
 ### Model specific settings
 
 If you wish to further customize model behavior, you can use a subclass of [`ModelSettings`][pydantic_ai.settings.ModelSettings], like [`GeminiModelSettings`][pydantic_ai.models.gemini.GeminiModelSettings], associated with your model of choice.

docs/api/output.md

@@ -9,3 +9,4 @@
             - NativeOutput
             - PromptedOutput
             - TextOutput
+            - StructuredDict

docs/examples/chat-app.md

@@ -33,7 +33,7 @@ Python code that runs the chat app:
 
 Simple HTML page to render the app:
 
-```snippet {path="/examples/pydantic_ai_examples/chat_app.py"}```
+```snippet {path="/examples/pydantic_ai_examples/chat_app.html"}```
 
 TypeScript to handle rendering the messages, to keep this simple (and at the risk of offending frontend developers) the typescript code is passed to the browser as plain text and transpiled in the browser.
 

docs/graph.md

@@ -352,7 +352,7 @@ stateDiagram-v2
   Feedback --> [*]
 ```
 
-```python {title="genai_email_feedback.py" py="3.10"}
+```python {title="genai_email_feedback.py" py="3.10" test="ci_only"}
 from __future__ import annotations as _annotations
 
 from dataclasses import dataclass, field

docs/models/google.md

@@ -58,7 +58,7 @@ To use Vertex AI, you may need to set up [application default credentials](https
 
 If you have the [`gcloud` CLI](https://cloud.google.com/sdk/gcloud) installed and configured, you can use:
 
-```python
+```python {test="ci_only"}
 from pydantic_ai import Agent
 from pydantic_ai.models.google import GoogleModel
 from pydantic_ai.providers.google import GoogleProvider

docs/models/index.md

@@ -124,6 +124,39 @@ The `ModelResponse` message above indicates in the `model_name` field that the o
 !!! note
     Each model's options should be configured individually. For example, `base_url`, `api_key`, and custom clients should be set on each model itself, not on the `FallbackModel`.
 
+### Per-Model Settings
+
+You can configure different [`ModelSettings`][pydantic_ai.settings.ModelSettings] for each model in a fallback chain by passing the `settings` parameter when creating each model. This is particularly useful when different providers have different optimal configurations:
+
+```python {title="fallback_model_per_settings.py"}
+from pydantic_ai import Agent
+from pydantic_ai.models.anthropic import AnthropicModel
+from pydantic_ai.models.fallback import FallbackModel
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.settings import ModelSettings
+
+# Configure each model with provider-specific optimal settings
+openai_model = OpenAIModel(
+    'gpt-4o',
+    settings=ModelSettings(temperature=0.7, max_tokens=1000)  # Higher creativity for OpenAI
+)
+anthropic_model = AnthropicModel(
+    'claude-3-5-sonnet-latest',
+    settings=ModelSettings(temperature=0.2, max_tokens=1000)  # Lower temperature for consistency
+)
+
+fallback_model = FallbackModel(openai_model, anthropic_model)
+agent = Agent(fallback_model)
+
+result = agent.run_sync('Write a creative story about space exploration')
+print(result.output)
+"""
+In the year 2157, Captain Maya Chen piloted her spacecraft through the vast expanse of the Andromeda Galaxy. As she discovered a planet with crystalline mountains that sang in harmony with the cosmic winds, she realized that space exploration was not just about finding new worlds, but about finding new ways to understand the universe and our place within it.
+"""
+```
+
+In this example, if the OpenAI model fails, the agent will automatically fall back to the Anthropic model with its own configured settings. The `FallbackModel` itself doesn't have settings - it uses the individual settings of whichever model successfully handles the request.
+
 In this next example, we demonstrate the exception-handling capabilities of `FallbackModel`.
 If all models fail, a [`FallbackExceptionGroup`][pydantic_ai.exceptions.FallbackExceptionGroup] is raised, which
 contains all the exceptions encountered during the `run` execution.

docs/output.md

@@ -31,7 +31,7 @@ _(This example is complete, it can be run "as is")_
 
 ## Output data {#structured-output}
 
-The [`Agent`][pydantic_ai.Agent] class constructor takes an `output_type` argument that takes one or more types or [output functions](#output-functions). It supports simple scalar types, list and dict types, dataclasses and Pydantic models, as well as type unions -- generally everything supported as type hints in a Pydantic model. You can also pass a list of multiple choices.
+The [`Agent`][pydantic_ai.Agent] class constructor takes an `output_type` argument that takes one or more types or [output functions](#output-functions). It supports simple scalar types, list and dict types (including `TypedDict`s and [`StructuredDict`s](#structured-dict)), dataclasses and Pydantic models, as well as type unions -- generally everything supported as type hints in a Pydantic model. You can also pass a list of multiple choices.
 
 By default, Pydantic AI leverages the model's tool calling capability to make it return structured data. When multiple output types are specified (in a union or list), each member is registered with the model as a separate output tool in order to reduce the complexity of the schema and maximise the chances a model will respond correctly. This has been shown to work well across a wide range of models. If you'd like to change the names of the output tools, use a model's native structured output feature, or pass the output schema to the model in its [instructions](agents.md#instructions), you can use an [output mode](#output-modes) marker class.
 
@@ -117,7 +117,6 @@ print(result.output)
 
 _(This example is complete, it can be run "as is")_
 
-
 ### Output functions
 
 Instead of plain text or structured data, you may want the output of your agent run to be the result of a function called with arguments provided by the model, for example to further process or validate the data provided through the arguments (with the option to tell the model to try again), or to hand off to another agent.
@@ -387,6 +386,37 @@ print(repr(result.output))
 
 _(This example is complete, it can be run "as is")_
 
+### Custom JSON schema {#structured-dict}
+
+If it's not feasible to define your desired structured output object using a Pydantic `BaseModel`, dataclass, or `TypedDict`, for example when you get a JSON schema from an external source or generate it dynamically, you can use the [`StructuredDict()`][pydantic_ai.output.StructuredDict] helper function to generate a `dict[str, Any]` subclass with a JSON schema attached that Pydantic AI will pass to the model.
+
+Note that Pydantic AI will not perform any validation of the received JSON object and it's up to the model to correctly interpret the schema and any constraints expressed in it, like required fields or integer value ranges.
+
+The output type will be a `dict[str, Any]` and it's up to your code to defensively read from it in case the model made a mistake. You can use an [output validator](#output-validator-functions) to reflect validation errors back to the model and get it to try again.
+
+Along with the JSON schema, you can optionally pass `name` and `description` arguments to provide additional context to the model:
+
+```python
+from pydantic_ai import Agent, StructuredDict
+
+HumanDict = StructuredDict(
+    {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "age": {"type": "integer"}
+        },
+        "required": ["name", "age"]
+    },
+    name="Human",
+    description="A human with a name and age",
+)
+
+agent = Agent('openai:gpt-4o', output_type=HumanDict)
+result = agent.run_sync("Create a person")
+#> {'name': 'John Doe', 'age': 30}
+```
+
 ### Output validators {#output-validator-functions}
 
 Some validation is inconvenient or impossible to do in Pydantic validators, in particular when the validation requires IO and is asynchronous. PydanticAI provides a way to add validation functions via the [`agent.output_validator`][pydantic_ai.Agent.output_validator] decorator.