pydantic-ai's capability primitive is what makes it more than a model-switching wrapper

The capability abstraction is the real organizing idea here. A capability bundles tools, instructions, hooks, and model settings into a single composable unit that attaches to any agent with one list entry. The bank support example makes this concrete: customer_context is a capability that injects the customer's name as an instruction and exposes a balance-checking tool; refunds is a deferred capability that the model loads only when the conversation actually calls for it. Neither is a black box. Both decompose into the same primitives you'd write by hand.

That composability extends to the pre-built Coder capability in the separate Harness package. It bundles file access, an allowlisted shell, repo orientation, sub-agents, and context management — but the README is explicit that using Coder() and listing its constituent capabilities directly are equivalent. You can take it apart and reassemble only what you need.

The interface story is broader than most agent SDKs attempt. One agent definition runs as a CLI, a web chat, a realtime voice session (OpenAI Realtime, Gemini Live, Azure, xAI Grok Voice), or a durable background workflow. Durable execution spans seven engines — Temporal, DBOS, Prefect, Restate, AWS Lambda, Kitaru, and Airflow — with the first five described as co-maintained with the vendor teams. Attaching TemporalDurability() as a capability is all that changes in the agent definition; every model and tool call becomes a durable activity underneath.

The type system is load-bearing, not decorative. Tool argument schemas derive from function signatures and docstrings; arguments are validated before user code runs; the run is guaranteed to return the declared output type. Your IDE and type checker see the same contract the LLM does. Pydantic Evals tests agent behavior the way pytest tests code — a direct comparison the README makes without hedging.

Observability is OpenTelemetry-native throughout, so any OTel backend works. The Gateway provides a single key across all providers with failover and real-time cost monitoring, and it self-hosts. Pricing data comes from the separate genai-prices package, kept current independently.

The package is the Pydantic team's own SDK, and the README notes that Pydantic validation already underlies the OpenAI SDK, the Anthropic SDK, the Google ADK, and LangChain. That heritage shows in the design: the priority is making the type system do real work, not adding abstraction for its own sake.