# Handlers

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

Source: https://docs.vlayers.ai/get-started/concepts/handlers

Kind: Concept

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.](https://docs.vlayers.ai/portal-media/concepts/handlers.svg)

*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.

| 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](https://docs.vlayers.ai/developers/sdks/voice-agents): every handler, with examples.
- [Call lifecycle](https://docs.vlayers.ai/get-started/concepts/call-lifecycle): where in a call each one runs.
