Walk a caller through steps they cannot skip

AI Agentsguided AI conversation flow

Expose only the next allowed AI agent tool at each step so callers cannot move backward or skip ahead.

contexts

The claim

A step is a prompt the model reads while that step is active, plus three fields around it. valid_steps lists where the model’s next_step tool can go. functions lists the tools that exist while the step is active. step_criteria is the sentence the runtime judges before it advances. The steps reference documents all three. Each step below names exactly one tool, and each step but the last names only the step after it, so the flow is a line.

Why it holds

Tool handlers accept the answers and write them to global_data. Your handler decides whether an answer counts before anything is written.

How it works

Each step is declared once and carries its own edges.

flow.add_step("location") \
    .add_section("Current Task", "Ask where the vehicle is.") \
    .set_step_criteria("save_location has accepted a location.") \
    .set_functions(["save_location"]) \
    .set_valid_steps(["vehicle"])

The last step sets end instead of valid_steps. What the platform receives:

{"name": "location", "text": "...",
 "step_criteria": "save_location has accepted a location.",
 "functions": ["save_location"],
 "valid_steps": ["vehicle"]}

Call set_functions on every step. The SDK’s own note on set_functions says a step that does not declare functions inherits the previous step’s set. It calls that the most common bug in multi-step agents.

The handler judges the answer. A location under six characters returns INCOMPLETE and writes nothing; a vehicle needs at least two words. A usable answer emits set_global_data. The last handler records the problem and tells the model to say the request is recorded. This recipe dispatches nothing.

The SDK closes the flow at build time. A valid_steps entry naming a step that does not exist fails the context builder’s validate(). The SDK catches that error during render and logs it as ai_verb_config_error, so what you see is a schema error about a missing prompt. The line naming the step is in the log.

Limitations

A step is not a security boundary. step_criteria is a sentence the model judges, and valid_steps shapes the tool it is offered. What the verifier proves is the document: one tool per step, one edge per step. Anything that must not happen early belongs in a handler.

The verifier shows gather_info is absent from the SDK’s bundled schema, so a document using it cannot be validated offline. This recipe does not use it.

What to change first

Give vehicle a valid_steps of ["problem", "location"] and run the verifier. It fails on the backward edge: the document now offers the model a way back.

Where this sits

Before this

Control which tools an AI agent can call at each step

Enforce an AI agent's next step in code

python/app.py

"""Walk a caller through ordered steps.

A step is a prompt the model reads while that step is active, plus three
fields the platform reads around it:

  valid_steps    the only places the model's next_step tool can go
  functions      the only tools that exist while the step is active
  step_criteria  the sentence the runtime judges before advancing

The intake below has three steps. Every step names one tool, and every step
but the last names only the step after it, so the model is never offered a way
to skip ahead or double back. The data each step collects is written by a tool
handler, not read out of the transcript.

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()


class ClaimIntakeAgent(AgentBase):
    """Three questions, in order, for a roadside assistance line."""

    def __init__(self):
        super().__init__(name="claim-intake", route="/intake")
        self.prompt_add_section(
            "Role",
            "You record a roadside assistance request. Follow the current "
            "step. Ask one thing at a time and do not move on until the "
            "tool for this step has accepted the answer.",
        )

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

        # Each nonterminal step lists exactly one next step, so the next_step
        # tool the platform offers has one destination. Each step lists
        # exactly one function, so nothing else exists to call.
        flow.add_step("location") \
            .add_section("Current Task",
                         "Ask where the vehicle is: road or street, and the "
                         "nearest town or exit.") \
            .set_step_criteria("save_location has accepted a location.") \
            .set_functions(["save_location"]) \
            .set_valid_steps(["vehicle"])

        flow.add_step("vehicle") \
            .add_section("Current Task",
                         "Ask for the vehicle's make, model and colour.") \
            .set_step_criteria("save_vehicle has accepted a description.") \
            .set_functions(["save_vehicle"]) \
            .set_valid_steps(["problem"])

        flow.add_step("problem") \
            .add_section("Current Task",
                         "Ask what happened, then confirm the request is "
                         "recorded and end the call.") \
            .set_step_criteria("save_problem has accepted a description.") \
            .set_functions(["save_problem"]) \
            .set_end(True)

    # --- one tool per step -------------------------------------------------
    # Each handler validates, then writes to global_data. The model never
    # decides what counts as an answer; the handler does.

    @AgentBase.tool(
        name="save_location",
        description="Record where the vehicle is, after the caller says.",
        parameters={
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": ("Road or street plus the nearest town or "
                                    "exit, in the caller's words."),
                }
            },
            "required": ["location"],
        },
    )
    def save_location(self, args, raw_data):
        location = (args.get("location") or "").strip()
        if len(location) < 6:
            return FunctionResult(
                "INCOMPLETE: that is not enough to find them. Ask for the "
                "road and the nearest town or exit."
            )
        r = FunctionResult(f"Location saved: {location}.")
        r.add_action("set_global_data", {"location": location})
        return r

    @AgentBase.tool(
        name="save_vehicle",
        description="Record the vehicle's make, model and colour.",
        parameters={
            "type": "object",
            "properties": {
                "vehicle": {
                    "type": "string",
                    "description": "Make, model and colour, in the caller's words.",
                }
            },
            "required": ["vehicle"],
        },
    )
    def save_vehicle(self, args, raw_data):
        vehicle = (args.get("vehicle") or "").strip()
        if len(vehicle.split()) < 2:
            return FunctionResult(
                "INCOMPLETE: need at least make and colour. Ask again."
            )
        r = FunctionResult(f"Vehicle saved: {vehicle}.")
        r.add_action("set_global_data", {"vehicle": vehicle})
        return r

    @AgentBase.tool(
        name="save_problem",
        description="Record what is wrong with the vehicle.",
        parameters={
            "type": "object",
            "properties": {
                "problem": {
                    "type": "string",
                    "description": "What happened, in the caller's words.",
                }
            },
            "required": ["problem"],
        },
    )
    def save_problem(self, args, raw_data):
        problem = (args.get("problem") or "").strip()
        if not problem:
            return FunctionResult("INCOMPLETE: ask what happened.")
        # Nothing is dispatched here. A real line would hand the three saved
        # fields to its dispatch system; this one records them.
        r = FunctionResult(
            f"Problem saved: {problem}. Tell the caller the request is recorded."
        )
        r.add_action("set_global_data", {"problem": problem})
        return r


agent = ClaimIntakeAgent()

if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py

The webhook needs a public HTTPS URL. For a local run, expose port 3000 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/intake/.

Verify it

No network, no account.

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

It renders and validates the SWML, then asserts the following.

the three steps appear in order; each names one functions entry and carries the exact step_criteria sentence
each step but the last names only its successor in valid_steps, so next_step has no backward or skip target
the last step carries end and no valid_steps
an inadequate answer returns INCOMPLETE with no action; a usable one emits set_global_data, tested at the five and six character boundary and at one and two words
gather_info does not appear in the SDK’s bundled schema
the last handler’s reply tells the model to say the request is recorded
a step naming a destination that does not exist fails validate(), logs ai_verb_config_error naming it, and the render raises a schema error for the missing prompt

Report an issue