# Lifecycle hooks

> A **lifecycle hook** runs one of your workflows at a moment you pick.

A **lifecycle hook** runs one of your workflows at a moment you pick.

## When to use a hook

| | When it runs | Use it for |
|---|---|---|
| **Hook** | Every time, at the moment you pick. | What must always happen: a lookup, a check, a log. |
| **Tool** | When the agent decides it needs the tool. | Actions that need the agent's judgment. |
| **Flow** | In the order of the flow's steps. | A procedure with a fixed order. |

If a variable's value decides whether a tool may run, use [Available when](../agents/single-agents.md#tool-guards) instead of a hook.

## Hooks reference

Hooks are listed in the order they run.

| Hook | Set on | When it runs | Common use |
|---|---|---|---|
| **On session start** | Assistant | Once, at the start of each conversation. | Look up the customer in your CRM. |
| **On user message** | Assistant | Each time the user sends a message, before any agent answers. | Block abuse. |
| **On agent start** | Agent | When this agent takes over the conversation. | Load the customer's orders. |
| **On user message** | Agent, Agent node | Each time this agent gets a message, before it replies. | Answer a common question with a fixed reply. |
| **Before tool call** | Tool | Each time the agent calls this tool, before the tool runs. | Check an OTP or fetch an access token. |
| **On tool success** | Tool | After the tool succeeds. | Show a confirmation card. |
| **On tool error** | Tool | When the tool fails or times out. | Alert your team and hand off. |
| **On turn end** | Agent, Agent node, assistant | After the reply goes out. | Send collected data to your CRM. |
| **On turn error** | Assistant | When something goes wrong in the turn. | Tell the user what went wrong, in your words. |
| **On call end** | Assistant | Once, when a voice call ends. | Save the call outcome. |

## Set up a hook

### On the assistant

1. Go to **AI agents → Configuration → Lifecycle hooks**.
2. On the hook you want, click **+ Add workflow** and pick the workflow.
3. Click **Save**.

![Configuration → Lifecycle hooks, with On session start running "Look up customer in CRM", On user message running "Block abuse and end turn", and On turn end running "Log conversation outcome"](https://cdn.yellowmessenger.com/docs/v3/ct/lifecycle-hooks-01.png)

Click a hook to open it. In the hook, you can:

- Turn it off with the **Enabled** switch.
- Save the workflow's result with **+ Save result to a variable**, where available.
- Add a condition with **+ Run only when…**, where available.
- Remove it with **Remove**. The workflow is not deleted.

![The On session start hook opened, with the workflow "Look up customer in CRM" picked and the Save result to a variable and Run only when… buttons below it](https://cdn.yellowmessenger.com/docs/v3/ct/lifecycle-hooks-02.png)

### On an agent

1. Open the agent, for example **Order Support**.
2. Next to **Lifecycle hooks**, click **+** and pick the hook, for example **On agent start**.
3. Pick the workflow, for example **Load customer orders**.
4. Save the agent.

![The Order Support agent, with a Lifecycle hooks section where On agent start runs "Load customer orders"](https://cdn.yellowmessenger.com/docs/v3/ct/lifecycle-hooks-03.png)

For an Agent node in a multi agent, open the node on the canvas and use its **Lifecycle hooks** section.

### On a tool {#before-tool-call}

1. Open the agent and click the tool's chip, for example **Issue refund**.
2. Under **Hooks**, click **+ Add tool hook** and pick **Before tool call**, **On tool success** or **On tool error**.
3. Pick the workflow, for example **Verify OTP before refund**.
4. Save the agent.

![The Issue refund tool's settings, with three hooks: Before tool call runs "Verify OTP before refund" with "Skip the tool if the workflow fails" ticked, On tool success runs "Confirm refund to customer", and On tool error runs "Escalate failed refund"](https://cdn.yellowmessenger.com/docs/v3/ct/lifecycle-hooks-04.png)

**Before tool call** has the checkbox **Skip the tool if the workflow fails**. It is selected by default. If the workflow ends in **Failure**, returns an error or times out, the tool does not run. The agent tells the user why.

## What a hook workflow can do

A hook workflow can send messages, save variables and call your systems. Before the reply is sent, it can also end the turn or transfer the user to another agent. See [How the workflow ends](../tools/workflows.md#how-a-workflow-ends).

## Examples

### Greet a known customer

1. On the assistant, set **On session start** to **Look up customer in CRM**.
2. In the workflow, find the customer by phone number and send "Hi Priya, welcome back."
3. End the workflow with **Continue**. The agent then answers if the user's first message is a question.

### Block abuse before the agent answers

1. On the assistant, set **On user message** to **Block abuse and end turn**.
2. In the workflow, check the message. If it is abusive, send a fixed reply and **End the turn**.
3. Otherwise, end with **Continue**. The agent answers as usual.

Keep this workflow fast. The reply is sent only after it finishes.

### Verify an OTP before a refund

1. On **Order Support**, open **Issue refund** and add **Before tool call** → **Verify OTP before refund**.
2. In the workflow, check `otpVerified`. If it is not true, end on a **Failure** output with the reason "OTP not verified".

### Hand off when a refund fails

1. On **Issue refund**, add **On tool error** → **Escalate failed refund**.
2. In the workflow, alert your team. Then end on **Transfer to agent → Returns** with a handoff note.

### Load context once for every agent {#seeding-context}

In **On session start**, look up the customer once and save the result to a **global** variable, such as `customer`. Every agent can read this variable, so no agent needs its own lookup tool. See [memory scopes](memory.md#scopes).

## Limitations

- **On turn end cannot change the reply.** The reply is already sent.
- **On call end applies to voice only.** Its messages are not sent, because the call has ended.

## Test your hooks

In the [Testing Lab](../../test-debug/index.md), send a message and trigger the tool. Then check that each hook ran.
