AIAgent
AIAgentAction hands the answered call to a Sautikit AI agent, expanding inline so a Say or Play prologue may precede it in the same response. It must be
AIAgentAction hands the answered call to a Sautikit AI agent, expanding inline so a Say or Play prologue may precede it in the same response. It must be the final action: nothing runs after the leg is forked.
| Parameter | Type | JSON key | Required | Description |
|---|---|---|---|---|
AgentID | string | agentId | Yes | AgentID is the workspace-scoped agent UUID. Required. There is deliberately no name form: agent names have no uniqueness constraint, so a name could resolve to several agents. The workspace is always taken from the dialled number, never from this document. |
Revision | int | revision | No | Revision pins a published revision. 0 runs the agent's current one. |
Variables | map[string]string | variables | No | Variables are appended to the agent's prompt as a labelled data block. They are framed as caller-supplied values rather than spliced into instruction text, so a variable containing something like "ignore your instructions" reads as a value the model was handed. Keys are sorted, so the same variables always produce the same prompt. |
Handover | *AIAgentHandover | handover | No | Handover configures where the caller goes when the agent hands back. Optional; without it the call returns to the number's own handover configuration, and failing that ends. |
OnUnavailable | string | onUnavailable | No | OnUnavailable is taken when the agent cannot be reached at all: no published revision, no free seat, staging failure, or an unconfigured bridge. One of "hangup" (default), "voicemail", "forward", "callback". Unlike number-level routing there is no "fall through to normal routing" left at this point in a call, so without a fallback every failure would be a dropped call. |
Voicemail | *AIAgentVoicemail | voicemail | No | Voicemail supplies the target when OnUnavailable is "voicemail". Kept beside Forward rather than nested under Handover because the two fire for different reasons: this one when the agent could not be reached at all, Handover when the agent finished and handed back. |
Forward | *AIAgentForward | forward | No | Forward supplies the destination pool when OnUnavailable is "forward". |
import { sauti } from "@sautikit/node";
res.json(sauti.voiceResponse([
sauti.say("Connecting you to our assistant."),
sauti.aiAgent("3f1b8c22-6a4e-4f1a-9c77-5b2e0d9a4411", {
handover: {
forward: {
destinations: ["+254712345678"],
voicemail: { greetingText: "Sorry we missed you — leave a message after the tone." },
},
},
}),
]));{
"actions": [
{
"say": {
"text": "Connecting you to our assistant."
}
},
{
"aiAgent": {
"agentId": "3f1b8c22-6a4e-4f1a-9c77-5b2e0d9a4411",
"handover": {
"forward": {
"destinations": [
"+254712345678"
],
"voicemail": {
"greetingText": "Sorry we missed you — leave a message after the tone."
}
}
}
}
}
]
}