Control which tools an AI agent can call at each step

AI Agentsper-step tool scoping for AI agents

At each point in the conversation the model can only see the tools you allowed there.

contextsgovernance

The claim

The model cannot call a tool that is not exposed at the current step. The tool is absent from its world rather than discouraged by an instruction, so neither a persistent caller nor a prompt injection can reach it.

Example · Annotated transcript

agentThanks for calling. Can I get your full name?

callerActually just put me through to a person.

Step collect_name exposes only save_name. No transfer tool exists this turn, so there is nothing for the model to call.

agentI'll get you to someone right after I have your name.

callerDana Whitfield.

save_name ran and the handler advanced to collect_reason, which does list transfer_to_human.

agentThank you Dana. What's this about, so I route you correctly?

callerA billing charge I don't recognise.

agentPutting you through to billing now.

A caller trying to skip the intake step, and failing.

An example written from the code beside it, not a recording. Replays at reading pace.

Why it holds

This is the difference between a rule and a constraint. A prompt saying “do not transfer before taking a name” is a preference the model may ignore under pressure. A step that does not list transfer_to_human in its functions makes transferring unavailable.

How it works

The agent declares one context with two steps. Each step calls set_functions([...]) with exactly the tools that may exist while it is active, and set_valid_steps([...]) with where it may go next. In the SWML the platform receives, that becomes a functions whitelist on each step under ai.prompt.contexts.default.steps:

{"name": "collect_name",   "functions": ["save_name"],                     "valid_steps": ["collect_reason"]}
{"name": "collect_reason", "functions": ["save_reason", "transfer_to_human"], "valid_steps": ["collect_reason"]}

All three tools are defined once on the agent (ai.SWAIG.functions); the step decides which of them the model can see. save_name writes the caller’s name to global_data from the handler (set_global_data action), so the next step has it without the model relaying it. transfer_to_human returns FunctionResult(...).connect(address), which the platform receives as a SWML action carrying a connect verb plus "transfer": "true".

One thing to know: a step that does not call set_functions *inherits the previous step’s whitelist*. Declare it on every step.

Limitations

Step advancement is model-evaluated against the step criteria. Tool visibility is not. If the order itself must be guaranteed, force the transition from inside the tool handler rather than trusting the criteria.

What to change first

Add a third step and give it a tool the earlier steps must not reach. Then try to talk the agent into using it early.

Where this sits

python/app.py

"""Scope an agent's tools per step.

Each step declares exactly which functions exist while it is active. A tool the
step does not list is not withheld from the model - it is not presented at all.

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

from dotenv import load_dotenv
from signalwire import AgentBase
from signalwire.core.function_result import FunctionResult

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


class IntakeAgent(AgentBase):
    def __init__(self):
        super().__init__(name="intake", route="/intake")

        self.prompt_add_section(
            "Role",
            "You take a caller's name, then find out why they are calling, "
            "then route them. Follow the current step and nothing else.",
        )

        contexts = self.define_contexts()
        flow = contexts.add_context("default")

        # Step one: save_name is the only function that exists here.
        flow.add_step("collect_name") \
            .add_section("Current Task", "Ask for the caller's full name.") \
            .set_step_criteria("The caller has given a name.") \
            .set_functions(["save_name"]) \
            .set_valid_steps(["collect_reason"])

        # Step two: transferring becomes possible only now.
        flow.add_step("collect_reason") \
            .add_section("Current Task",
                         "Ask why they are calling, then route them.") \
            .set_step_criteria("The caller has explained why they called.") \
            .set_functions(["save_reason", "transfer_to_human"]) \
            .set_valid_steps(["collect_reason"])

    @AgentBase.tool(
        name="save_name",
        description="Record the caller's name",
        parameters={
            "name": {
                "type": "string",
                "description": "The caller's full name",
            }
        },
    )
    def save_name(self, args, raw_data):
        name = (args.get("name") or "").strip()
        if not name:
            return FunctionResult("I did not catch that - could you repeat it?")
        result = FunctionResult(f"Thank you {name}.")
        # Carry it forward without routing it back through the model.
        result.add_action("set_global_data", {"caller_name": name})
        return result

    @AgentBase.tool(
        name="save_reason",
        description="Record why the caller is calling",
        parameters={
            "reason": {
                "type": "string",
                "description": "Why the caller is calling, in their words",
            }
        },
    )
    def save_reason(self, args, raw_data):
        reason = (args.get("reason") or "").strip()
        result = FunctionResult("Got it.")
        result.add_action("set_global_data", {"intake_reason": reason})
        return result

    @AgentBase.tool(
        name="transfer_to_human",
        description="Connect the caller to a human agent",
        parameters={},
    )
    def transfer_to_human(self, args, raw_data):
        # connect() emits the documented shape: a SWML action carrying the
        # connect verb, plus "transfer": "true" so the agent exits. A bare
        # {"connect": ...} action is not in the platform's SWAIG action list.
        return FunctionResult("Connecting you now.").connect(
            os.environ["SUPPORT_ADDRESS"], final=True
        )


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

Run it

cd python
pip install -r requirements.txt
SUPPORT_ADDRESS=sip:support@yourspace.sip.signalwire.com python app.py

Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/intake/, using the credentials from your .env (the agent prints its URL and Basic Auth on start).

Verify it

No network, no account:

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

It renders the SWML and asserts the per-step functions lists. It then runs each tool handler and asserts the JSON keys the platform receives (set_global_data, SWML + transfer), never the SDK method names that produced them.

Report an issue

Control which tools an AI agent can call at each step

The claim

Why it holds

How it works

Limitations

What to change first

Where this sits

Before this

Related

Next

Seen in a build

Seen in a build

Seen in a build