Claude Agent Guardrails: Block Unsafe Tool Calls Before They Run

With the Anthropic Messages API, Claude chooses which tool to call and with what arguments, and your code runs it. In this guide's calculator agent, add and multiply are the intended tools, yet Claude can also ask for divide. Run the loop with no check and divide runs: nothing stopped it. For a calculator that is harmless. Swap divide for issue_refund or delete_user and it would run just the same.

Claude only proposes a tool call. Your code runs it, so the check belongs on the function your code runs. beta_tool reads a function's name, docstring and signature to build the tool schema. governed_tools returns functions with all three unchanged, so wrap the plain function first and pass the wrapped one to beta_tool. Applying it to the finished tool object is the wrong order.

What happens on one tool call

1. Intercept. Claude asks for a tool and your loop calls it. The wrapper receives the call. Your function has not run.
2. Ask. The wrapper sends the tool name and its arguments, with the agent id, to the AgentTrust gateway. This is the pre-check.
3. Compare. The gateway checks the call against the agent's declared tools. A tool that is not declared, or an amount above its declared limit, is refused by the tool-trust hard gate.
4. Record. The gateway writes an event for the decision, allowed or refused.
5. Run or refuse. An allowed call runs, and its result goes back to the gateway for a post-check, a second event. A refused call never runs. Claude receives Blocked by AgentTrust as the tool result.

What the wrapper must cover

The check covers only the tools you wrap. A tool you hand to Claude unwrapped is not checked, so wrap every tool the agent has. Give each agent its own agent_id so the audit trail says who acted. The manifest matters too: an agent with no declared tools is not restricted, so every tool is allowed.

The same steps, applied to a small calculator agent. You run it three ways and watch a tool call get refused. About 10 minutes. Steps 1 to 4 need nothing else when you add --scripted to each command; without it they need ANTHROPIC_API_KEY. Steps 5 to 7 use an AgentTrust console account.

Create the project

mkdir agentrust-quickstart && cd agentrust-quickstart
python -m venv .venv && source .venv/bin/activate     # on Windows: .venv\Scripts\activate
pip install "agentrust-py[claude,embedded]"

Save the program below as claude_quickstart.py. It is the example examples/claude_quickstart.py from the AgentTrust SDK repository.

"""
claude_quickstart.py — a Claude agent whose tool calls AgentTrust checks.

The agent is a calculator: Claude (Anthropic Messages API) with add, multiply
and divide tools, asked to do two sums. The loop is the usual one: send the
messages, run each tool Claude asks for, send the results back.

AgentTrust is one line (marked "AgentTrust" below): the tools are wrapped with
governed_tools before they are turned into Claude tools. Every call is checked
before it runs, and its result after. A tool the agent may not use is refused
before its code runs; Claude is told why as the tool result and the run still
finishes. The agent may use add and multiply, not divide.

RUN IT (in the folder that holds this file)
    pip install "agentrust-py[claude,embedded]"
    export ANTHROPIC_API_KEY=...                          # or use --scripted, which needs no key

    python claude_quickstart.py --without-agentrust       # AgentTrust off: every tool runs
    python claude_quickstart.py --local                   # a gateway starts inside this program; no account
    python claude_quickstart.py --console                 # your AgentTrust console keeps every decision
    python claude_quickstart.py --scripted                # replay a fixed conversation instead of calling a model

  --console needs three settings, from the agent you create in the console:
      export AGENTRUST_GATEWAY_URL=https://console.agent-trust.tech
      export AGENTRUST_KEY=at_live_...
      export AGENTRUST_AGENT_ID=...

ANOTHER MODEL
    CLAUDE_QUICKSTART_MODEL=claude-opus-5-5 (export ANTHROPIC_API_KEY).
    Any Claude model that supports tool use works.
"""
from __future__ import annotations

import argparse
import os
import sys
import tempfile
from types import SimpleNamespace

from anthropic import Anthropic, beta_tool

from agentrust_sdk.adapters.claude_agents import governed_tools

AGENT_ID = os.environ.get("AGENTRUST_AGENT_ID", "calculator-agent")
MODEL = os.environ.get("CLAUDE_QUICKSTART_MODEL", "claude-sonnet-5-5")

# The tools this agent may call. With --local they are set here; with --console
# you declare the same list on the agent in the console. divide is left out on purpose.
MANIFEST = {"declared_tools": [{"name": "add"}, {"name": "multiply"}]}

SYSTEM = (
    "You do the arithmetic you are asked for, using your tools, one tool call at a time. "
    "If a tool is refused, say the operation could not be done."
)


def multiply(a: int, b: int) -> int:
    """Multiply `a` and `b`."""
    return a * b


def add(a: int, b: int) -> int:
    """Add `a` and `b`."""
    return a + b


def divide(a: int, b: int) -> float:
    """Divide `a` by `b`."""
    return a / b


# AgentTrust: every call to these tools is checked before it runs and after it
# returns. Turn the wrapped functions into Claude tools, not the plain ones.
tools = [beta_tool(fn) for fn in governed_tools([add, multiply, divide], agent_id=AGENT_ID)]

REQUESTS = ["Add 3 and 4.", "Divide 10 by 2."]


def ask(request: str, client, max_turns: int = 6) -> str:
    """The agent loop: run the tools Claude asks for until it answers in text."""
    by_name = {tool.name: tool for tool in tools}
    messages = [{"role": "user", "content": request}]
    for _ in range(max_turns):
        reply = client.messages.create(
            model=MODEL, max_tokens=1024, system=SYSTEM, messages=messages,
            tools=[tool.to_dict() for tool in tools],
        )
        messages.append({"role": "assistant", "content": reply.content})
        calls = [block for block in reply.content if block.type == "tool_use"]
        if not calls:
            return "".join(block.text for block in reply.content if block.type == "text")
        results = []
        for call in calls:
            # A refused call returns the refusal text here, and Claude reads it next turn.
            output = by_name[call.name].call(call.input)
            print(f"  tool {call.name}({', '.join(f'{k}={v}' for k, v in call.input.items())}) -> {output}")
            results.append({"type": "tool_result", "tool_use_id": call.id, "content": str(output)})
        messages.append({"role": "user", "content": results})
    return "(stopped: too many turns)"


# --scripted: replay a fixed conversation, so the quickstart runs with no model and no key.
# A replay does not read tool results, so its last line is the same with AgentTrust on or off;
# what differs is what each tool returned.
# Each reply is either a tool call (name, arguments) or the final text.
SCRIPT = [
    ("add", {"a": 3, "b": 4}), "3 + 4 = 7.",
    ("divide", {"a": 10, "b": 2}), "That is everything you asked for.",
]


class ScriptedClient:
    """Stands in for Anthropic(): messages.create returns the next scripted reply."""

    def __init__(self, replies=SCRIPT) -> None:
        self._replies = list(replies)
        self.messages = SimpleNamespace(create=self._create)

    def _create(self, **kwargs):
        reply = self._replies.pop(0)
        if isinstance(reply, str):
            block = SimpleNamespace(type="text", text=reply)
        else:
            name, args = reply
            block = SimpleNamespace(type="tool_use", id=f"toolu_{len(self._replies)}", name=name, input=args)
        return SimpleNamespace(content=[block], stop_reason="end_turn")


def ask_agent(where: str, scripted: bool) -> bool:
    """Ask the agent to add, then to divide. False if the model can't be reached."""
    print(f"AgentTrust: {where} · agent {AGENT_ID} · model {'scripted' if scripted else MODEL}")
    client = ScriptedClient() if scripted else Anthropic()
    try:
        for request in REQUESTS:
            print(f"\n=== {request} ===")
            print(f"\nResult: {ask(request, client)}")
    except Exception as exc:  # noqa: BLE001 - any provider error ends the run
        print(f"\nThe model call failed ({MODEL}): {exc}\n"
              "Check ANTHROPIC_API_KEY is set, or run with --scripted.", file=sys.stderr)
        return False
    return True


# --without-agentrust: every tool runs. For comparison.
def run_without_agentrust(scripted: bool) -> int:
    os.environ["AGENTRUST_ENABLED"] = "false"   # the SDK's off switch: wrapped tools pass every call through
    return 0 if ask_agent("off (every tool runs)", scripted) else 1


# --local: a gateway runs inside this program; no account needed.
def run_local(scripted: bool) -> int:
    from agentrust_sdk.embedded import embed_gateway

    # SQLite in a temp dir, gone after the run. embed_gateway sets
    # AGENTRUST_GATEWAY_URL and AGENTRUST_KEY, which governed_tools reads.
    gateway = embed_gateway(db_path=os.path.join(tempfile.mkdtemp(), "gateway.db"))
    gateway.register_manifest(AGENT_ID, MANIFEST)
    try:
        ok = ask_agent(f"local gateway {gateway.url} (no account, nothing kept)", scripted)
    finally:
        gateway.stop()
    return 0 if ok else 1


# --console: the SDK sends every check to your console, which keeps the decisions.
def run_with_console(scripted: bool) -> int:
    missing = [v for v in ("AGENTRUST_GATEWAY_URL", "AGENTRUST_KEY", "AGENTRUST_AGENT_ID") if not os.environ.get(v)]
    if missing:
        print(f"Set {', '.join(missing)} (from the agent you created in the console), or use --local.",
              file=sys.stderr)
        return 2
    console = os.environ["AGENTRUST_GATEWAY_URL"]
    ok = ask_agent(f"console {console}", scripted)
    print(f"\nOpen Events in the console ({console}) and filter by agent ID {AGENT_ID}.")
    return 0 if ok else 1


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description="The Claude calculator agent, governed by AgentTrust.")
    where = parser.add_mutually_exclusive_group()
    where.add_argument("--local", action="store_true", help="run a gateway inside this program, no account (the default)")
    where.add_argument("--console", action="store_true", help="send every check to your AgentTrust console")
    where.add_argument("--without-agentrust", action="store_true", help="for comparison: AgentTrust off, every tool runs")
    parser.add_argument("--scripted", action="store_true", help="replay a fixed conversation: no model, no API key")
    args = parser.parse_args(argv)
    if args.without_agentrust:
        return run_without_agentrust(args.scripted)
    return run_with_console(args.scripted) if args.console else run_local(args.scripted)


if __name__ == "__main__":
    sys.exit(main())

Run it without AgentTrust

First, see what the agent does on its own:

python claude_quickstart.py --without-agentrust --scripted

The scripted agent replays a fixed conversation and does not read tool results, so its last line is the same with AgentTrust on or off. What differs is what each tool returned.

AgentTrust: off (every tool runs) · agent calculator-agent · model scripted

=== Add 3 and 4. ===
  tool add(a=3, b=4) -> 7

Result: 3 + 4 = 7.

=== Divide 10 by 2. ===
  tool divide(a=10, b=2) -> 5.0

Result: That is everything you asked for.

The agent used divide and nothing stopped it.

Where governed_tools sits in the Claude file

This is the only change AgentTrust needs, and it is already in your file, so there is nothing to edit. Find the governed_tools line near the top, right after the tools are defined and before the loop uses them. On your own agent it looks like this:

+ from agentrust_sdk.adapters.claude_agents import governed_tools
- tools = [beta_tool(fn) for fn in [add, multiply, divide]]
+ tools = [beta_tool(fn) for fn in governed_tools([add, multiply, divide], agent_id=AGENT_ID)]

Names, descriptions and argument types stay the same, so Claude sees what it saw before. Every tool call now goes through AgentTrust first. Allowed calls run and their results are checked. Refused calls never run.

Run it locally

python claude_quickstart.py --local --scripted

The program starts a small AgentTrust gateway inside itself and allows only the tools in MANIFEST: add and multiply. divide is not on the list. No account needed.

AgentTrust: local gateway http://127.0.0.1:8765 (no account, nothing kept) · agent calculator-agent · model scripted

=== Add 3 and 4. ===
  tool add(a=3, b=4) -> 7

Result: 3 + 4 = 7.

=== Divide 10 by 2. ===
  tool divide(a=10, b=2) -> Blocked by AgentTrust: Tool-trust hard gate: action 'divide' is
not in this agent's declared_tools (envelope dec75b50-beb1-4603-a8e7-cd8bdad96951)

Result: That is everything you asked for.

add returned 7. divide was refused before its code ran, and Claude was told why, so the run still finished. Nothing is kept after the program exits.

Create the agent in your console

To keep decisions and manage the agent from the console, register it there:

1. Open Agents, select New agent, name it claude-quickstart, and select Create.
2. Copy the API Key and the Agent ID before you select Done. The key starts with at_live_ and is shown only once.
3. Select the agent in the list. Under Manifest & fingerprint, select Declare. Under Declared tools, select + Add tool twice, type add and multiply, and select Save manifest.

Step 3 is the same list MANIFEST holds in the program, now kept in the console. An agent with no declared tools is not restricted, so divide would run.

Run it against the console

export AGENTRUST_GATEWAY_URL=https://console.agent-trust.tech   # your console's address
export AGENTRUST_KEY=at_live_...                                # the API key
export AGENTRUST_AGENT_ID=claude-quickstart                     # the Agent ID

python claude_quickstart.py --console --scripted

The first line names the console, and the run should match the local one: add returns 7 and divide is refused with the same Blocked by AgentTrust text. Drop --scripted to use a real model.

See the decisions in the console

Open Events in the console and type your Agent ID into Filter by Agent ID. You will see one row per decision: add approved before and after it ran, and divide blocked.

With a real model

We also ran claude-haiku-4-5 as the agent, text only, through the logged-in claude CLI. It is not the tool_runner helper against the live Messages API. add ran. divide was refused and Haiku told the user it was blocked. A $40 refund ran. A $5,000 refund was refused and Haiku explained the $100 limit.

Wrap the function first. Then hand it to beta_tool.

Hold risky calls for a person. Set the agent's mode to Human Review. Rejected or timed-out calls do not run. See the Claude integration docs.

Check every reply too. Wrap your client with ClaudeAgentGuard(agent_id=...).wrap_client(client). A blocked reply raises BlockedError.

Serving tools over MCP? MCP Server Security: Block Unsafe Tool Calls Before They Run does the same with one line. Same check on other frameworks: Block Unsafe AutoGen Tool Calls Before They Run, or build a full governed bot in Guide: Stop Your AI Support Bot from Issuing a Bad Refund.