Add new capabilities abstraction + make agents serializable

clai/README.md

@@ -72,7 +72,7 @@ options:
   -m MODEL, --model MODEL
                         Model to use, in format "<provider>:<model>" e.g. "openai:gpt-5" or "anthropic:claude-sonnet-4-6". Defaults to "openai:gpt-5".
   -a AGENT, --agent AGENT
-                        Custom Agent to use, in format "module:variable", e.g. "mymodule.submodule:my_agent"
+                        Custom Agent to use: a module path like "module:variable" or a YAML/JSON spec file like "agent.yml"
   -t CODE_THEME, --code-theme CODE_THEME
                         Which colors to use for code, can be "dark", "light" or any theme from pygments.org/styles/. Defaults to "dark" which works well on dark terminals.
   --no-stream           Disable streaming from the model

docs/agent.md

@@ -309,13 +309,6 @@ async def main():
     print(nodes)
     """
     [
-        UserPromptNode(
-            user_prompt='What is the capital of France?',
-            instructions_functions=[],
-            system_prompts=(),
-            system_prompt_functions=[],
-            system_prompt_dynamic_functions={},
-        ),
         ModelRequestNode(
             request=ModelRequest(
                 parts=[
@@ -545,7 +538,6 @@ if __name__ == '__main__':
     print(output_messages)
     """
     [
-        '=== UserPromptNode: What will the weather be like in Paris on Tuesday? ===',
         '=== ModelRequestNode: streaming partial request tokens ===',
         "[Request] Starting part 0: ToolCallPart(tool_name='weather_forecast', tool_call_id='0001')",
         '[Request] Part 0 args delta: {"location":"Pa',
@@ -712,6 +704,33 @@ print(result_sync.output)
 
 The final request uses `temperature=0.0` (run-time), `max_tokens=500` (from model), demonstrating how settings merge with run-time taking precedence.
 
+##### Dynamic model settings
+
+Both agent-level and run-level `model_settings` accept a callable that receives a
+[`RunContext`][pydantic_ai.tools.RunContext] and returns [`ModelSettings`][pydantic_ai.settings.ModelSettings].
+The callable is invoked before each model request, so settings can vary per step.
+The current resolved settings so far are available via `ctx.model_settings` inside the callable.
+
+Settings are resolved in layers, each merged on top of the previous:
+
+1. **Model defaults** (`model.settings`)
+2. **Agent-level** (`Agent(model_settings=...)`)
+3. **Capability-level** (e.g. from `Thinking()`, `ModelSettings(...)` capabilities)
+4. **Run-level** (`agent.run(model_settings=...)`)
+
+Inside a callable, `ctx.model_settings` contains the merged result of all *previous* layers (position-dependent). For example, an agent-level callable sees only model defaults, while a run-level callable sees model defaults + agent-level + capability-level settings. To reset a field set by a previous layer, set it explicitly (e.g. `{'temperature': None}`).
+
+```python
+from pydantic_ai import Agent, ModelSettings
+
+agent = Agent(
+    'test',
+    model_settings=lambda ctx: ModelSettings(
+        temperature=0.0 if ctx.run_step <= 1 else 0.7,
+    ),
+)
+```
+
 !!! note "Model Settings Support"
     Model-level settings are supported by all concrete model implementations (OpenAI, Anthropic, Google, etc.). Wrapper models like [`FallbackModel`](models/overview.md#fallback-model), [`WrapperModel`][pydantic_ai.models.wrapper.WrapperModel], and [`InstrumentedModel`][pydantic_ai.models.instrumented.InstrumentedModel] don't have their own settings - they use the settings of their underlying models.
 

mkdocs.yml

@@ -23,6 +23,7 @@ nav:
           - tools.md
           - output.md
           - message-history.md
+          - capabilities.md
           - direct.md
       - Models & Providers:
           - Overview: models/overview.md

pydantic_ai_slim/pydantic_ai/__init__.py

@@ -1,5 +1,6 @@
 from importlib.metadata import version as _metadata_version
 
+from ._template import TemplateStr
 from .agent import (
     Agent,
     CallToolsNode,
@@ -42,6 +43,9 @@
     ModelAPIError,
     ModelHTTPError,
     ModelRetry,
+    SkipModelRequest,
+    SkipToolExecution,
+    SkipToolValidation,
     UnexpectedModelBehavior,
     UsageLimitExceeded,
     UserError,
@@ -115,6 +119,7 @@
 from .tools import DeferredToolRequests, DeferredToolResults, RunContext, Tool, ToolApproved, ToolDefinition, ToolDenied
 from .toolsets import (
     AbstractToolset,
+    AgentToolset,
     ApprovalRequiredToolset,
     CombinedToolset,
     ExternalToolset,
@@ -161,6 +166,9 @@
     'ModelHTTPError',
     'FallbackExceptionGroup',
     'IncompleteToolCall',
+    'SkipModelRequest',
+    'SkipToolExecution',
+    'SkipToolValidation',
     'UnexpectedModelBehavior',
     'UsageLimitExceeded',
     'UserError',
@@ -233,6 +241,7 @@
     'ToolDenied',
     # toolsets
     'AbstractToolset',
+    'AgentToolset',
     'ApprovalRequiredToolset',
     'CombinedToolset',
     'ExternalToolset',
@@ -260,6 +269,8 @@
     'PromptedOutput',
     'TextOutput',
     'StructuredDict',
+    # template
+    'TemplateStr',
     # format_prompt
     'format_as_xml',
     # settings