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?
Awaited: the call waits
These return something the call needs, so each has a deadline. A slow or crashed worker never hangs a call.
| Kind | What it is | Deadline |
|---|---|---|
| Tool | Code the model can call (defineTool). What it returns goes back to the model. | 10 s by default; set 100 ms to 30 s |
| Process hooks | process.onField, process.onComplete, completeWhen while collecting fields. | 2 s, 5 s, 2 s |
| Triggers | A 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 hook | The handoff briefing, and endCall.onEnd, which can take over teardown. | 2 s each |
| Brain turn | onQuery 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:
| Call | Does |
|---|---|
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:
| Code | Meaning |
|---|---|
guard_denied | The agent did not declare that capability, or the destination is not allowed. |
scope_closed | The call ended, or the invocation was cancelled or timed out. |
unsupported_on_channel | For 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
- Voice agents in code: every handler, with examples.
- Call lifecycle: where in a call each one runs.