Collect required details in any order with a voice AI agent

AI Agentsslot filling for voice AI agents

Let a caller give the required details of a report in any order, keep the checklist in the tool handlers, and refuse to file until every required detail is in.

Also called form filling by voice, absence reporting line, intake checklist, required fields before submit

tool-callinggovernance

The claim

A form has required fields, and a phone call does not fill them in order. The caller says why they are out before they say who they are. This agent takes the details as they come. record_detail takes a field name and a value and writes the whole details object back with set_global_data. Its response tells the model what is still needed, in the words the checklist uses, so the model asks for that and nothing already recorded.

Why it holds

submit_report takes no arguments. It reads the collected details from the global_data the platform posted with the call, and it files the report only when every required field is there. A model that asks to submit early gets a MISSING list, not a report. The prompt says “record each detail as soon as you hear it”; the handlers are what make the order not matter.

How it works

REQUIRED = {"employee_name": "the employee's name",
            "shift_date": "the date of the shift",
            "reason": "the reason for the absence"}

def record_detail(self, args, raw_data):
    field, value = _text(args.get("field")), _text(args.get("value"))
    details = dict((raw_data.get("global_data") or {}).get("details") or {})
    details[field] = value
    result = FunctionResult(f"Recorded {FIELDS[field]}. {status_line(details)}")
    result.update_global_data({"details": details})   # the whole object
    return result

def submit_report(self, args, raw_data):
    details = (raw_data.get("global_data") or {}).get("details") or {}
    if missing(details):
        return FunctionResult("MISSING: " + ", ".join(...) + ". Ask for those.")
    ...

The field parameter is an enum of the checklist, so the model is offered the field names rather than inventing them. The enum shapes the offer only: an out-of-enum value still reaches the handler, which answers UNKNOWN_FIELD and writes nothing.

set_global_data merges top-level keys. Writing {"details": {"reason": ...}} would replace the whole object and lose the fields already recorded. So the handler reads the current object from the request, adds the one field, and writes the whole object back. The verifier threads global_data between calls the way the platform does, applying each action before the next call.

submit_report also reads report_id from global_data. Once a report is filed, asking again, or a retry of the same call, gets ALREADY_FILED with the reference and no second report.

What the first record_detail returns, with the reason given first:

{"response": "Recorded the reason for the absence. Still needed: the employee's name, the date of the shift.",
 "action": [{"set_global_data": {"details": {"reason": "a fever"}}}]}

Limitations

The report is filed into a list in the process. Your HR system replaces it. The report_id check makes a retry within the call harmless; a retry after the call has ended is your system’s idempotency key to keep.

Two record_detail calls emitted in one model turn would each read the same global_data, and the second whole-object write would drop the first field. Whether the platform applies one action before the next call in the same turn is not something this verifier can prove. The prompt asks for one detail per call for that reason.

Optional fields are recorded the same way but never block the submit. Whether a detail is required is a line in REQUIRED, not a prompt sentence.

The TypeScript SDK’s /swaig route in 2.0.5 hands argument to the handler as posted, while the platform nests the arguments in argument.parsed[0]. The surface overrides onFunctionCall to unwrap that shape.

What to change first

Move reason from REQUIRED to OPTIONAL and run the verifier. The first submit still refuses, but for one field, and the expected MISSING line no longer matches. The checklist is code, and the verifier reads it as code.

Where this sits

Before this

Give a voice AI agent a tool

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

python/app.py

"""Collect required details in any order.

A caller reporting an absence gives the details in whatever order they come
to mind. One tool, `record_detail`, takes a field name and a value and writes
it into `global_data`; the handler answers with what is still missing. A
second tool, `submit_report`, reads the collected details from the request
body and refuses until every required field is present. The prompt asks; the
handlers keep the checklist.

Written against signalwire-sdk 3.0.1.
"""
import os
from datetime import datetime, timezone

from dotenv import load_dotenv
from signalwire import AgentBase, FunctionResult

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

# The checklist. Order here is the order the model is offered, nothing more:
# the caller may fill it in any order.
REQUIRED = {"employee_name": "the employee's name",
            "shift_date": "the date of the shift",
            "reason": "the reason for the absence"}
OPTIONAL = {"expected_return": "when they expect to be back",
            "notes": "anything else for the manager"}
FIELDS = {**REQUIRED, **OPTIONAL}

# Your HR system. A real one is an API call.
REPORTS = []


def _text(value):
    """The model may send a number where a string was asked for."""
    return "" if value is None else str(value).strip()


def missing(details):
    """The required fields not yet recorded, in checklist order."""
    return [f for f in REQUIRED if not _text(details.get(f))]


def status_line(details):
    gaps = missing(details)
    if gaps:
        return "Still needed: " + ", ".join(REQUIRED[f] for f in gaps) + "."
    return ("Everything required is recorded. Read the details back to the caller, "
            "then call submit_report.")


class AbsenceLine(AgentBase):
    def __init__(self):
        super().__init__(name="absence-line", route="/absence")
        self.prompt_add_section(
            "Role",
            "You take absence reports for a warehouse. Callers give details in any "
            "order; record each one as soon as you hear it. Never ask for something "
            "already recorded. When the tool says everything required is in, read "
            "the details back and submit.",
        )

    @AgentBase.tool(
        name="record_detail",
        description=("Record one detail of the absence report as soon as the caller "
                     "says it, in any order. Call it once per detail."),
        parameters={
            "type": "object",
            "properties": {
                "field": {"type": "string", "enum": list(FIELDS),
                          "description": "Which detail this is."},
                "value": {"type": "string",
                          "description": "The detail in the caller's words."},
            },
            "required": ["field", "value"],
        },
    )
    def record_detail(self, args, raw_data):
        field = _text(args.get("field"))
        value = _text(args.get("value"))
        if field not in FIELDS:
            # the enum shapes what the model is offered; the handler decides
            return FunctionResult(f"UNKNOWN_FIELD: {field!r} is not on the report. "
                                  f"Record one of: {', '.join(FIELDS)}.")
        if not value:
            return FunctionResult(f"EMPTY: nothing to record for {FIELDS[field]}. "
                                  "Ask the caller again.")
        details = dict((raw_data.get("global_data") or {}).get("details") or {})
        details[field] = value
        # set_global_data merges top-level keys, so the whole details object
        # goes back, not one field of it
        result = FunctionResult(f"Recorded {FIELDS[field]}. {status_line(details)}")
        result.update_global_data({"details": details})
        return result

    @AgentBase.tool(
        name="submit_report",
        description=("File the absence report. Only call this after the tool has said "
                     "everything required is recorded."),
        parameters={"type": "object", "properties": {}},
    )
    def submit_report(self, args, raw_data):
        global_data = raw_data.get("global_data") or {}
        if global_data.get("report_id"):
            # a retry, or the model asking twice: one report per call
            return FunctionResult(f"ALREADY_FILED: {global_data['report_id']}. Tell the "
                                  "caller the reference.")
        details = global_data.get("details") or {}
        gaps = missing(details)
        if gaps:
            # the model asked to submit early; the checklist says no
            return FunctionResult("MISSING: " + ", ".join(REQUIRED[f] for f in gaps)
                                  + ". Ask for those before submitting.")
        report_id = f"ABS-{len(REPORTS) + 1001}"
        REPORTS.append({"id": report_id, **details,
                        "filed_at": datetime.now(timezone.utc).isoformat()})
        result = FunctionResult(
            f"Report {report_id} filed for {details['employee_name']}, "
            f"shift {details['shift_date']}. Tell the caller the reference and end "
            "the call.")
        result.update_global_data({"report_id": report_id})
        return result


agent = AbsenceLine()

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

/**
 * Collect required details in any order.
 *
 * A caller reporting an absence gives the details in whatever order they come
 * to mind. One tool, `record_detail`, takes a field name and a value and
 * writes it into `global_data`; the handler answers with what is still
 * missing. A second tool, `submit_report`, reads the collected details from
 * the request body and refuses until every required field is present. The
 * prompt asks; the handlers keep the checklist.
 *
 * Written against @signalwire/sdk 2.0.5.
 *
 *     npm start            # serves /absence/ and /absence/swaig
 */
import "dotenv/config";
import { AgentBase, FunctionResult } from "@signalwire/sdk";

type Json = Record<string, unknown>;
type Hook = Promise<Json> | undefined;

// The checklist. Order here is the order the model is offered, nothing more:
// the caller may fill it in any order.
export const REQUIRED: Record<string, string> = {
  employee_name: "the employee's name",
  shift_date: "the date of the shift",
  reason: "the reason for the absence",
};
export const OPTIONAL: Record<string, string> = {
  expected_return: "when they expect to be back",
  notes: "anything else for the manager",
};
export const FIELDS = { ...REQUIRED, ...OPTIONAL };

// Your HR system. A real one is an API call.
export const REPORTS: Json[] = [];

const text = (v: unknown) => String(v ?? "").trim();

/** The required fields not yet recorded, in checklist order. */
export const missing = (details: Record<string, string>) =>
  Object.keys(REQUIRED).filter((f) => !text(details[f]));

function statusLine(details: Record<string, string>) {
  const gaps = missing(details);
  if (gaps.length) {
    return "Still needed: " + gaps.map((f) => REQUIRED[f]).join(", ") + ".";
  }
  return "Everything required is recorded. Read the details back to the caller, "
       + "then call submit_report.";
}

const detailsOf = (raw: Json) =>
  ({ ...(((raw["global_data"] as Json | undefined) ?? {})["details"] as
      Record<string, string> | undefined ?? {}) });

export class AbsenceLine extends AgentBase {
  constructor() {
    super({ name: "absence-line", route: "/absence" });
    this.promptAddSection("Role", {
      body: "You take absence reports for a warehouse. Callers give details in any "
          + "order; record each one as soon as you hear it. Never ask for something "
          + "already recorded. When the tool says everything required is in, read "
          + "the details back and submit.",
    });
    this.defineTool({
      name: "record_detail",
      description: "Record one detail of the absence report as soon as the caller "
                 + "says it, in any order. Call it once per detail.",
      parameters: {
        type: "object",
        properties: {
          field: { type: "string", enum: Object.keys(FIELDS),
                   description: "Which detail this is." },
          value: { type: "string", description: "The detail in the caller's words." },
        },
        required: ["field", "value"],
      },
      handler: (args, raw) => {
        const field = text(args["field"]);
        const value = text(args["value"]);
        if (!Object.hasOwn(FIELDS, field)) {
          // the enum shapes what the model is offered; the handler decides
          return new FunctionResult(`UNKNOWN_FIELD: '${field}' is not on the report. `
            + `Record one of: ${Object.keys(FIELDS).join(", ")}.`);
        }
        if (!value) {
          return new FunctionResult(`EMPTY: nothing to record for ${FIELDS[field]}. `
                                    + "Ask the caller again.");
        }
        const details = detailsOf(raw);
        details[field] = value;
        // set_global_data merges top-level keys, so the whole details object
        // goes back, not one field of it
        return new FunctionResult(`Recorded ${FIELDS[field]}. ${statusLine(details)}`)
          .updateGlobalData({ details });
      },
    });
    this.defineTool({
      name: "submit_report",
      description: "File the absence report. Only call this after the tool has said "
                 + "everything required is recorded.",
      parameters: { type: "object", properties: {} },
      handler: (_args, raw) => {
        const filed = ((raw["global_data"] as Json | undefined) ?? {})["report_id"];
        if (filed) {
          // a retry, or the model asking twice: one report per call
          return new FunctionResult(
            `ALREADY_FILED: ${filed}. Tell the caller the reference.`);
        }
        const details = detailsOf(raw);
        const gaps = missing(details);
        if (gaps.length) {
          // the model asked to submit early; the checklist says no
          return new FunctionResult("MISSING: " + gaps.map((f) => REQUIRED[f]).join(", ")
                                    + ". Ask for those before submitting.");
        }
        const reportId = `ABS-${REPORTS.length + 1001}`;
        REPORTS.push({ id: reportId, ...details, filed_at: new Date().toISOString() });
        return new FunctionResult(
          `Report ${reportId} filed for ${details["employee_name"]}, `
          + `shift ${details["shift_date"]}. Tell the caller the reference and end `
          + "the call.")
          .updateGlobalData({ report_id: reportId });
      },
    });
  }

  /**
   * The platform posts a tool's arguments as `argument: {parsed: [args], raw}`.
   * The 2.0.5 `/swaig` route hands `argument` to the handler as posted, so
   * this hook unwraps the documented shape before dispatch.
   */
  override onFunctionCall(name: string, args: Json, raw: Json): Hook {
    const parsed = args["parsed"];
    if (!Array.isArray(parsed)) return undefined;
    const tool = this.getTools().find((t) => t.name === name);
    return tool ? tool.execute((parsed[0] ?? {}) as Json, raw) : undefined;
  }
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  for (const name of ["SWML_BASIC_AUTH_USER", "SWML_BASIC_AUTH_PASSWORD"]) {
    if (!process.env[name]) throw new Error(`${name} is required; see .env.example`);
  }
  new AbsenceLine().serve({ port: Number(process.env["PORT"] ?? 3000) });
}

Run it

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

The TypeScript surface is the same agent with defineTool, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start

Point a number’s SWML webhook at https://<user>:<password>@<your-host>/absence/ and call it. Give the reason first, then the date, then your name, and ask it to submit after each one.

Verify it

No network, no account.

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

The verifier renders the document, then runs the handlers in a scrambled order, threading global_data between calls the way the platform does. It asserts the following.

both tools render; the field enum equals the checklist and submit_report has no parameters
reason first, with stray spaces: the trimmed value is written, and the response names the two fields still needed
submit with two fields missing is refused with exactly those two, and writes nothing
an optional note, sent as a number, is recorded as text and does not shorten the missing list
the date next: one field still needed, and the details object now holds all three
an unknown field, the prototype name constructor, and an empty value are refused with a typed state and no action
the name last: the response says everything required is in; submit then files ABS-1001 and writes report_id
a second submit answers ALREADY_FILED with the reference, writes nothing, and the report list still holds one
the TypeScript surface, through its own /swaig route with the documented argument shape, gives the same twelve responses and actions

Report an issue