Require verification before unlocking AI agent tools

AI Agentsverification-gated AI agent tools

The account tools do not exist in the model's world until a handler says the caller passed.

governancetool-calling

The claim

The model cannot call a tool that is not active. get_balance and list_recent_transactions are declared with active: false, so at the start of the call they are not in the model’s world: not discouraged, absent. The only thing that turns them on is a toggle_functions action emitted by the verify_pin handler. The handler emits it only when the PIN matches the caller’s record. A prompt that says “verify before discussing the account” is a request; this is a constraint.

How it works

@AgentBase.tool(name="get_balance", description="...", parameters={}, active=False)
def get_balance(self, args, raw_data): ...

@AgentBase.tool(name="verify_pin", ...)
def verify_pin(self, args, raw_data):
    if pin_matches(raw_data["caller_id_num"], args["pin"]):
        return (FunctionResult("You are verified.")
                .toggle_functions([{"function": "get_balance", "active": True},
                                   {"function": "list_recent_transactions", "active": True}])
                .toggle_functions([{"function": "verify_pin", "active": False}])
                .update_global_data({"verified": True}))
    return FunctionResult("That PIN does not match.")   # no action: nothing unlocks

In the rendered SWML the account functions carry "active": false. The successful handler’s reply carries the platform action the model never composes:

{"toggle_functions": [{"function": "get_balance", "active": true}, {"function": "list_recent_transactions", "active": true}]}

The check is code, so a caller from an unknown number with the right digits still fails, and verify_pin retires itself once it has done its job. Retiring is optional; re-verification mid-call is the same toggle in reverse.

What to change first

Swap the PIN for an OTP: send a code with send-an-otp-by-sms-with-voice-fallback and verify it in the same handler before toggling the tools on.

Where this sits

Before this

Give a voice AI agent a tool

Control which tools an AI agent can call at each step Show the AI model only the fields it needs

Send an OTP by SMS, with voice fallback

python/app.py

"""Require verification before unlocking tools.

The account tools are declared with `active: False`, so they are not in the
model's tool list when the call starts. Only the verification handler - code,
not the model - turns them on, with a `toggle_functions` action, and only when
the code is right.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

# the SDK does not read .env for you
load_dotenv()

ACCOUNT_TOOLS = ["get_balance", "list_recent_transactions"]

# Your system of record. Keyed by phone number for the demo.
CUSTOMERS = {
    "+15551234567": {"pin": "4242", "balance": "1,204.18",
                     "recent": ["-42.10 grocery", "-9.99 streaming"]},
}


class BankAgent(AgentBase):
    def __init__(self):
        super().__init__(name="bank", route="/bank")
        self.prompt_add_section(
            "Role",
            "You are a bank's phone line. Before anything else, ask for the "
            "caller's four-digit PIN and call verify_pin. Never guess account "
            "details.",
        )

    @AgentBase.tool(
        name="verify_pin",
        description="Check the caller's PIN. Account tools unlock only on success.",
        parameters={"pin": {"type": "string", "description": "Four-digit PIN"}},
    )
    def verify_pin(self, args, raw_data):
        caller = (raw_data or {}).get("caller_id_num", "")
        customer = CUSTOMERS.get(caller)
        if not customer or (args.get("pin") or "").strip() != customer["pin"]:
            # No action: the account tools stay inactive.
            return FunctionResult("That PIN does not match. Please try again.")
        result = FunctionResult("Thank you, you are verified. How can I help?")
        # The unlock is a platform action emitted by code, not a prompt instruction.
        result.toggle_functions([{"function": f, "active": True} for f in ACCOUNT_TOOLS])
        result.toggle_functions([{"function": "verify_pin", "active": False}])
        result.update_global_data({"verified": True})
        return result

    @AgentBase.tool(
        name="get_balance",
        description="Read the verified caller's balance",
        parameters={},
        active=False,   # not in the model's world until verify_pin succeeds
    )
    def get_balance(self, args, raw_data):
        c = CUSTOMERS.get((raw_data or {}).get("caller_id_num", ""))
        if not c:
            return FunctionResult("No account found.")
        return FunctionResult(f"The balance is {c['balance']} dollars.")

    @AgentBase.tool(
        name="list_recent_transactions",
        description="Read the verified caller's last transactions",
        parameters={},
        active=False,
    )
    def list_recent_transactions(self, args, raw_data):
        c = CUSTOMERS.get((raw_data or {}).get("caller_id_num", ""))
        return FunctionResult("; ".join(c["recent"]) if c else "No account found.")


if __name__ == "__main__":
    BankAgent().serve(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
python app.py

Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/bank/, using the credentials from your .env. The demo customer is +15551234567 with PIN 4242; replace CUSTOMERS with your system of record.

Verify it

python verify.py          # from the recipe folder, not python/

It renders the SWML and asserts the account tools are active: false. It then runs the handler three ways:

a wrong PIN produces no action
the right PIN produces a toggle_functions action activating exactly the account tools
the right PIN from an unknown number produces no action

Report an issue