Patterns

Each tree below is a complete, valid operations array. Declare the {{args.…}} it reads in the tool’s json_schema and create the {{secrets.…}} it reads before publishing.

Lookup then answer

The caller asks for something you fetch; the agent answers from it. The say covers the HTTP latency, and the http is silent so the model sees only the two values.

[
  { "kind": "say", "config": { "text": "One moment, let me pull that up." } },
  {
    "kind": "http",
    "config": {
      "method": "GET",
      "url": "https://api.example.com/accounts/{{args.account_id}}/balance",
      "headers": { "Authorization": "Bearer {{secrets.BILLING_API_KEY}}" },
      "timeout": 10
    },
    "silent": true,
    "publish_fields": [
      { "path": "balance_due", "key": "balance", "store": "tooldata" },
      { "path": "due_date", "store": "tooldata" }
    ]
  },
  {
    "kind": "generate_reply",
    "config": { "instructions": "Tell the caller their balance is {{tooldata.balance}}, due on {{tooldata.due_date}}. Then ask if they want to pay now." }
  }
]

If the wording never varies, replace the generate_reply with a say and save a model call.

Book then confirm

An irreversible action whose outcome the caller must hear. The confirmation is a say so the reference is read exactly, and the reference goes to userdata so the rest of the call knows it.

[
  { "kind": "say", "config": { "text": "Let me get that booked for you." } },
  {
    "kind": "http",
    "config": {
      "method": "POST",
      "url": "https://api.example.com/bookings",
      "headers": {
        "Authorization": "Bearer {{secrets.BOOKING_API_KEY}}",
        "Idempotency-Key": "{{args.slot_id}}"
      },
      "body": { "slot_id": "{{args.slot_id}}", "phone": "{{system_vars.human_phone_number}}" },
      "timeout": 15
    },
    "silent": true,
    "publish_fields": [
      { "path": "confirmed", "store": "tooldata" },
      { "path": "reference", "key": "booking_reference", "store": "userdata" }
    ]
  },
  {
    "kind": "if",
    "config": { "left": "{{tooldata.confirmed}}", "op": "eq", "right": true },
    "then": [
      { "kind": "say", "config": { "text": "You're booked. Your reference is {{userdata.booking_reference}}." } }
    ],
    "else": [
      {
        "kind": "generate_reply",
        "config": { "instructions": "Tell the caller that slot could not be booked and ask whether another time would work." }
      }
    ]
  }
]

Escalation to a person

One tool per destination, no arguments, with disable_interruptions: true on the tool so a caller talking over the ringback cannot lose the outcome. The tool’s description is the escalation policy: say exactly when to use it and when not to. See transfer for mode, on_failure and what the caller hears.

[
  { "kind": "say", "config": { "text": "Putting you through to the support team now." } },
  {
    "kind": "transfer",
    "config": { "destination": "+14155550142", "mode": "cold", "on_failure": "continue" }
  }
]

Guard then continue

Nothing can follow an if, so an early exit puts the whole rest of the flow inside one branch.

[
  {
    "kind": "if",
    "config": { "left": "{{userdata.account_id}}", "op": "exists" },
    "then": [
      {
        "kind": "http",
        "config": {
          "method": "POST",
          "url": "https://api.example.com/accounts/{{userdata.account_id}}/tickets",
          "headers": { "Authorization": "Bearer {{secrets.SUPPORT_API_KEY}}" },
          "body": { "summary": "{{args.summary}}" },
          "timeout": 15
        },
        "silent": true,
        "publish_fields": [{ "path": "ticket_number", "key": "ticket", "store": "tooldata" }]
      },
      { "kind": "say", "config": { "text": "I've raised ticket {{tooldata.ticket}} for you." } }
    ],
    "else": [
      {
        "kind": "generate_reply",
        "config": { "instructions": "Say you need to find their account first, and ask for the email address on it." }
      }
    ]
  }
]

Business hours

Time decisions belong in a code operation: {{system_vars.time}} is a spoken string and gt/lt refuse it. The script names its zone, so it works whatever the agent’s timezone; replace Asia/Kolkata with your own.

[
  {
    "kind": "code",
    "config": {
      "source_ts": "export default async function handler(input) {\n  const parts = new Intl.DateTimeFormat(\"en-GB\", {\n    timeZone: \"Asia/Kolkata\",\n    weekday: \"short\",\n    hour: \"numeric\",\n    hour12: false,\n  }).formatToParts(new Date());\n  const weekday = parts.find((p) => p.type === \"weekday\").value;\n  const hour = Number(parts.find((p) => p.type === \"hour\").value);\n  const open = weekday !== \"Sat\" && weekday !== \"Sun\" && hour >= 9 && hour < 18;\n  return { open: open ? \"yes\" : \"no\" };\n}\n",
      "timeout": 5
    },
    "silent": true,
    "publish_fields": [{ "path": "open", "store": "tooldata" }]
  },
  {
    "kind": "if",
    "config": { "left": "{{tooldata.open}}", "op": "eq", "right": "yes" },
    "then": [
      { "kind": "say", "config": { "text": "The team is in, let me put you through." } },
      { "kind": "transfer", "config": { "destination": "+14155550142", "mode": "cold" } }
    ],
    "else": [
      {
        "kind": "generate_reply",
        "config": { "instructions": "Say the office is closed, open weekdays 9am to 6pm, and offer to take a message." }
      }
    ]
  }
]

The script, readable:

export default async function handler(input) {
  const parts = new Intl.DateTimeFormat("en-GB", {
    timeZone: "Asia/Kolkata",
    weekday: "short",
    hour: "numeric",
    hour12: false,
  }).formatToParts(new Date());
  const weekday = parts.find((p) => p.type === "weekday").value;
  const hour = Number(parts.find((p) => p.type === "hour").value);
  const open = weekday !== "Sat" && weekday !== "Sun" && hour >= 9 && hour < 18;
  return { open: open ? "yes" : "no" };
}

It returns "yes"/"no" rather than a boolean so the if stays editable in the dashboard, whose fields are plain text.

Silent logging

Record something without the caller waiting or the model reacting. background_execution sends the request and moves on; nothing is published and a failure only reaches our logs. A tool made only of background operations is silent, so the model says nothing about it.

[
  {
    "kind": "http",
    "config": {
      "method": "POST",
      "url": "https://api.example.com/events",
      "headers": { "Authorization": "Bearer {{secrets.ANALYTICS_API_KEY}}" },
      "body": { "event": "{{args.event}}", "phone": "{{system_vars.human_phone_number}}", "at": "{{system_vars.now}}" }
    },
    "background_execution": true
  }
]

A fully silent tool means the agent says nothing in the turn the model called it. That suits a lifecycle hook; if the model calls it while the caller waits for an answer, add a generate_reply.

The operation tree

Kinds, on_error and the branch rule.

Testing and publishing

Run a pattern against your endpoints before publishing.

Get started

Build

Guides

Lookup then answer

Book then confirm

Escalation to a person

Guard then continue

Business hours

Silent logging

Next

The operation tree

Testing and publishing

​Lookup then answer

​Book then confirm

​Escalation to a person

​Guard then continue

​Business hours

​Silent logging

​Next

The operation tree

Testing and publishing

Lookup then answer

Book then confirm

Escalation to a person

Guard then continue

Business hours

Silent logging

Next