The AI Toolchain — issue 020, September 8, 2026

Adds instant rollback capability enabling rapid reversion of deployments to a previous snapshot, introduces snapshot-serving in live mode so deployments can be served directly from snapshots, and adds a custom prefix capability for deployment or routing configuration.

Adds import/dependency edges (parser version 81) for Bash (source FILE, . FILE), Lua (require), Ruby (require_relative, require, load), and Elixir (alias, import, require, use), enabling --deps, --arch, and --cochange on codebases using those languages. This changes the dep_files=, ccd, acd, nccd (--deps), propagation_cost (--arch), and pair filter (--cochange) denominators for any corpus containing these languages — numbers recorded against an older build are not directly comparable.

Adds --rank-by=churn-decay flag that emits a file-level <recent> block ordered by newest commit first, so queries about what changed recently are answered correctly rather than by churn frequency.

$ ripwire . --rank-by=churn-decay

Adds <health dep_langs=> attribute to --deps output, publishing the exact set of dependency-capable languages behind the dep_files=, ccd, acd, nccd denominators so numbers are comparable across builds.

Changes --cochange's surprising= predicate to a per-pair question requiring a shared dependency dialect, preventing cross-dialect pairs (.sh↔.h, .js↔.h, .py↔.cpp) from being reported as hidden architectural debt. Pairs previously flagged as surprising across dialects (e.g. .js↔.h) will no longer appear.

Rewrites all eighteen MCP skill descriptions to fit the ~350-character client budget and folds ripwire-efficient into ripwire-orient, enforced by test/skilldescbudgetcheck.sh against the binary's own skill discovery.

Adds tests-to-run output in evidence order: a changed test file appears first, then its stem partner, then graph hops, with each row stating why it is included and an explicit message when the result is empty.

Adds herdr machine add <target> --label <name> (optionally with --remote-session <name> to target a named remote session), plus herdr machine list (with --json for scripting), herdr machine rename <profile-id> --label <name>, herdr machine disable <profile-id>, herdr machine enable <profile-id>, and herdr machine remove <profile-id> to manage saved profiles. Supports multi-machine connections from Linux/macOS clients to Linux/macOS servers on x86_64 and aarch64, with a combined agent list, machine-scoped navigation, notifications, and automatic reconnects; machine add checks remote installation capabilities and installs or updates with approval only when needed, avoiding pre-matched release versions. A machine token appears in sidebar rows and status-bar layouts (with conditional color support) when multiple machines are present, and an experimental --handoff flag on herdr --remote supports live server handoff during standalone setup.

$ herdr machine add workbox --label "Build machine" --remote-session agents

$ herdr machine list --json

$ herdr machine disable <profile-id>

$ herdr machine add "Build machine" --remote-session build-session

theme.custom.light.* and theme.custom.dark.* config keys (accent, panel_bg, sidebar_bg, active_row_bg, selection_bg, surface0, surface1, surface_dim, overlay0, overlay1, text, subtext0, mauve, green, yellow, red, blue, teal, peach) override individual color tokens depending on whether auto_switch selects a light or dark appearance, applied after theme.custom; values accept hex, named colors, rgb(r,g,b), or reset aliases. Exposed as [theme.custom.light] and [theme.custom.dark] TOML subtables layering overrides on shared custom colors.

theme:
  custom:
    light:
      accent: "#005f87"
      panel_bg: "#f0f4f8"
      sidebar_bg: "#e2eaf2"
    dark:
      accent: "#61afef"
      panel_bg: "#1e2228"
      sidebar_bg: "#16191e"

rules arrays on text-valued status-bar tokens support equals, contains, starts_with, gt, and lt conditions with per-rule style overrides, and ignore_case = true enables ASCII case-insensitive matching on string rules. Sidebar text and metadata tokens can likewise change color, boldness, and dimming based on their values using ordered text or numeric rules.

[$load]
style = { fg = '#fff' }
rules = [
  { gt = 90, style = { fg = '#f55' } },
  { gt = 60, style = { fg = '#fc0' } }
]

The --group flag on workspace close (or close_group: true on workspace.close) closes a primary workspace together with its linked-worktree workspaces; omitting it returns workspace_group_close_required. As of v0.9.0 this flag is mandatory in that scenario — previously the whole group closed automatically when the primary workspace was closed.

$ herdr workspace close --group

ui.pane_borders accepts "auto" (borders only for split panes), "always" (frame even a single pane), or "off" (no borders), with existing boolean values still accepted; ui.pane_outer_borders = true is required to frame a single pane when ui.pane_borders = "always" is set.

[ui]
pane_borders = 'always'
pane_outer_borders = true

ui.pane_borders = "always"

Adds --session <name> flag to herdr and herdr --remote to target a named session instead of the default, and --remote-keybindings server flag to remote attach so the server's keybindings are used instead of local ones.

$ herdr --remote workbox --session build-session

Adds Windows integration support for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, Devin CLI, OpenCode, Kilo Code CLI, Droid, Kimi Code CLI, Qoder CLI, and Antigravity CLI, with unsupported install formats automatically hidden or rejected.

The terminal UI now runs in each client, keeping themes, menus, copy mode, and other presentation settings local to the viewing machine. Client updates can leave compatible servers and their running agents untouched, with missing server features disabling only the affected action instead of preventing connection.

New lifecycle event subscriptions now start with live events rather than replaying retained history; API clients should subscribe before taking their initial snapshot to avoid missing changes.

Exposes vim_normal.enter_replace_mode in the configurable TUI keymap, enabling Vim Replace mode (entered with R) that overwrites graphemes, and supports Backspace recovery, dot-repeat, and undo.

Extends macOS MCP launcher to use native spawning for bare command names and relative executable paths, resolving against the child's configured PATH.

Switches app-server to jemalloc (tikv_jemallocator::Jemalloc) on Linux musl x86_64/aarch64 targets for improved memory performance.

Per-launch agent models are now exposed via the CLI, SDK, and MCP; the desktop app adds a reasoning effort picker for the cursor-agent; mobile sessions let users pick the agent's model and effort when starting a session; and pinned model releases are now placed behind a submenu.

Ships Catppuccin Latte, Solarized Light, and Vellum as built-in themes, selectable via Settings > Themes without installing a marketplace package.

Enables replying to PR review threads directly from the Changes pane: open the Changes pane, locate a PR review thread, and click 'Reply' to respond inline.

The CLI gains a --upsert flag and the ability to list, edit, and delete terminal scripts via superset cli.

Caps page uploads at 16 MB and uploads page documents straight to storage via tRPC, CLI, and MCP.

Adds a Claude Status widget showing live severity along with a cached 48-hour incident-history strip. It falls back to stale data when live status can't be fetched and shows a graceful ? when no status data is available at all.

Widget hiding is unified across numeric, Git, JJ, usage, cache, and other widgets into a shared h checklist of supported hide conditions, with existing settings automatically migrated to the new system.

The Git Conflicts widget gains a hide-on-zero option, plus the ability to display either ⚠0 or a customizable clean glyph when the tree has no conflicts.

Adds graft init --no-statusline (and GRAFT_NO_STATUSLINE=1 env var) to skip writing Claude Code's statusLine / subagentStatusLine, preserving user-defined status bars in .claude/settings.json or ~/.claude/settings.json; the choice is recorded in the wiring stamp so a later session refresh cannot restore Graft's bar.

$ graft init --no-statusline

Adds orcarouter as a first-class GRAFT_PROVIDER value, with ORCAROUTER_API_KEY, ORCAROUTER_BASE_URL, and ORCAROUTER_MODEL env-var fallbacks and /v1/models auto-discovery, mirroring existing litellm wiring; also adds a LiteLLM provider with /v1/models discovery as an LLM backend option.

Adds graft init --agents grok to configure Grok (xAI) as a host, writing .grok/skills/graft/SKILL.md and a [mcp_servers.graft] block in .grok/config.toml; adds Hermes Agent host support; adds first-class Google Antigravity host support; and brings the full Claude Code hook set to Codex (hook parity).

$ graft init --agents grok

Adds graft telemetry disable and the DO_NOT_TRACK environment variable to opt out of anonymous usage telemetry; graft telemetry debug prints the exact batch that would be sent without transmitting anything.

$ graft telemetry disable

$ graft telemetry debug

Adds a graft blast command that seeds impact traversal from changed symbols in a diff and posts the result on every PR; the --export-viz flag publishes the impact graph as the viewer's Context tab.

$ graft blast --export-viz

Adds graft uninstall to fully retract every file and config block graft has ever written to a repo; updates graft init to retract every agent it is not about to write so re-running init with different --agents converges the repo instead of accumulating stale files; and adds auto-update for graft and the wiring it writes.

$ graft uninstall

$ graft init --agents claude-code,cursor

Adds --only-dir to graft build to restrict indexing to a specific directory subtree, opt-in indexing of nested git clones (previously subdirectories that were separate git repositories were skipped), and an opt-out of .gitignore and .ignore writes during graft build.

$ graft build --only-dir src/auth

graft init now wires every workspace child repo in addition to the parent, and --dry-run lists each child's writes with node/edge totals summed across children; adds nearestGraftRoot resolution so a session started from a subdirectory (e.g. <repo>/src/foo/) finds the repo's graph rather than reporting none.

Blast-radius PR reports gained reviewer suggestions derived from git log over each affected area and scored by recency; App comments now name blast-radius areas and tag reviewers via nameReport then attachOwners in review.ts, closing a gap where App comments showed raw hub symbols and no Tag: line while CI comments on the same repo showed concept names and a reviewer; and PR comments, CLI output, and a shared helper now quote the source line where a call edge occurs.

Adds full-fidelity (depth-tier) Swift extraction via tree-sitter-swift ^0.7.1, parsing .swift files with complete symbol and call-edge wiring — classes, structs, enums, actors, extensions, protocols, typealiases, and top-level variables.

Adds R language support, parsing .R/.r files via tree-sitter-r (npm:@davisvaughan/tree-sitter-r), with support for R6, S4, S3 class systems and plain functions.

The breadth tier now resolves C/C++ #include → file-to-file import edges, Rust use crate::… → file-to-module import edges, and PHP use App\… → file-to-class-file import edges, plus resolved reference edges (extends, implements, new); Java annotation usage is also wired as reference edges in the code graph.

Mid-turn messages are now delivered to the agent at the next possible opportunity, allowing real-time steering instead of waiting for the current turn to complete. Built-in actions such as Ship and Review still queue until the agent finishes, preserving end-of-turn semantics, and manual queueing remains available via Amp or the Amp CLI when immediate steering isn't wanted.

Adds pydantic-monty (Python, uv add pydantic-monty), @pydantic/monty (npm), and the monty-pool Rust crate (cargo add monty-pool) providing a Monty worker pool and session.feed_run()/feedRun() to execute LLM-generated Python with no filesystem, environment, or network access. Supports inputs and external_lookup/externalLookup to pass host-side values and callable tools into the sandbox, and feed_start + dump() + load_snapshot to suspend, serialize (including the call stack), and resume a paused interpreter on another machine. Enforces VM-level resource limits via max_memory, max_duration_secs, max_recursion_depth, and pool-level max_suspensions. A commercial 'Full Monty' option exposes the same workers behind a WebSocket as a container image for OS-level isolation and horizontal scaling.

from pydantic_monty import Monty

code = """
kcal = nutrition('chocolate bar')['kcal']
hours = kcal * 4184 / (bulb_watts * 3600)
print(f'a chocolate bar could power a {bulb_watts}W bulb for {hours:.1f} hours')
"""

with Monty() as pool:
    with pool.checkout() as session:
        session.feed_run(
            code,
            inputs={'bulb_watts': 10},
            external_lookup={'nutrition': lambda food: {'kcal': 230}},
        )

from pydantic_monty import Monty

with Monty() as pool:
    with pool.checkout() as session:
        suspension = session.feed_start(code, inputs={'x': 42})
        snapshot_bytes = suspension.dump()

# Later, on any machine:
    with pool.checkout() as session2:
        session2.load_snapshot(snapshot_bytes)

Adds Agent.from_file('agent.yaml') and Agent.from_spec(dict_or_AgentSpec, **kwargs) to build agents from YAML/JSON without Python construction code, with kwargs overriding spec fields (model, instructions, capabilities, model_settings, output_type, deps_type, retries). Adds AgentSpec.from_file for finer-grained loading and AgentSpec.to_file('agent.yaml') to serialize a spec plus an optional companion JSON Schema (schema_path=None to skip). Adds TemplateStr, a Handlebars-style ({{variable}}) template type for instructions/description rendered against deps at runtime — any {{-containing string in a spec file is auto-promoted. The AgentSpec model carries model, name, description, instructions, model_settings, capabilities, deps_schema, output_schema, retries (int or AgentRetries), end_strategy ('early'/'graceful'/'exhaustive'), tool_timeout, instrument, and metadata; output_schema yields a StructuredDict returning dict[str, Any] when no output_type is passed, and deps_schema validates TemplateStr variable names without a Python deps_type. Declarative capability syntax supports Thinking, Instrumentation, WebSearch, WebFetch, ImageGeneration, XSearch, MCP, ToolSearch, PrefixTools, NativeTool, IncludeToolReturnSchemas, SetToolMetadata, RaiseContentFilterError, and ReinjectSystemPrompt.

model: anthropic:claude-opus-4-6
instructions: You are a helpful research assistant.
model_settings:
  max_tokens: 8192
capabilities:
  - WebSearch:
      local: duckduckgo
  - Thinking:
      effort: high

from pydantic_ai import Agent

agent = Agent.from_file('agent.yaml')
result = agent.run_sync('Summarize the latest news on LLM safety.')
print(result.output)

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class UserContext:
    user_name: str

agent = Agent.from_spec(
    {
        'model': 'anthropic:claude-opus-4-6',
        'instructions': 'You are helping {{user_name}}.',
        'capabilities': [{'WebSearch': {'local': 'duckduckgo'}}],
    },
    deps_type=UserContext,
)
result = agent.run_sync('Find recent papers on RAG.', deps=UserContext(user_name='Alice'))
print(result.output)

Adds Hooks (pydantic_ai.capabilities) with @hooks.on.* decorator registration (or constructor kwargs, e.g. Hooks(before_model_request=log_request)) — no subclassing required. Provides hook families for model requests (before_model_request, after_model_request, model_request, model_request_error, with ModelRequestContext bundling model, messages, model_settings, model_request_parameters), tool validation (before_tool_validate, after_tool_validate, tool_validate, tool_validate_error), tool execution (before_tool_execute, after_tool_execute, tool_execute, tool_execute_error), run-level (before_run, after_run, run, run_error), node-level (before_node_run, after_node_run, node_run, node_run_error for UserPromptNode/ModelRequestNode/CallToolsNode), output validation (before_output_validate, after_output_validate, output_validate, output_validate_error), and output processing (before_output_process, after_output_process, output_process, output_process_error). Also adds prepare_tools/prepare_output_tools to filter tool definitions per step, deferred_tool_calls to resolve approval-required tools inline via DeferredToolRequests/DeferredToolResults, and run_event_stream/event to wrap or observe the event stream (ToolCallPart, EnqueuedMessagesEvent, CustomEvent, RealtimeEvent). Supports defer_loading=True for on-demand hooks, and raising SkipModelRequest, SkipToolValidation, or SkipToolExecution to bypass the corresponding step; hooks may be sync (run in a thread pool) or async.

from pydantic_ai import Agent, ModelRequestContext, RunContext
from pydantic_ai.capabilities import Hooks

hooks = Hooks()

@hooks.on.before_model_request
async def log_request(ctx: RunContext, request_context: ModelRequestContext) -> ModelRequestContext:
    print(f'Sending {len(request_context.messages)} messages to the model')
    return request_context

agent = Agent('openai:gpt-4o', capabilities=[hooks])
result = agent.run_sync('Summarize this report.')
print(result.output)

from pydantic_ai import Agent, DeferredToolRequests, DeferredToolResults, RunContext
from pydantic_ai.capabilities import Hooks

hooks = Hooks()

@hooks.on.deferred_tool_calls
async def auto_approve(ctx: RunContext, *, requests: DeferredToolRequests) -> DeferredToolResults:
    return requests.build_results(approve_all=True)

agent = Agent('openai:gpt-4o', capabilities=[hooks])

@agent.tool_plain(requires_approval=True)
def delete_file(path: str) -> str:
    return f'File {path!r} deleted'

result = agent.run_sync('Delete tmp/cache.log')
print(result.output)

from pydantic_ai import Agent, PartStartEvent, RunContext
from pydantic_ai.capabilities import Hooks

hooks = Hooks()
event_count = 0

@hooks.on.event(PartStartEvent)
async def count_events(ctx: RunContext, event: PartStartEvent) -> None:
    global event_count
    event_count += 1

agent = Agent('openai:gpt-4o', capabilities=[hooks])
agent.run_sync('Tell me three facts about the ocean.')
print(f'PartStartEvent count: {event_count}')

Adds AbstractCapability base class with override points get_toolset, get_native_tools, get_wrapper_toolset, get_instructions, and get_model_settings for building custom agent capabilities — get_wrapper_toolset wraps the whole assembled toolset via WrapperToolset for cross-cutting behaviors like logging, get_toolset accepts a prebuilt AbstractToolset or a RunContext callable, and get_instructions/get_model_settings support static values, TemplateStr, or per-run callables. Supports defer_loading=True (requiring a stable id); capability id drives merge semantics — same-id instances merge field-by-field, and a run-level capability overrides an agent-level one outright unless a custom combine override point is defined. Instruction parts are keyed 'capability:<id>' or 'capability:<id>:<name>' via @capability.instructions(name=...). Supports AbstractCapability[MyDeps] generic typing for typed RunContext[MyDeps], and plain class, @dataclass, or custom __init__ construction patterns.

from dataclasses import dataclass
from typing import Any
from pydantic_ai import Agent
from pydantic_ai.capabilities import AbstractCapability
from pydantic_ai.toolsets import AbstractToolset
from pydantic_ai.toolsets.wrapper import WrapperToolset

@dataclass
class LoggingToolset(WrapperToolset[Any]):
    async def call_tool(self, tool_name: str, tool_args: dict[str, Any], *args: Any, **kwargs: Any) -> Any:
        print(f'[AUDIT] Calling tool: {tool_name} args={tool_args}')
        return await super().call_tool(tool_name, tool_args, *args, **kwargs)

@dataclass
class AuditLogCalls(AbstractCapability[Any]):
    def get_wrapper_toolset(self, toolset: AbstractToolset[Any]) -> AbstractToolset[Any]:
        return LoggingToolset(wrapped=toolset)

agent = Agent('openai:gpt-5.2', capabilities=[AuditLogCalls()])

from dataclasses import dataclass
from datetime import datetime
from typing import Any
from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import AbstractCapability

@dataclass
class CurrentTimeContext(AbstractCapability[Any]):
    def get_instructions(self):
        def _instructions(ctx: RunContext[Any]) -> str:
            return f'The current UTC time is {datetime.utcnow().isoformat()}. Use it when answering time-sensitive questions.'
        return _instructions

agent = Agent('openai:gpt-5.2', capabilities=[CurrentTimeContext()])
result = agent.run_sync('Is the market open right now?')

from dataclasses import dataclass
from typing import Any
from pydantic_ai import Agent
from pydantic_ai.capabilities import AbstractCapability
from pydantic_ai.toolsets import FunctionToolset, AgentToolset

math_toolset = FunctionToolset()

@math_toolset.tool_plain
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b

@math_toolset.tool_plain
def multiply(a: float, b: float) -> float:
    """Multiply two numbers."""
    return a * b

@dataclass
class MathTools(AbstractCapability[Any]):
    id: str | None = 'math_tools'
    def get_toolset(self) -> AgentToolset[Any] | None:
        return math_toolset

agent = Agent('openai:gpt-5.2', capabilities=[MathTools()])
result = agent.run_sync('What is 7 multiplied by 6?')

Adds XaiModel/XaiProvider (pydantic_ai.models.xai / pydantic_ai.providers.xai) for 'xai:<model-name>' agents authenticated via XAI_API_KEY, with provider options api_host, timeout, and metadata (e.g. x-grok-conv-id for prompt-cache sticky routing) and a custom xai_sdk.AsyncClient via xai_client. Adds the XSearch capability (allowed_x_handles, excluded_x_handles, from_date, to_date, enable_image_understanding, enable_video_understanding, include_output) for real-time X search, plus XaiModelSettings fields xai_include_x_search_output, xai_reasoning_effort ('none'|'low'|'medium'|'high', for Grok 4.3), xai_max_turns (caps server-side tool-loop turns), xai_agent_count (parallel agents for grok-4.20-multi-agent), and xai_include_attachment_search_output (default False, surfaces the attachment_search/pdf_browse tool output). Adds ImageGenerator support for xAI image models via XaiImageGenerationSettings (aspect_ratio, xai_resolution) with moderation-aware batching that reports flagged images in provider_details['moderated_image_indices'] and only raises ContentFilterError when every image is flagged. Installs via pydantic-ai-slim[xai].

from datetime import datetime
from pydantic_ai import Agent
from pydantic_ai.capabilities import XSearch

agent = Agent(
    'xai:grok-4.3',
    capabilities=[
        XSearch(
            allowed_x_handles=['OpenAI', 'AnthropicAI'],
            from_date=datetime(2025, 1, 1),
            enable_image_understanding=True,
            include_output=True,
        )
    ],
)
result = agent.run_sync('Summarize recent AI announcements.')
print(result.output)

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.3',
    model_settings=XaiModelSettings(
        xai_reasoning_effort='low',
        xai_max_turns=3,
    ),
)
result = agent.run_sync('What are the top cybersecurity threats this week?')
print(result.output)

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

provider = XaiProvider(
    api_key='your-api-key',
    metadata=(('x-grok-conv-id', 'session-abc123'),),
)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
result = agent.run_sync('Continue our analysis of the incident report.')
print(result.output)

Adds AsyncHTTPX2TenacityTransport and HTTPX2TenacityTransport (pydantic_ai.retries) to attach tenacity-powered retries directly to httpx2 clients used by any provider, configured via a unified RetryConfig object wrapping tenacity's retry, wait, stop, and reraise parameters. Adds wait_retry_after, a wait strategy parsing provider Retry-After headers (seconds or HTTP-date format) from 429s with a configurable max_wait ceiling and fallback to any tenacity wait strategy, plus ModelHTTPError.retry_after for custom backoff outside a transport. Installs via pydantic-ai-slim[retries] (pulls in tenacity). Documentation now enumerates seven retry layers — transport, provider SDK, durable execution (retry_policy in Temporal's ActivityConfig, max_attempts in DBOS's StepConfig, retries in Prefect's TaskConfig), model fallback (FallbackModel), tool retries (retries={'tools': N}), output retries (retries={'output': N}/ToolOutput(max_retries=N)), and ModelRetry-raising hooks — clarifying only the last three consume model round trips and that UsageLimits.request_limit counts only model requests.

from httpx2 import AsyncClient, HTTPStatusError
from tenacity import retry_if_exception_type, stop_after_attempt, wait_exponential
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
from pydantic_ai.retries import AsyncHTTPX2TenacityTransport, RetryConfig, wait_retry_after

transport = AsyncHTTPX2TenacityTransport(
    config=RetryConfig(
        retry=retry_if_exception_type(HTTPStatusError),
        wait=wait_retry_after(
            fallback_strategy=wait_exponential(multiplier=1, max=60),
            max_wait=300,
        ),
        stop=stop_after_attempt(5),
        reraise=True,
    ),
    validate_response=lambda r: r.raise_for_status(),
)
client = AsyncClient(transport=transport)
model = OpenAIChatModel('gpt-4o', provider=OpenAIProvider(http_client=client))
agent = Agent(model)

import httpx2
from tenacity import retry_if_exception_type, stop_after_attempt, wait_exponential
from pydantic_ai.retries import AsyncHTTPX2TenacityTransport, RetryConfig

transport = AsyncHTTPX2TenacityTransport(
    config=RetryConfig(
        retry=retry_if_exception_type((
            httpx2.TimeoutException,
            httpx2.ConnectError,
            httpx2.ReadError,
        )),
        wait=wait_exponential(multiplier=1, max=10),
        stop=stop_after_attempt(3),
        reraise=True,
    )
)
client = httpx2.AsyncClient(transport=transport)

Adds model_request_sync, model_request, model_request_stream, and model_request_stream_sync in pydantic_ai.direct for making sync/async, streamed/non-streamed LLM requests without constructing an Agent, supporting ModelRequestParameters (function_tools, allow_text_output). Supports per-call OpenTelemetry/Logfire instrumentation via instrument=True.

from pydantic_ai import ModelRequest
from pydantic_ai.direct import model_request_sync

model_response = model_request_sync(
    'anthropic:claude-haiku-4-5',
    [ModelRequest.user_text_prompt('What is the capital of France?')]
)
print(model_response.parts[0].content)
print(model_response.usage)

from typing import Literal
from pydantic import BaseModel
from pydantic_ai import ModelRequest, ToolDefinition
from pydantic_ai.direct import model_request
from pydantic_ai.models import ModelRequestParameters

class Divide(BaseModel):
    """Divide two numbers."""
    numerator: float
    denominator: float
    on_inf: Literal['error', 'infinity'] = 'infinity'

model_response = await model_request(
    'openai:gpt-5-nano',
    [ModelRequest.user_text_prompt('What is 123 / 456?')],
    model_request_parameters=ModelRequestParameters(
        function_tools=[
            ToolDefinition(
                name=Divide.__name__.lower(),
                description=Divide.__doc__,
                parameters_json_schema=Divide.model_json_schema(),
            )
        ],
        allow_text_output=True,
    ),
)

import logfire
from pydantic_ai import ModelRequest
from pydantic_ai.direct import model_request_sync

logfire.configure()

model_response = model_request_sync(
    'anthropic:claude-haiku-4-5',
    [ModelRequest.user_text_prompt('What is the capital of France?')],
    instrument=True
)
print(model_response.parts[0].content)

Adds HuggingFaceModel (pydantic_ai.models.huggingface) and HuggingFaceProvider (pydantic_ai.providers.huggingface) to run open-source models such as Qwen/Qwen3-235B-A22B and DeepSeek R1 through Hugging Face Inference Providers, selecting a backend (Cerebras, Together AI, Cohere, Nebius, Fireworks AI, etc.) via provider_name or a custom AsyncInferenceClient passed as hf_client (exposing headers, bill_to, base_url). Reads HF_TOKEN for auth and installs via the pydantic-ai-slim[huggingface] extras group.

from pydantic_ai import Agent
from pydantic_ai.models.huggingface import HuggingFaceModel
from pydantic_ai.providers.huggingface import HuggingFaceProvider

model = HuggingFaceModel(
    'Qwen/Qwen3-235B-A22B',
    provider=HuggingFaceProvider(api_key='hf_token', provider_name='nebius'),
)
agent = Agent(model)

from huggingface_hub import AsyncInferenceClient
from pydantic_ai import Agent
from pydantic_ai.models.huggingface import HuggingFaceModel
from pydantic_ai.providers.huggingface import HuggingFaceProvider

client = AsyncInferenceClient(
    bill_to='openai',
    api_key='hf_token',
    provider='fireworks-ai',
)
model = HuggingFaceModel(
    'Qwen/Qwen3-235B-A22B',
    provider=HuggingFaceProvider(hf_client=client),
)
agent = Agent(model)

Adds MistralModel (pydantic_ai.models.mistral) and MistralProvider (pydantic_ai.providers.mistral) to run agents against Mistral-hosted models like mistral-large-latest and mistral-small-latest, authenticated via MISTRAL_API_KEY or explicit api_key/base_url/http_client arguments. Installable via the mistral extras group (pip install 'pydantic-ai-slim[mistral]'), exposes LatestMistralModelNames for reference, and accepts an httpx2.AsyncClient as http_client (legacy httpx.AsyncClient still works but is deprecated for removal in v3).

from pydantic_ai import Agent
agent = Agent('mistral:mistral-large-latest')

from httpx2 import AsyncClient
from pydantic_ai import Agent
from pydantic_ai.models.mistral import MistralModel
from pydantic_ai.providers.mistral import MistralProvider

custom_http_client = AsyncClient(timeout=30)
model = MistralModel(
    'mistral-large-latest',
    provider=MistralProvider(
        api_key='your-api-key',
        base_url='https://<mistral-provider-endpoint>',
        http_client=custom_http_client,
    ),
)
agent = Agent(model)

Adds GroqModel and GroqProvider (pydantic_ai.models.groq / pydantic_ai.providers.groq) for Groq-hosted LLMs, configured via GROQ_API_KEY or an api_key argument, with 'groq:<model-name>' shorthand. Supports a custom httpx.AsyncClient via http_client for timeouts/transport, and exposes the Groq SDK's retry count through groq_client=AsyncGroq(max_retries=...) (default max_retries=2). Installs via pydantic-ai-slim[groq].

from httpx import AsyncClient
from pydantic_ai import Agent
from pydantic_ai.models.groq import GroqModel
from pydantic_ai.providers.groq import GroqProvider

custom_http_client = AsyncClient(timeout=30)
model = GroqModel(
    'llama-3.3-70b-versatile',
    provider=GroqProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)

from groq import AsyncGroq
from pydantic_ai import Agent
from pydantic_ai.models.groq import GroqModel
from pydantic_ai.providers.groq import GroqProvider

model = GroqModel(
    'llama-3.3-70b-versatile',
    provider=GroqProvider(groq_client=AsyncGroq(max_retries=0)),
)
agent = Agent(model)

Adds CohereModel (pydantic_ai.models.cohere), CohereProvider (api_key, http_client), and CohereModelSettings (temperature, top_k) for running agents against Cohere endpoints via CO_API_KEY or the cohere: shorthand prefix. Installs via pydantic-ai-slim[cohere]; Cohere's built-in client retries server errors and rate limits twice regardless of transport, and max_retries cannot be configured.

from httpx import AsyncClient
from pydantic_ai import Agent
from pydantic_ai.models.cohere import CohereModel
from pydantic_ai.providers.cohere import CohereProvider

custom_http_client = AsyncClient(timeout=30)
model = CohereModel(
    'command-r7b-12-2024',
    provider=CohereProvider(api_key='your-api-key', http_client=custom_http_client),
)
agent = Agent(model)

from pydantic_ai import Agent
from pydantic_ai.models.cohere import CohereModel, CohereModelSettings

model = CohereModel('command-r7b-12-2024')
settings = CohereModelSettings(temperature=0.2, top_k=40)
agent = Agent(model, model_settings=settings)

Ships an installable skill giving coding agents up-to-date PydanticAI knowledge, covering tools, capabilities, structured output, streaming, testing, multi-agent delegation, hooks, and agent specs. Installable via claude plugin install pydantic-ai@claude-plugins-official, or claude plugin marketplace add pydantic/skills + claude plugin install ai@pydantic-skills, via the agentskills.io standard with npx skills add pydantic/skills (30+ agents including Claude Code, Codex, Cursor, Gemini CLI), or from a project's transitive dependency via uvx library-skills --all (add --claude to also write into .claude/skills/).

$ uvx library-skills --all --claude

$ claude plugin install pydantic-ai@claude-plugins-official

$ npx skills add pydantic/skills

Adds an ImageGenerator class with a generate_sync() method to generate images directly without an agent run, using providers such as openai:gpt-image-2 and returning a result with .image.data bytes.

from pydantic_ai import ImageGenerator
from pathlib import Path

generator = ImageGenerator('openai:gpt-image-2')
result = generator.generate_sync('A minimalist logo for a coffee shop called Extract.')
Path('logo.png').write_bytes(result.image.data)

from pydantic_ai import ImageGenerator
from pathlib import Path

generator = ImageGenerator('openai:gpt-image-2')
result = generator.generate_sync('A minimalist logo for a coffee shop called Extract.')
Path('logo.png').write_bytes(result.image.data)

Retains exit status and captured output of completed background commands, accessible via process(action="log") for output and process(action="poll") for exit status from the conversation that launched it; process(action="list") now includes retained results, not just live processes. Keeps the newest 64 completed results for up to 7 days under logs/process-results/ in the profile's Hermes home, with each receipt capped at a 200,000-character output tail and terminal secret-redaction always applied.

$ process(action="log")

Adds hermes peer run <peer>[/<agent>] [message] to start a long Bot Chat turn asynchronously and return its run_id, session ID, and idempotency key; hermes peer status <peer>[/<agent>] <run_id> polls a run and prints its final output when complete; hermes peer stop <peer>[/<agent>] <run_id> stops an exact run without targeting another turn.

$ run_id=$(hermes peer run myagent/researcher 'Summarize recent CVEs in openssl' | jq -r .run_id)
hermes peer status myagent/researcher "$run_id"

Adds skills.create_dir config key to redirect new agent-created skills to a custom directory — such as a shared 'brain' directory, a git-tracked repo, or a fleet-wide skills volume — instead of the default profile-local skills directory. Agent-facing tool descriptions and prompt text dynamically render the configured create_dir path so the agent is automatically told to write skills there, and skills under create_dir are fully integrated into the skill index, slash commands, and support patch and delete operations alongside local skills.

create_dir: /opt/brain/skills

Adds defer config option (auto or never) for auxiliary.background_review so reviews on the managed local llama-server queue at turn end and run once the machine is idle, preventing GPU contention with the next prompt; defer_max_age_s forces a queued review to run after a maximum wait even if the machine never goes idle.

defer: auto
defer_max_age_s: 600

defer: never

Makes platforms.<name>.enabled: false in config.yaml authoritative over credentials present in .env for twelve platforms (Weixin, WhatsApp Cloud, Home Assistant, Email, SMS, DingTalk, Feishu, WeCom, WeCom callback, BlueBubbles, QQ Bot, Yuanbao); previously credentials alone re-enabled the adapter regardless of this key. Startup now logs a WARNING per affected platform instead of silently re-enabling it.

platforms:
  weixin:
    enabled: false

platforms:
  weixin:
    enabled: false

Adds privacy.redact_pii: true config key to hash platform, chat, thread, sender, message, profile, and scope identifiers in the model-visible per-message JSON context on supported platforms, while preserving original identifiers internally for routing.

privacy:
  redact_pii: true

privacy:
  redact_pii: true

Adds gateway.trust_env config key to disable inherited HTTP_PROXY/HTTPS_PROXY/NO_PROXY/SSL_CERT_FILE and macOS system proxy auto-detection for all platform adapters at once, while explicit per-platform proxy variables (DISCORD_PROXY, TELEGRAM_PROXY, MATRIX_PROXY, …) remain honored.

gateway:
  trust_env: false

gateway:
  trust_env: false

Adds Fast Mode support for OpenAI Priority Processing (service_tier: priority), xAI Priority Processing on Grok 4.6, and Anthropic Fast Mode (speed: fast, Opus 4.8 / Opus 5 only), configurable with normal, fast, auto, cold modes and a fast_auto_seconds window. The /fast normal|fast|auto|cold slash command switches Fast Mode for the current session, with an optional flag to persist the setting; /fast alone shows the current mode.

Adds hermes runs incidents command as a read-only fleet health check for failed runs, failed deliveries, overdue/missing next_run_at, and missing scripts or workdirs — it exits non-zero when issues are found.

$ hermes runs incidents

Adds context_file_read_timeout config key (default 5 seconds) to skip context files that take too long to read — such as those on iCloud Drive, OneDrive, or NFS — with a warning instead of blocking, bounding per-file reads on network-backed filesystems before the system prompt is built.

context_file_read_timeout: 15

Adds docker_snap_compat config key (also exposed as TERMINAL_DOCKER_SNAP_COMPAT env var) to drop --init and --no-new-privileges sandbox flags on hosts where Docker is installed as a snap (e.g. Ubuntu Azure VMs), preventing container startup failures.

docker_snap_compat: true

Adds non_interactive_hard_stop_enabled config key to control loop-detection hard stops, enabling them by default for unattended gateway and cron sessions while leaving interactive CLI, TUI, Desktop, and ACP sessions in warning-only mode.

non_interactive_hard_stop_enabled: false

Adds port-conflict detection to the backend: prints a machine-readable BACKEND_PORT_IN_USE port=<port> sentinel and exits with EX_TEMPFAIL when the requested port is occupied; supports --port 0 to bind a free ephemeral port, announced via HERMES_BACKEND_READY port=<port>.

Adds F6 to open a full-screen live subagent monitor without losing the composer draft, with arrow-key worker selection, a log view, s to steer a worker, and x to stop one with confirmation; F7 toggles the live subagent dock between a multi-row preview and a single summary line without moving composer focus.

Sending a message while a turn is in progress redirects it: model generation restarts with reasoning and completed work preserved, and any running foreground terminal command is moved to the background instead of being killed, with a completion notification when it finishes.

Adds model.streaming: false config key to force non-streaming requests for the whole session (parent and subagents), as an escape hatch for self-hosted OpenAI-compatible servers with broken tool-call paths such as vLLM with --tool-call-parser qwen3_xml.

Adds agent.budget_warning_ratio config key (strictly between 0 and 1, off by default) to append a one-time model-visible checkpoint notice after a configurable fraction of the turn budget is consumed, with Dispatcher-owned Kanban workers defaulting to a 90% threshold.

Supports forwarding skill-declared environment variables over SSH via OpenSSH SendEnv, with variable names listed under terminal.env_passthrough; requires AcceptEnv in /etc/ssh/sshd_config on the server.

Adds keepalive_interval_seconds config key to cap the background token-refresh tick interval for long-running gateway and dashboard processes; set to 0 to disable the keepalive entirely.

keepalive_interval_seconds: 0  # disables the keepalive

Adds hermes skills uninstall <name> shell command to remove missing-directory ('orphaned') skill entries detected during install checks.

$ hermes skills uninstall <name>

Supports masked password prompts for interactive sudo commands in parent sessions, including literal absolute or quoted executable paths and env prefixes with ordinary options and assignments (e.g. env -u UNUSED /usr/bin/sudo id); passwordless sudo requires no prompt.

Adds new provider/model targets including alibaba-cn, alibaba-coding-plan-cn, alibaba-token-plan, nebius, nebius-token-factory, nebius-tf, tokenfactory, tencent-tokenplan, tokenplan, tencent-lkeap, router, ramp-router, and ramp.

Adds PageFileSystem(knowledge=...) toolkit exposing files.tools() for bounded, read-only, sync/async page access — lazy reads against pinned revisions, scoped metadata listing, and literal grep — without shell execution or write access.

from agno.knowledge.page import PageFileSystem, Knowledge
from agno.agent import Agent

fs = PageFileSystem(knowledge=Knowledge(name="docs"))

agent = Agent(
    tools=fs.tools(),
    description="Reads documentation pages on demand.",
)
agent.print_response("Summarise the getting-started page.", stream=True)

Adds AIMLAPI model integration with a fixed analytics-only attribution header set inspectable as agno.models.aimlapi.AIMLAPI_HEADERS and overridable per model via default_headers; defaults to model gpt-5.6-terra.

from agno.models.aimlapi import AIMLAPI
from agno.agent import Agent

agent = Agent(
    model=AIMLAPI(
        default_headers={"X-Custom-Key": "my-value"},
    ),
    description="Agent backed by AIMLAPI (defaults to gpt-5.6-terra).",
)
agent.print_response("Hello!", stream=True)

Knowledge constructor arguments are now keyword-only, so positional calls such as Knowledge('docs') must become Knowledge(name='docs'). content_db is now the preferred spelling of the former contents_db field on Knowledge; contents_db remains a read/write alias but passing both keywords requires the same object. Page search no longer silently forces ef_search=200, instead honouring the configured PgVector HNSW ef_search — deployments relying on the implicit 200 must set it explicitly, and page indexes built with the implicit ef_construction=64 from interim main builds require an operator-managed rebuild.

Adds PublicSurface for publicly serving selected Agents, stateless MCP, and authenticated durable-sync Workflows, with shared quotas, CORS, request/output bounds, and internal-service authentication. Extended in the same release to serve explicitly selected Teams with REST and gzip support, sharing the same Agent admission, execution, and output limits.

Adds agno.knowledge.page with Knowledge(page_search=PageSearchConfig(...)) for typed, transaction-local planner controls, installable via the new agno[pages] extra.

Agent dependency callables can now receive run_input and session alongside the existing agent and run_context arguments; resolution runs before pre-hooks and reuses successful values on model retries.

Adds inherit_host_environment=False on agents.sandbox.sandboxes.unix_local to pass only a conservative allowlist of host variables (instead of the full host environment) to sandbox commands, with host_environment_allowlist accepting a custom collection to replace the default set (PATH, LANG, LC_ALL, TZ, SSL_CERT_FILE, CI, and others). Adds labels support for Docker sandbox sessions, passing key-value pairs to Docker at container creation, storing them in DockerSandboxSessionState, and verifying label consistency on resume(...) — raising ValueError if any persisted label no longer matches.

session = await agents.sandbox.sandboxes.unix_local.create(
    inherit_host_environment=False,
    host_environment_allowlist={"PATH", "LANG", "SSL_CERT_FILE"},
)

session = await client.create(
    labels={
        "com.example.owner": "agents-sdk",
        "com.example.environment": "development",
    },
)

Adds tool_input_guardrails and tool_output_guardrails parameters to local MCP server classes, letting you attach server-wide guardrails that apply to every MCP tool after filtering — input guardrails can block the call and supply replacement content, output guardrails inspect the converted result before it is returned to the model. Guardrails attached directly to local MCP servers apply to every tool exposed by that server, and input guardrails run before and output guardrails after every guarded function-tool invocation, including local MCP tools. Adds RunConfig.output_guardrail_blocked_message to set a custom placeholder string or synchronous formatter, receiving OutputGuardrailBlockedMessageArgs (SDK default, guardrail name, agent, and active run context), when an output guardrail blocks a tool response.

from agents.decorators import tool_input_guardrail
import json
from agents import ToolGuardrailFunctionOutput

@tool_input_guardrail
async def block_secret_arguments(arguments):
    tool_arguments = json.loads(arguments)
    if "secret" in tool_arguments:
        return ToolGuardrailFunctionOutput(
            reject_content="Remove secrets before calling this MCP tool."
        )
    return ToolGuardrailFunctionOutput(allow=".")

# Pass to your local MCP server
server = MCPServerStdio(
    ...,
    tool_input_guardrails=[block_secret_arguments]
)

from openai_agents import RunConfig, OutputGuardrailBlockedMessageArgs

def my_blocked_formatter(args: OutputGuardrailBlockedMessageArgs) -> str:
    return f"Output blocked by policy: {args.guardrail_name}."

run_config = RunConfig(
    output_guardrail_blocked_message=my_blocked_formatter
)

Adds search_content_types parameter supporting "image" and "text" values to control whether web search returns images, text results, or both, plus image_settings.max_results to request a specific number of image results and image_settings.caption to request short descriptions when available. When "image" is included, the SDK automatically requests web_search_call.results, stored on the web_search_call item in RunResult.raw_responses, with fields image_url, source_website_url, thumbnail_url, and caption.