Concept

Handlers

Which of your code runs during a call, which ones the call waits for, and what each can do.

Code you write for an agent comes in a few kinds. They differ in one way that matters: does the call wait for it?

One call at the top splits into two boxes. Awaited code, which the call waits for within a deadline: tools, process hooks, trigger conditions and actions, the handoff briefing and the end-of-call hook, and brain turns. Notifications, which the call never waits for: onUtterance, onFieldCaptured, onDtmf and onCallEnd, delivered at least once and in call order.
Awaited code has a deadline. Notifications never hold the call.

Awaited: the call waits

These return something the call needs, so each has a deadline. A slow or crashed worker never hangs a call.

KindWhat it isDeadline
ToolCode the model can call (defineTool). What it returns goes back to the model.10 s by default; set 100 ms to 30 s
Process hooksprocess.onField, process.onComplete, completeWhen while collecting fields.2 s, 5 s, 2 s
TriggersA condition and an action that act before the model replies, for example hand off on a word.1 s for a condition, 2 s for an action
Briefing and end hookThe handoff briefing, and endCall.onEnd, which can take over teardown.2 s each
Brain turnonQuery or a framework brain: your code writes the reply.The first words must come within a deadline you can set (brain.firstTokenDeadlineMs)

When one is late, the call carries on without it: a tool gives the model a failed result, a trigger lets the turn continue, a late briefing is replaced by the platform's.

Notifications: the call never waits

onUtterance, onFieldCaptured, onDtmf and onCallEnd tell you something happened. They are delivered at least once, in call order. That means a handler can run twice for the same event, so make what it does safe to repeat: write by a key you choose, or check before you act. Keep call state in ctx.metadata or ctx.memory, not in worker memory, because two invocations of one call can land on two processes.

What ctx can do

Inside a handler, ctx can speak and steer the call:

CallDoes
ctx.say(text)Speak a line.
ctx.respond(instructions?)Let the model write the next reply.
ctx.ask(question)Ask and wait for the answer (voice only).
ctx.handoff(to, opts)Transfer to a person.
ctx.endCall(opts)Hang up.

Each action is checked against the capabilities the agent declared. An action that is not allowed is refused with a named code, never silently dropped:

CodeMeaning
guard_deniedThe agent did not declare that capability, or the destination is not allowed.
scope_closedThe call ended, or the invocation was cancelled or timed out.
unsupported_on_channelFor example ctx.ask on a text conversation.

Handlers receive the caller's number and words as placeholders unless a tool sets sendRealValues: true, and each release is recorded.

Next

On this page