Add new capabilities abstraction + make agents serializable

[DouweM]

• Closes New "capabilities" abstraction + out of the box capabilities to let a general knowledge work agents be defined in <10 lines #4303
• Closes Agent Definition from JSON/YAML (like Pydantic models) #4251

[github-actions]

Thinking extends ModelSettings (a @dataclass) but bypasses the dataclass-generated __init__ with a custom __init__ that calls super().__init__(cast(..., {...})). This is fragile: if ModelSettings gains additional fields in the future, this __init__ won't set them.

A cleaner approach would be to just call the dataclass __init__ directly: super().__init__(settings=cast(_ModelSettings, {...})). That way the dataclass machinery handles field initialization properly.

[DouweM]

Fixed: now uses super().__init__(settings=cast(...)) with the keyword arg.

[github-actions]

The from_spec error message references a GitHub issue number (#3894) which is opaque to users who encounter this error. Consider replacing it with a user-friendly message that just says configurable thinking parameters aren't supported yet, and suggests using ModelSettings as a workaround, without the issue reference.

[DouweM]

Fixed: removed issue reference from user-facing error message.

[github-actions]

The asyncio.create_task + asyncio.Event cooperative hand-off pattern here (and in the streaming wrap_model_request path in _agent_graph.py) is quite subtle. A comment block explaining the protocol would help future readers:

# wrap_run cooperative hand-off:
# 1. _do_run runs before_run, signals readiness, waits for completion
# 2. wrap_run wraps _do_run via capability middleware chain
# 3. Caller waits for readiness, yields agent_run, then signals completion
# 4. On error: cancels the wrap task; on success: awaits wrap result + after_run

[DouweM]

Comments already added in a previous round.

[github-actions]

The per_run_state.py example uses test="skip" but there's nothing here that requires skipping — it's a pure in-memory example with no external dependencies. Per docs guidelines, test="skip" should be avoided unless unavoidable.

[DouweM]

Fixed in 0881700.

[github-actions]

This has been discussed before and the short name is kept intentionally, but I want to note one concrete risk: from pydantic_ai.capabilities import ModelSettings and from pydantic_ai import ModelSettings resolve to different types (a @dataclass capability class vs a TypedDict). A user who does from pydantic_ai.capabilities import * alongside from pydantic_ai import ModelSettings (or vice versa) will silently get the wrong one. At minimum, consider adding a # noqa comment that explains the shadowing is intentional, and ensure the capabilities docs page explicitly warns about this when showing the import.

[DouweM]

Intentional — discussed with maintainer. The short name is kept for ergonomics.

[adtyavrdhn]

What do we expect to happen if someone sends in two Instructions capabilities contradicting each other? This example is a little non-deterministic but the point is, for capabilities that interact more with the internals of the code instead of a prompt but enforce different constraints?

[DouweM]

We just concatenate all instructions with \n\n, so I guess it's up to the user not to be contradictory, and up to capabilities to only add instructions that relate to them and are unlikely to affect other capabilities' instructions and user instructions. Of course the user could add 2 capabilities that are fundamentally incompatible -- is that what you're thinking of?

[adtyavrdhn]

Of course the user could add 2 capabilities that are fundamentally incompatible -- is that what you're thinking of?

Yes we should at from_spec() time detect incompatible capabilities. I think capabilities can have a field where they can mark which ones they are incompatible with although I am not sure how that would scale but I would rather the agent crash before rather than do weird stuff on prod. Throwing it out there.

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 10 additional findings in Devin Review.

[devin-ai-integration]

🚩 CombinedCapability dynamic model settings don't update ctx.model_settings between capability callables

In CombinedCapability.get_model_settings() (combined.py:56-60), when multiple capabilities provide dynamic (callable) settings, the resolve() closure calls each function sequentially but does NOT update ctx.model_settings between calls. Compare with the agent-level resolver (agent/__init__.py:990-1013) which explicitly sets run_context.model_settings = merged between each layer.

This means if capabilities A and B both provide dynamic settings within the same CombinedCapability, B's callable will see ctx.model_settings from the layer before the entire capability group — it won't see A's contribution. The docs at docs/capabilities.md:176 say the callable sees "the merged result of all layers resolved before this capability", which is ambiguous about whether "this capability" means the individual capability or the combined group. Current behavior treats all capabilities as a single layer, which is internally consistent but could surprise users.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🚩 wrap_run task coordination in iter() handles error propagation correctly but doesn't support wrap_run error recovery

The iter() method's _do_run / _wrap_task coordination (agent/__init__.py:1115-1166) correctly propagates user exceptions: when the user's code raises inside async with agent.iter(...) as agent_run:, _run_error is set and re-raised, then _wrap_task is cancelled in the finally block.

However, if a wrap_run implementation catches the error from handler() and returns a recovery result, that result is silently discarded — the user's original exception always propagates. This is because the finally block only awaits _wrap_task for its result when _run_error is None. Whether this is intentional depends on whether wrap_run error recovery is a supported use case. The docs don't mention it, and the test suite doesn't test for it. Worth documenting this limitation if wrap_run is intended to support try/catch patterns around handler().

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[github-actions]

_AgentSpecSchema manually duplicates every field from AgentSpec, and even drops TemplateStr from several fields (e.g. description is str | None here but TemplateStr | str | None in AgentSpec, and same for instructions). This has been flagged in multiple previous review rounds but remains unaddressed.

The schema divergence means the generated JSON schema doesn't reflect the actual validation behavior — users who rely on the schema for IDE autocompletion or validation will get incorrect type information, and any future field additions to AgentSpec that aren't mirrored here will silently produce an incomplete schema.

Consider deriving _AgentSpecSchema programmatically from AgentSpec (e.g. AgentSpec.model_fields), or at minimum add a test that asserts the field names match between the two classes to catch drift. @DouweM

[github-actions]

The abstract setter declares str | None but the concrete Agent.description.setter at agent/__init__.py:844 accepts TemplateStr[AgentDepsT] | str | None. This means a WrapperAgent or other AbstractAgent subclass that follows the abstract contract would reject TemplateStr values, and Pyright will flag the override as incompatible.

The abstract setter should be updated to match: TemplateStr[AgentDepsT] | str | None.

[github-actions]

merged if merged is not None else ModelSettings() — ModelSettings is a TypedDict, so ModelSettings() creates an empty dict which is falsy. This is fine for the is not None check, but the returned callable's return type annotation is ModelSettings while the overall get_model_settings return type includes | None. When there are no dynamic settings and static_settings is None, the method correctly returns None from line 54.

However, inside this closure, if every dynamic callable returns None-ish settings and static_settings is also None, merged will be None, and this produces an empty ModelSettings() dict. That empty dict is then merged at the agent level as a no-op, which is fine functionally, but it means the callable never returns None — it always returns a dict. This is subtly different from static_settings returning None on line 54. Consider using return merged or None to be consistent (a no-op merge target is indistinguishable from None).

[github-actions]

DEFAULT_CAPABILITY_TYPES (used for spec schema generation) includes only Instructions, ModelSettings, Thinking, and WebSearch, while CAPABILITY_TYPES (used for the registry) also includes HistoryProcessor and Toolset. Since DEFAULT_CAPABILITY_TYPES drives the JSON schema output in model_json_schema_with_capabilities, HistoryProcessor and Toolset won't appear in the generated schema unless passed as custom_capability_types.

If the intent is that these two are not useful in YAML/JSON specs (since they take non-serializable callables/objects), that's reasonable but should be documented. A comment explaining why DEFAULT_CAPABILITY_TYPES is a subset of CAPABILITY_TYPES would help future readers.

[github-actions]

Defining __init__ on a @dataclass subclass bypasses the dataclass-generated __init__, which means Thinking doesn't participate in the standard dataclass field protocol. This works because super().__init__(settings=cast(...)) calls ModelSettings.__init__ directly, but it's fragile — if ModelSettings gains additional fields, Thinking.__init__ won't pass them.

Since Thinking is essentially ModelSettings with hardcoded settings, consider making it a classmethod factory instead, or using field(default_factory=...) on the settings field to avoid the manual __init__ override entirely:

@dataclass
class Thinking(ModelSettings[AgentDepsT]):
    settings: _ModelSettings = field(default_factory=lambda: cast(_ModelSettings, {
        'openai_reasoning_effort': 'high',
        ...
    }))

[github-actions]

The asyncio.create_task + Event cooperative hand-off pattern for wrap_run is quite complex and has been flagged repeatedly. The pattern has at least one subtle edge case: if wrap_run raises before calling handler() (e.g. a precondition check), _run_ready is never set, and _wrap_task.done() becomes True with _run_ready.is_set() False, triggering the short-circuit path that calls _wrap_task.result() — which will re-raise the exception from wrap_run. That exception isn't caught here, so it'll propagate out of the iter() context manager.

This seems correct but is very hard to reason about. A thorough comment block explaining the state machine (which combinations of _run_ready, _run_done, _run_error, _short_circuited, and _wrap_task.done() are possible and what each means) would make this much more maintainable.

[github-actions]

The docstring example uses test="skip" which is understandable since pydantic-handlebars is an optional dependency. However, the entire TemplateStr class (including __init__, render, __call__, and the Pydantic schema hook) calls _import_pydantic_handlebars() or uses compiled templates that require it. This means these code paths have zero test coverage in CI unless pydantic-handlebars is installed in the test environment.

Looking at pyproject.toml, handlebars = ["pydantic-handlebars>=0.1.0"] is added as an optional dependency group but I don't see it included in the test dependencies. The test_template.py tests presumably need this. Can you confirm that pydantic-handlebars is installed in CI for the test runs that exercise TemplateStr?

[github-actions]

This example uses 'anthropic:claude-sonnet-4-20250514' which is not a frontier model. Per the docs guidelines, use the latest frontier model — e.g. 'anthropic:claude-opus-4-6' or 'openai:gpt-5.2'.