Capabilities

Capabilities are PydanticAI's composable extension point for cross-cutting agent behavior. A capability bundles tools, lifecycle hooks, instructions, and model settings into a single unit that attaches to an agent. InitRunner exposes PydanticAI's built-in capabilities via spec.capabilities in role YAML.

For InitRunner-managed integrations (filesystem, shell, SQL, etc.), use Tools instead. Both can coexist in the same role.

YAML Syntax

Capabilities use PydanticAI's native spec format with three forms:

spec:
  capabilities:
    # Bare string (no arguments)
    - WebSearch

    # Single positional argument
    - Thinking: high

    # Keyword arguments
    - MCP:
        url: https://mcp.example.com
    - WebSearch:
        allowed_domains: [docs.python.org, pydantic.dev]
        search_context_size: high

Names are CamelCase class names matching PydanticAI's capability registry.

Supported Capabilities

Capability	Arguments	Purpose
`Thinking`	`effort`: `minimal`, `low`, `medium`, `high`, `xhigh`	Enable model-level extended thinking
`WebSearch`	`allowed_domains`, `blocked_domains`, `search_context_size`, `max_uses`	Native provider web search; raises on a model without native web search (no local fallback)
`WebFetch`	`allowed_domains`, `blocked_domains`, `max_uses`	URL fetching with InitRunner's injected SSRF-protected local fallback
`ImageGeneration`	(none)	Image generation with fallback
`MCP`	`url` (required), `id`, `authorization_token`, `headers`, `allowed_tools`	PydanticAI-native MCP server connection
`NativeTool`	`tool` (native tool spec)	Register an individual provider-native tool
`PrefixTools`	`prefix`, `capability` (nested spec)	Namespace tool names to avoid conflicts

Since v2026.6.7 (PydanticAI v2), the BuiltinTool capability is named NativeTool. A role still using - BuiltinTool under spec.capabilities must switch to - NativeTool. In the same release, WebSearch became native-only: it uses the provider's own web search and raises on a model that has none, rather than adapting to a local fallback. WebFetch is unaffected and still uses InitRunner's injected SSRF-protected local fallback.

Examples

Extended thinking

spec:
  capabilities:
    - Thinking: high

Web search with domain filtering

spec:
  capabilities:
    - WebSearch:
        allowed_domains: [docs.python.org, github.com]
        search_context_size: medium

Remote MCP server

spec:
  capabilities:
    - MCP:
        url: https://mcp.example.com/api
        authorization_token: ${MCP_TOKEN}

Prefixed capabilities (namespace tools)

spec:
  capabilities:
    - PrefixTools:
        prefix: search
        capability:
          WebSearch:
            allowed_domains: [example.com]

Combined

spec:
  capabilities:
    - Thinking: high
    - WebSearch:
        allowed_domains: [docs.python.org]
    - MCP:
        url: https://tools.example.com/mcp

Guardrail Capabilities

InitRunner auto-constructs an InputGuardCapability from spec.security.content when any input validation is configured (blocked patterns, profanity filter, LLM classifier, or non-default max prompt length). This capability fires before the agent starts and raises ContentBlockedError to abort the run when the user prompt violates the content policy.

No capabilities: entry is needed — the guard is auto-constructed from the security config:

spec:
  security:
    content:
      blocked_input_patterns:
        - "ignore.*instructions"
        - "reveal.*system.*prompt"
      profanity_filter: true
      max_prompt_length: 10000

See Security for the full content policy reference.

Capabilities vs Tools

	Capabilities (`spec.capabilities`)	Tools (`spec.tools`)
Source	PydanticAI built-ins	InitRunner tool registry
Scope	Cross-cutting (hooks + tools + instructions)	Single tool function
Use for	Thinking, web search, MCP servers	Filesystem, shell, SQL, HTTP, custom code

Both can coexist in the same role. InitRunner logs a warning when both an MCP capability and an MCP tool target the same server.

Thinking vs Reasoning

The Thinking capability controls model-level extended thinking — how much the LLM reasons internally before responding. InitRunner's spec.reasoning controls orchestration patterns (react, reflexion, todo_driven, plan_execute) that structure multi-step agent runs. See Reasoning.

These are orthogonal and can be combined, though InitRunner logs a warning since the interaction may be confusing.

Dashboard

Agents with capabilities show:

A capabilities dot in the capability glyph (2x4 grid)
An Enhanced filter in the capability filter bar
A Capabilities section in the agent detail config panel listing each capability's type and configuration

On this page