Docs/SDK/Tool Registry

Tool Registry

Expose typed, auditable tools to your agent (structured inputs/outputs + traceable execution), so tool calls are deterministic and debuggable.

This guide covers:

Tool calls should be validated and replayable.

The Tool Registry gives tools the same failure semantics as the rest of the runtime: strict schemas, explicit capability checks, and trace events for post-mortems.

Table of Contents

  1. Why Tool Registry
  2. Default tools
  3. Register a typed tool
  4. Execute tools (with tracing)
  5. Capability checks

Why Tool Registry

Without typed tools, agents “call tools” with ambiguous payloads:

Tool Registry addresses this by:

Default tools

You can register a ready-made tool pack for common browser operations.

ToolPurpose
snapshot_stateCapture a bounded snapshot state.
click, type, pressCore interaction primitives.
scroll, scroll_to_element, click_rectViewport movement + coordinate click.
evaluate_jsBounded JavaScript evaluation.
grant_permissions, clear_permissions, set_geolocationPermission management tools (backend-dependent).

Register a typed tool

from pydantic import BaseModel
from predicate.tools import ToolRegistry, ToolSpec

class EchoIn(BaseModel):
    message: str

class EchoOut(BaseModel):
    echoed: str

registry = ToolRegistry()
registry.register(ToolSpec(
    name="echo",
    description="Echo a message",
    input_model=EchoIn,
    output_model=EchoOut,
))

Execute tools (with tracing)

When you execute tools through the registry, inputs/outputs are validated and tool_call events are emitted (if tracing is enabled).

from predicate.tools import ToolRegistry, ToolContext, register_default_tools

registry = ToolRegistry()
register_default_tools(registry, runtime)

ctx = ToolContext(runtime)
result = await registry.execute("snapshot_state", {"limit": 60}, ctx=ctx)

Capability checks

Some tools require backend capabilities (e.g., permissions). Keep failures explicit:

Related topics