Improve deferred tools metadata documentation example

- Replace contrived task_id parameter with realistic tool signatures
- Add ComputeDeps class demonstrating dependency injection pattern
- Show using ctx.deps to compute metadata from tool arguments
- Remove incorrect statement about backwards compatibility
- Update test_examples.py to match new realistic example

Author: cjohnhanson

docs/deferred-tools.md

@@ -326,16 +326,20 @@ _(This example is complete, it can be run "as is" — you'll need to add `asynci
 
 Both [`CallDeferred`][pydantic_ai.exceptions.CallDeferred] and [`ApprovalRequired`][pydantic_ai.exceptions.ApprovalRequired] exceptions accept an optional `metadata` parameter that allows you to attach arbitrary context information to deferred tool calls. This metadata is then available in the [`DeferredToolRequests.metadata`][pydantic_ai.tools.DeferredToolRequests.metadata] dictionary, keyed by the tool call ID.
 
+A common pattern is to use [`RunContext`][pydantic_ai.tools.RunContext] to access application dependencies (databases, APIs, calculators) and compute metadata based on the tool arguments and current context. This allows you to provide rich information for approval decisions or external task tracking.
+
 Common use cases for metadata include:
 
-- Providing cost estimates or time estimates for approval decisions
-- Including task IDs or tracking information for external execution
-- Storing context about why approval is required
-- Attaching priority or urgency information
+- Computing cost estimates based on tool arguments and dependency services
+- Including job IDs or tracking information for external execution systems
+- Storing approval context like user permissions or resource availability
+- Attaching priority levels computed from current system state
 
-Here's an example showing how to use metadata with both approval-required and external tools:
+Here's an example showing how to use metadata with deps to make informed approval decisions:
 
 ```python {title="deferred_tools_with_metadata.py"}
+from dataclasses import dataclass
+
 from pydantic_ai import (
     Agent,
     ApprovalRequired,
@@ -347,91 +351,113 @@ from pydantic_ai import (
     ToolDenied,
 )
 
-agent = Agent('openai:gpt-5', output_type=[str, DeferredToolRequests])
+
+@dataclass
+class ComputeDeps:
+    """Dependencies providing cost estimation and job scheduling."""
+
+    def estimate_cost(self, dataset: str, model_type: str) -> float:
+        # In real code, query pricing API or database
+        costs = {'gpt-4': 50.0, 'gpt-3.5': 10.0}
+        return costs.get(model_type, 25.0)
+
+    def estimate_duration(self, dataset: str) -> int:
+        # In real code, estimate based on dataset size
+        return 30 if dataset == 'large_dataset' else 5
+
+    def submit_job(self, dataset: str, model_type: str) -> str:
+        # In real code, submit to batch processing system
+        return f'job_{dataset}_{model_type}'
+
+
+agent = Agent(
+    'openai:gpt-5',
+    deps_type=ComputeDeps,
+    output_type=[str, DeferredToolRequests],
+)
 
 
 @agent.tool
-def expensive_compute(ctx: RunContext, task_id: str) -> str:
+def train_model(ctx: RunContext[ComputeDeps], dataset: str, model_type: str) -> str:
+    """Train ML model - requires approval for expensive models."""
     if not ctx.tool_call_approved:
+        # Use deps to compute actual estimates based on args
+        cost = ctx.deps.estimate_cost(dataset, model_type)
+        duration = ctx.deps.estimate_duration(dataset)
+
         raise ApprovalRequired(
             metadata={
-                'task_id': task_id,
-                'estimated_cost_usd': 25.50,
-                'estimated_time_minutes': 15,
-                'reason': 'High compute cost',
+                'dataset': dataset,
+                'model_type': model_type,
+                'estimated_cost_usd': cost,
+                'estimated_duration_minutes': duration,
             }
         )
-    return f'Task {task_id} completed'
+
+    return f'Model {model_type} trained on {dataset}'
 
 
 @agent.tool
-async def external_api_call(ctx: RunContext, endpoint: str) -> str:
-    # Schedule the external API call and defer execution
-    task_id = f'api_call_{ctx.tool_call_id}'
+def process_dataset(ctx: RunContext[ComputeDeps], dataset: str, operation: str) -> str:
+    """Process dataset in external batch system."""
+    # Submit job and defer execution
+    job_id = ctx.deps.submit_job(dataset, operation)
 
     raise CallDeferred(
         metadata={
-            'task_id': task_id,
-            'endpoint': endpoint,
-            'priority': 'high',
+            'job_id': job_id,
+            'dataset': dataset,
+            'operation': operation,
         }
     )
 
 
-result = agent.run_sync('Run expensive task-123 and call the /data endpoint')
+deps = ComputeDeps()
+result = agent.run_sync(
+    'Train gpt-4 on large_dataset and process large_dataset with transform',
+    deps=deps,
+)
 messages = result.all_messages()
 
 assert isinstance(result.output, DeferredToolRequests)
 requests = result.output
 
-# Handle approvals with metadata
-for call in requests.approvals:
-    metadata = requests.metadata.get(call.tool_call_id, {})
-    print(f'Approval needed for {call.tool_name}')
-    #> Approval needed for expensive_compute
-    print(f'  Cost: ${metadata.get("estimated_cost_usd")}')
-    #>   Cost: $25.5
-    print(f'  Time: {metadata.get("estimated_time_minutes")} minutes')
-    #>   Time: 15 minutes
-    print(f'  Reason: {metadata.get("reason")}')
-    #>   Reason: High compute cost
-
-# Handle external calls with metadata
-for call in requests.calls:
-    metadata = requests.metadata.get(call.tool_call_id, {})
-    print(f'External call to {call.tool_name}')
-    #> External call to external_api_call
-    print(f'  Task ID: {metadata.get("task_id")}')
-    #>   Task ID: api_call_external_api_call
-    print(f'  Priority: {metadata.get("priority")}')
-    #>   Priority: high
-
-# Build results with approvals and external results
+# Make approval decisions based on metadata
 results = DeferredToolResults()
 for call in requests.approvals:
     metadata = requests.metadata.get(call.tool_call_id, {})
     cost = metadata.get('estimated_cost_usd', 0)
 
-    if cost < 50:  # Approve if cost is under $50
+    print(f'Approval needed: {call.tool_name}')
+    #> Approval needed: train_model
+    print(f'  Model: {metadata.get("model_type")}, Cost: ${cost}')
+    #>   Model: gpt-4, Cost: $50.0
+
+    if cost < 100:
         results.approvals[call.tool_call_id] = ToolApproved()
     else:
-        results.approvals[call.tool_call_id] = ToolDenied('Cost too high')
+        results.approvals[call.tool_call_id] = ToolDenied('Cost exceeds limit')
 
+# Process external jobs using metadata
 for call in requests.calls:
     metadata = requests.metadata.get(call.tool_call_id, {})
-    # Simulate getting result from external task
-    task_id = metadata.get('task_id')
-    results.calls[call.tool_call_id] = f'Result from {task_id}: success'
+    job_id = metadata.get('job_id')
 
-result = agent.run_sync(message_history=messages, deferred_tool_results=results)
+    print(f'External job: {job_id}')
+    #> External job: job_large_dataset_transform
+
+    # In real code, poll job status and get result
+    results.calls[call.tool_call_id] = f'Completed {job_id}'
+
+result = agent.run_sync(message_history=messages, deferred_tool_results=results, deps=deps)
 print(result.output)
-#> I completed task-123 and retrieved data from the /data endpoint.
+"""
+Model gpt-4 trained on large_dataset and dataset processing job job_large_dataset_transform completed
+"""
 ```
 
 _(This example is complete, it can be run "as is")_
 
-The metadata dictionary can contain any JSON-serializable values and is entirely application-defined. If no metadata is provided when raising the exception, the tool call ID will still be present in the `metadata` dictionary with an empty dict as the value for backward compatibility.
-
 ## See Also
 
 - [Function Tools](tools.md) - Basic tool concepts and registration

tests/test_examples.py

@@ -523,9 +523,17 @@ async def call_tool(
     'Tell me about the pydantic/pydantic-ai repo.': 'The pydantic/pydantic-ai repo is a Python agent framework for building Generative AI applications.',
     'What do I have on my calendar today?': "You're going to spend all day playing with Pydantic AI.",
     'Write a long story about a cat': 'Once upon a time, there was a curious cat named Whiskers who loved to explore the world around him...',
-    'Run expensive task-123 and call the /data endpoint': [
-        ToolCallPart(tool_name='expensive_compute', args={'task_id': 'task-123'}, tool_call_id='expensive_compute'),
-        ToolCallPart(tool_name='external_api_call', args={'endpoint': '/data'}, tool_call_id='external_api_call'),
+    'Train gpt-4 on large_dataset and process large_dataset with transform': [
+        ToolCallPart(
+            tool_name='train_model',
+            args={'dataset': 'large_dataset', 'model_type': 'gpt-4'},
+            tool_call_id='train_model',
+        ),
+        ToolCallPart(
+            tool_name='process_dataset',
+            args={'dataset': 'large_dataset', 'operation': 'transform'},
+            tool_call_id='process_dataset',
+        ),
     ],
 }
 
@@ -875,11 +883,17 @@ async def model_logic(  # noqa: C901
         return ModelResponse(
             parts=[TextPart('The answer to the ultimate question of life, the universe, and everything is 42.')]
         )
-    elif isinstance(m, ToolReturnPart) and m.tool_name in ('expensive_compute', 'external_api_call'):
+    elif isinstance(m, ToolReturnPart) and m.tool_name in ('train_model', 'process_dataset'):
         # After deferred tools complete, check if we have all results to provide final response
         tool_names = {part.tool_name for msg in messages for part in msg.parts if isinstance(part, ToolReturnPart)}
-        if 'expensive_compute' in tool_names and 'external_api_call' in tool_names:
-            return ModelResponse(parts=[TextPart('I completed task-123 and retrieved data from the /data endpoint.')])
+        if 'train_model' in tool_names and 'process_dataset' in tool_names:
+            return ModelResponse(
+                parts=[
+                    TextPart(
+                        'Model gpt-4 trained on large_dataset and dataset processing job job_large_dataset_transform completed'
+                    )
+                ]
+            )
         # If we don't have both results yet, just acknowledge the tool result
         return ModelResponse(parts=[TextPart(f'Received result from {m.tool_name}')])