> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# handoff_settings

> Auto-escalation rules that hand a conversation to a human channel based on keywords or consecutive unresolved turns.

# `handoff_settings` — Handoff settings

Auto-escalation rules that hand a conversation to a human channel based on keywords or consecutive unresolved turns.

**Section key** `handoff_settings` · **Shape** object · **Tier** Pro and up (free trial includes it)\
**Edit in the dashboard:** [Human handoff page](/sidebar-menu/human-handoff)\
**Related:** [Handoff guide](/sidebar-menu/human-handoff)

## Fields

| Field              | Required | Type            | Allowed values / constraints | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------ | -------- | --------------- | ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_escalation`  | no       | object          | —                            | —       | Automatic escalation trigger configuration. Item fields below.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `required_inbound` | no       | array of object | max 20 items                 | —       | Fields a calling agent MUST supply when handing off TO this agent (its inbound-input contract). The caller fills them via handoff\_request's `provided_input`; the values arrive in the handoff envelope. Enforced as a BLOCKING gate before this agent starts: a sibling handoff missing a required field is rejected back to the caller, and an external A2A handoff parks in `input-required` with this schema. Same field shape as a handoff `expected_return` contract, but the opposite direction. Item fields below. |

### `auto_escalation` fields

Automatic escalation trigger configuration.

| Field     | Required | Type            | Allowed values / constraints | Default | Description                                                                    |
| --------- | -------- | --------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------ |
| `enabled` | no       | boolean         | —                            | —       | Master switch for auto-escalation rules.                                       |
| `rules`   | no       | array of object | —                            | —       | Ordered list of escalation rules. First matching rule wins. Item fields below. |

### `required_inbound` items

Fields a calling agent MUST supply when handing off TO this agent (its inbound-input contract). The caller fills them via handoff\_request's `provided_input`; the values arrive in the handoff envelope. Enforced as a BLOCKING gate before this agent starts: a sibling handoff missing a required field is rejected back to the caller, and an external A2A handoff parks in `input-required` with this schema. Same field shape as a handoff `expected_return` contract, but the opposite direction.

| Field         | Required | Type            | Allowed values / constraints                                             | Default | Description                                                                                    |
| ------------- | -------- | --------------- | ------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------- |
| `name`        | **yes**  | string          | —                                                                        | —       | Machine identifier (letters/digits/underscores) — the key the caller puts in `provided_input`. |
| `type`        | **yes**  | enum            | one of `string`, `multiline`, `number`, `boolean`, `enum`, `date`, `url` | —       | Field type — drives value coercion and validation.                                             |
| `label`       | no       | string          | —                                                                        | —       | Human-readable label. Defaults to `name`.                                                      |
| `description` | no       | string          | —                                                                        | —       | What this field is for — shown to the calling agent.                                           |
| `required`    | no       | boolean         | —                                                                        | —       | When true, the handoff is BLOCKED until the caller supplies this field.                        |
| `enum_values` | no       | array of string | —                                                                        | —       | For type='enum': the allowed values.                                                           |
| `placeholder` | no       | string          | —                                                                        | —       | Example value shown to the caller.                                                             |

### `auto_escalation.rules` items

Ordered list of escalation rules. First matching rule wins.

| Field        | Required | Type            | Allowed values / constraints                     | Default | Description                                                                                 |
| ------------ | -------- | --------------- | ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| `trigger`    | **yes**  | enum            | one of `keyword`, `consecutive_unresolved_turns` | —       | What causes this rule to fire.                                                              |
| `channel_id` | **yes**  | string          | —                                                | —       | ID of the handoff\_channel row to route to when this rule fires.                            |
| `patterns`   | no       | array of string | —                                                | —       | For trigger='keyword': list of keywords/phrases that trigger escalation.                    |
| `threshold`  | no       | integer         | —                                                | —       | For trigger='consecutive\_unresolved\_turns': number of unresolved turns before escalating. |
| `enabled`    | no       | boolean         | —                                                | —       | Whether this rule is active. Missing or true = active; false = skipped at evaluation time.  |