Commit a transaction from a call

AI Agentsvoice transaction confirmation

Use an allow-list to validate the caller's confirmation before one transaction tool commits the request.

tool-callingcontexts

The claim

Three tools, one write. set_order records the items in global_data and marks the order unconfirmed. confirm_order takes an answer argument: the words the model relays from the caller after the readback. The handler marks the order confirmed only when it finds that answer in an allow-list of whole phrases. commit_order writes to the order book once, and only when confirmed is true in the global_data the platform posted with the call.

Why it holds

The model proposes each step and relays the words. The handlers decide whether the step counts, from state they wrote themselves. No sequence of model calls writes an order without an answer the code accepted as a yes.

How it works

def confirm_order(self, args, raw_data):
    order = raw_data.get("global_data", {}).get("order")
    if not order:
        return FunctionResult("INCOMPLETE: there is no order to confirm yet.")
    readback = f"{', '.join(order['items'])} for {order['total']:.2f}"
    if normalise(args.get("answer")) not in YES:
        return FunctionResult(f"NOT_A_YES: the caller did not clearly agree to {readback}.")
    r = FunctionResult(f"Confirmed: {readback}. You may commit it now.")
    r.add_action("set_global_data", {"confirmed": True})
    return r

normalise lower-cases the answer, expands “that’s” and “it’s”, and drops punctuation and four politeness words. The handler then looks the result up in a set of whole answers. Membership, never substring: “yesterday” contains “yes” and is not a yes, and neither is “I can’t say yes”. commit_order checks three things in order: the book already has this call_id, there is an order, and confirmed is true.

Every refusal is a response with no action, so the payload carries the reason and changes nothing. set_order emits "confirmed": false alongside the order every time:

{"response": "Order noted: helmet, puncture-kit, total 101.50. Read it back ...",
 "action": [{"set_global_data": {"order": {"items": ["helmet", "puncture-kit"],
                                           "total": 101.5},
                                 "confirmed": false}}]}

A caller who confirms and then changes their mind therefore confirms again. The order book is keyed by call_id, which makes the commit idempotent per call: a repeated commit_order returns the id already on file.

The items parameter carries an enum of the catalogue. The handler drops anything outside it anyway, and refuses a list with nothing left.

Limitations

The handler judges the words it is given. The model relays them; nothing here proves they are the caller’s, and a stricter recipe would take the answer from DTMF or a prompt the platform collected.

The yes-set is small on purpose, and “sure thing” is asked again. Extend YES with whole phrases, never with substrings.

The order book is a dictionary in the process. Your version writes to a system that can itself refuse a duplicate keyed by call_id, because a restart between two commits would forget the first.

What to change first

Delete the NOT_CONFIRMED check in commit_order and run the verifier. The commit-before-confirmation assertion fails and the book has an order nobody confirmed, which is the failure this recipe exists to prevent.

Where this sits

Before this

Give a voice AI agent a tool

Enforce an AI agent's next step in code Write call dispositions from data your handlers recorded

Seen in a build

One of 8 recipes composed by AI phone ordering: a voice agent working with a live backend in real time.

python/app.py

"""Commit a transaction from a call.

Three tools, one write. `set_order` records what the caller wants in
`global_data` and marks it unconfirmed. `confirm_order` takes the caller's
answer to the readback and marks the order confirmed only when the handler
judges that answer a yes. `commit_order` writes it, once, and only when that
confirmation is on record. The model proposes each step; the handlers decide
whether the step counts, and nothing reaches the order book before a yes the
code accepted.

The handlers read state from `global_data` in `raw_data`, the copy the
platform posts with every tool call, not from anything the model says.

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

MENU = {"cargo-rack": 45.00, "puncture-kit": 12.50, "helmet": 89.00}

# The whole normalised answers that count as a yes. Matching is by set
# membership, never substring: "yesterday" and "I can't say yes" are not here.
YES = {"yes", "yep", "yeah", "correct", "that is right", "that is correct",
       "go ahead", "confirm", "confirmed", "yes that is right"}


def normalise(text):
    """Lower-case, expand contractions, drop punctuation and politeness."""
    t = (text or "").lower().replace("that's", "that is").replace("it's", "it is")
    t = "".join(ch if ch.isalnum() or ch == " " else " " for ch in t)
    words = [w for w in t.split() if w not in ("please", "thanks", "thank", "you")]
    return " ".join(words)

# The order book. Keyed by call id, so a call can commit exactly once. A real
# handler writes to your order system here.
ORDERS = {}


class OrderAgent(AgentBase):
    def __init__(self):
        super().__init__(name="orders", route="/orders")
        self.prompt_add_section(
            "Role",
            "You take accessory orders for Ridgeline Cycles. Use set_order when "
            "the caller says what they want, then read the items and total back "
            "and ask if that is right. Pass their exact answer to confirm_order. "
            "Use commit_order only after confirm_order says you may.",
        )

    @AgentBase.tool(
        name="set_order",
        description="Record the items the caller wants. Replaces any earlier list.",
        parameters={
            "type": "object",
            "properties": {
                "items": {
                    "type": "array",
                    "items": {"type": "string", "enum": sorted(MENU)},
                    "description": "Catalogue item names.",
                }
            },
            "required": ["items"],
        },
    )
    def set_order(self, args, raw_data):
        items = [i for i in (args.get("items") or []) if i in MENU]
        if not items:
            return FunctionResult("INVALID: none of those are catalogue items. "
                                  "Offer the catalogue.")
        total = round(sum(MENU[i] for i in items), 2)
        r = FunctionResult(f"Order noted: {', '.join(items)}, total {total:.2f}. "
                           "Read it back and ask the caller to confirm.")
        # any new list resets the confirmation
        r.add_action("set_global_data", {"order": {"items": items, "total": total},
                                         "confirmed": False})
        return r

    @AgentBase.tool(
        name="confirm_order",
        description=("Pass the caller's exact words in answer to the readback of "
                     "the items and total."),
        parameters={
            "type": "object",
            "properties": {"answer": {"type": "string",
                                      "description": "What the caller said, verbatim."}},
            "required": ["answer"],
        },
    )
    def confirm_order(self, args, raw_data):
        order = ((raw_data or {}).get("global_data") or {}).get("order")
        if not order:
            return FunctionResult("INCOMPLETE: there is no order to confirm yet.")
        readback = f"{', '.join(order['items'])} for {order['total']:.2f}"
        if normalise(args.get("answer")) not in YES:
            return FunctionResult(f"NOT_A_YES: the caller did not clearly agree to "
                                  f"{readback}. Ask again or change the order.")
        r = FunctionResult(f"Confirmed: {readback}. You may commit it now.")
        r.add_action("set_global_data", {"confirmed": True})
        return r

    @AgentBase.tool(
        name="commit_order",
        description="Place the confirmed order. Only after confirm_order.",
        parameters={"type": "object", "properties": {}},
    )
    def commit_order(self, args, raw_data):
        raw = raw_data or {}
        data = raw.get("global_data") or {}
        call_id = raw.get("call_id")
        if call_id in ORDERS:
            # the model asked twice; the book already has it
            return FunctionResult(f"ALREADY_PLACED: order {ORDERS[call_id]['id']} "
                                  "is on file. Do not place it again.")
        if not data.get("order"):
            return FunctionResult("INCOMPLETE: take the order first.")
        if data.get("confirmed") is not True:
            return FunctionResult("NOT_CONFIRMED: read the order back and get a yes "
                                  "before committing.")
        order_id = f"RC-{len(ORDERS) + 1001}"
        ORDERS[call_id] = {"id": order_id, **data["order"]}
        r = FunctionResult(f"Placed as {order_id}. Tell the caller the number.")
        r.add_action("set_global_data", {"order_id": order_id})
        return r


agent = OrderAgent()

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>/orders/, order a helmet, and answer the readback with “yesterday”.

Verify it

No network, no account.

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

The verifier threads global_data between tool calls the way the platform does and asserts the order book after each step.

the three tools render, and set_order carries the catalogue as an enum
commit_order and confirm_order before any order each return INCOMPLETE with no action
an empty item list, or one with nothing from the catalogue, returns INVALID with no action and leaves the session and the book untouched
set_order drops an item outside the catalogue and emits the order with confirmed: false
commit_order before confirmation returns NOT_CONFIRMED; the book is empty
“yesterday”, “no”, “I can’t say yes”, ““, “yes or no” and “sure thing” each return NOT_A_YES with no action
“Yes, that’s right.“ returns the exact readback response and confirmed: true
changing the order after confirming resets confirmed to false, and the commit is refused again
“Yes, thank you!“ confirms, because politeness and punctuation are dropped before the lookup
committing after a yes writes one order and returns its id
a second commit on the same call returns ALREADY_PLACED with that id, and the book still holds one
a second call id gets its own order

Report an issue