Registry

Server-side tools and their derived schemas. See Tools for the narrative.

ToolRegistry

ToolRegistry

An ordered, named collection of server-side tools.

State lives on the instance — a transport holds one, tests build a fresh one per scenario. Each tool's JSON Schema is derived once at registration, and either sync or async callables can be dispatched.

register

register(spec: ToolSpec) -> ToolBinding

Register spec and return its binding.

Raises:

Type	Description
ValueError	when spec.name is already registered.

get

get(name: str) -> ToolBinding

Return the binding for name or raise KeyError.

call

call(name: str, arguments: dict[str, Any], *, ctx: Any = None) -> Any

Dispatch a sync call to the registered tool.

arguments is the model's payload and nothing else. A tool declaring a leading ctx: RunContext[...] gets it from ctx here, the way pydantic-ai would supply it from the run; passing one to a tool that takes none is harmless.

Refuses coroutine functions to avoid silently returning an un-awaited coroutine. Use acall for async tools.

Raises:

Type	Description
TypeError	when the tool is async, or declares a RunContext parameter and no ctx was given.

acall async

acall(name: str, arguments: dict[str, Any], *, ctx: Any = None) -> Any

Dispatch an async call; transparently awaits sync callables.

ctx is bound exactly as in call.

tool

tool

tool(
    registry: ToolRegistry,
    *,
    name: str | None = None,
    description: str | None = None,
    destructive: bool = False,
    category: ToolCategory = ToolCategory.OTHER,
    confirm: str | None = None,
    summary: str | None = None,
) -> Callable[[F], F]

Register the decorated callable on registry as a tool.

name defaults to the function's name and description to the first paragraph of its docstring. confirm is the confirmation prompt for a destructive tool and summary a short display label; both reach the client as the matching x-* schema key.

ToolSpec

ToolSpec dataclass

Canonical declaration of a server-side tool.

Bundles the callable with the metadata the registry needs to expose it to a Pydantic-AI agent and to a frontend.

name instance-attribute

name: str

Stable identifier exposed to the agent, unique within a ToolRegistry.

fn instance-attribute

fn: Callable[..., Any]

The callable implementing the tool. Its parameters must be typed; the registry derives a JSON Schema from the signature.

description instance-attribute

description: str

Summary shown to the agent. Most clients display the first line.

destructive class-attribute instance-attribute

destructive: bool = False

Whether calling this tool may mutate state. Stamped as x-destructive so a frontend can gate it behind a confirmation step.

category class-attribute instance-attribute

category: ToolCategory = ToolCategory.OTHER

Coarse capability grouping, stamped as x-category.

confirm class-attribute instance-attribute

confirm: str | None = None

A confirmation prompt for a destructive tool, stamped as x-confirm, shown instead of a generic "Run ?".

summary class-attribute instance-attribute

summary: str | None = None

A short label, stamped as x-summary, shown on the tool-call card instead of the raw tool name.

ToolBinding

ToolBinding dataclass

A registered tool plus the JSON Schema derived from its signature.

The schema is computed once at registration and carried alongside the spec, so a tool listing does not re-introspect on every request.

build_input_schema

build_input_schema

build_input_schema(
    fn: Callable[..., Any],
    *,
    destructive: bool = False,
    category: ToolCategory = ToolCategory.OTHER,
    confirm: str | None = None,
    summary: str | None = None,
) -> dict[str, Any]

Derive a JSON Schema object from fn's parameters.

Covers str, int, float, bool, list[T], dict[str, Any] and X | None unions. Anything richer falls back to an empty fragment, imposing no type constraint but staying wire-valid.

destructive / category / confirm / summary are stamped at the schema root as the matching x-* extension keys, which AG-UI passes through verbatim to the client.

A leading ctx: RunContext[...] parameter is not an argument and is left out. Pydantic-AI fills it from the run — it is how a tool reaches the acting user — so advertising it would ask the model to invent a value for something it cannot supply.

ToolCategory

ToolCategory

Bases: str, Enum

Coarse grouping for a tool, surfaced to the agent and the UI.

Advisory metadata: it lets a frontend group tools, a system prompt reason about capability classes, and a project apply category-wide policy. It does not gate execution; that is the destructive flag's job.

Schema and metadata keys

The x-* keys are JSON-Schema extensions that reach the client on a tool's schema. DESTRUCTIVE_METADATA_KEY is different: it rides pydantic-ai's tool metadata and is read server-side by the tool guard, which needs destructiveness for tools whose flag doesn't come from the @tool registry.

constants

X_DESTRUCTIVE_KEY module-attribute

X_DESTRUCTIVE_KEY = 'x-destructive'

X_CATEGORY_KEY module-attribute

X_CATEGORY_KEY = 'x-category'

X_CONFIRM_KEY module-attribute

X_CONFIRM_KEY = 'x-confirm'

X_SUMMARY_KEY module-attribute

X_SUMMARY_KEY = 'x-summary'

DESTRUCTIVE_METADATA_KEY module-attribute

DESTRUCTIVE_METADATA_KEY = 'django_pydantic_agent.destructive'