Add documentation for the agent's validation context

Author: NicolasPllr1

docs/output.md

@@ -385,6 +385,62 @@ print(repr(result.output))
 
 _(This example is complete, it can be run "as is")_
 
+### Validation context {#validation-context}
+
+Some validation relies on an extra Pydantic [context](https://docs.pydantic.dev/latest/concepts/validators/#validation-context) object. You can pass such an object to an `Agent` at definition-time via its [`validation_context`][pydantic_ai.Agent.__init__] parameter.
+
+This validation context is used for the validation of _all_ structured outputs. It can be either:
+
+- the context object itself (`Any`), used as-is to validate outputs, or
+- a function that takes the [`RunContext`][pydantic_ai.tools.RunContext] and returns a context object (`Any`). This function will be called automatically before each validation, allowing you to build a dynamic validation context.
+
+!!! warning "Don't confuse this _validation_ context with the _LLM_ context"
+    This Pydantic [context](https://docs.pydantic.dev/latest/concepts/validators/#validation-data) object is only used internally by Pydantic AI for output validation. In particular, it is **not** included in the prompts or messages sent to the language model.
+
+```python {title="validation_context.py"}
+from dataclasses import dataclass
+
+from pydantic import BaseModel, ValidationInfo, field_validator
+
+from pydantic_ai import Agent
+
+
+class Value(BaseModel):
+    x: int
+
+    @field_validator('x')
+    def increment_value(cls, value: int, info: ValidationInfo):
+        return value + (info.context or 0)
+
+
+agent = Agent(
+    'google-gla:gemini-2.5-flash',
+    output_type=Value,
+    validation_context=10,
+)
+result = agent.run_sync('Give me a value of 5.')
+print(repr(result.output))  # 5 from the model + 10 from the validation context
+#> Value(x=15)
+
+
+@dataclass
+class Deps:
+    increment: int
+
+
+agent = Agent(
+    'google-gla:gemini-2.5-flash',
+    output_type=Value,
+    deps_type=Deps,
+    validation_context=lambda ctx: ctx.deps.increment,
+)
+result = agent.run_sync('Give me a value of 5.', deps=Deps(increment=10))
+print(repr(result.output))  # 5 from the model + 10 from the validation context
+#> Value(x=15)
+```
+
+_(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.
@@ -550,8 +606,8 @@ There two main challenges with streamed results:
 2. When receiving a response, we don't know if it's the final response without starting to stream it and peeking at the content. Pydantic AI streams just enough of the response to sniff out if it's a tool call or an output, then streams the whole thing and calls tools, or returns the stream as a [`StreamedRunResult`][pydantic_ai.result.StreamedRunResult].
 
 !!! note
-    As the `run_stream()` method will consider the first output matching the `output_type` to be the final output,
-    it will stop running the agent graph and will not execute any tool calls made by the model after this "final" output.
+As the `run_stream()` method will consider the first output matching the `output_type` to be the final output,
+it will stop running the agent graph and will not execute any tool calls made by the model after this "final" output.
 
     If you want to always run the agent graph to completion and stream all events from the model's streaming response and the agent's execution of tools,
     use [`agent.run_stream_events()`][pydantic_ai.agent.AbstractAgent.run_stream_events] ([docs](agents.md#streaming-all-events)) or [`agent.iter()`][pydantic_ai.agent.AbstractAgent.iter] ([docs](agents.md#streaming-all-events-and-output)) instead.
@@ -609,8 +665,8 @@ async def main():
 _(This example is complete, it can be run "as is" — you'll need to add `asyncio.run(main())` to run `main`)_
 
 !!! warning "Output message not included in `messages`"
-    The final output message will **NOT** be added to result messages if you use `.stream_text(delta=True)`,
-    see [Messages and chat history](message-history.md) for more information.
+The final output message will **NOT** be added to result messages if you use `.stream_text(delta=True)`,
+see [Messages and chat history](message-history.md) for more information.
 
 ### Streaming Structured Output