> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 更新状态

## 概述

**更新状态**工具可让智能体在对话进行期间设置一个或多个[动态变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)。与其他[系统工具](/docs/zh/eleven-agents/customization/tools/system-tools)一样，它只会更改对话内部状态，绝不会调用外部 API 或客户端函数。

可在通话过程中记录信息，例如标记对话是否应升级、存储用户提供的值，或计算基于其他动态变量得出的值。

如果要在[工作流](/docs/zh/eleven-agents/customization/agent-workflows)的固定节点应用状态更新，而不是在 LLM 调用工具时更新，请使用[更新状态节点](/docs/zh/eleven-agents/customization/agent-workflows#update-state-node)。它支持相同的状态更新。

## 功能

* **每次调用可更新多个变量**：单次工具调用最多可同时为 50 个动态变量赋值。
* **基于表达式的值**：每个值都是表达式的结果，表达式可组合常量、现有动态变量、LLM 从对话中提取的值和运算符。
* **仅在需要时由 LLM 提取**：工具只会让 LLM 为需要提取参数的更新提取参数。完全由常量和/或现有动态变量构成的更新不会向函数调用添加任何参数。
* **立即可用**：工具运行后，更新后的动态变量可供对话其余部分使用，后续提示词、其他工具调用和覆盖设置都能像引用其他动态变量一样引用它们。

## 工作原理

每项状态更新都会将表达式结果赋给一个动态变量：

```text
variable_name = expression
```

表达式可为以下类型之一，也可相互嵌套以构建更复杂的逻辑：

| 类型       | 说明                                                 |
| -------- | -------------------------------------------------- |
| 常量       | 固定的字符串、数字、布尔值或 null 值。                             |
| 动态变量     | 另一个动态变量的当前值。                                       |
| LLM 提取的值 | LLM 根据对话推断的值，符合你定义的类型（字符串、数字或布尔值）。                 |
| 逻辑运算符    | `and`、`or` 或结合其他表达式的条件表达式（`if` / `then` / `else`）。 |
| 比较运算符    | `=`、`≠`、`>`、`<`、`≥`、`≤`，用于比较两个表达式。                 |
| 算术运算符    | `+`、`-`、`×`、`÷`，用于组合两个数字表达式（对于 `+`，也可以是字符串表达式）。    |

例如，如果 LLM 判断用户感到沮丧，或 `retry_count` 动态变量已大于 3，以下状态更新会将 `should_escalate` 设为 `true`：

```text
should_escalate = (llm: "User sounds frustrated with the conversation") OR (retry_count > 3)
```

> **Note**
>
> 如果状态更新求值失败，例如除以零，工具调用将返回错误，且该次调用中的所有更新都不会应用。

## 配置

### 第 1 步：添加工具

前往智能体配置页面。在 **工具**部分，点击 **添加工具**，然后选择 **更新状态**。

### 第 2 步：定义状态更新

为每项状态更新提供以下内容：

* **变量名称**：要赋值的动态变量。
* **表达式**：要赋的值，由上述值类型和运算符类型构建。可嵌套值以构建更复杂的表达式。
* **必填**：关闭后，LLM 可以省略此更新所依赖的值。该更新会被跳过，变量将保留当前值。

单个工具最多可定义 50 项状态更新。

### 第 3 步：配置说明（可选）

可提供自定义说明，指导 LLM 何时调用该工具。如留空，将使用针对此工具优化的默认说明。

## 使用场景

* **升级标记**：设置供下游系统或业务规则检查的动态变量（例如 `should_escalate`），如 [Genesys 集成指南](/docs/zh/eleven-agents/customization/integrations/genesys#configure-escalation)所示。
* **记录提取的信息**：将用户提供的值（订单号、偏好设置、选择的部门）存为动态变量，供后续对话使用。
* **派生值**：根据其他动态变量计算值，例如递增计数器，或将两个变量合并为一个。

**用途**：让智能体根据对话更新一个或多个动态变量，无需调用外部 API。

**触发条件**：LLM 应在以下情况调用此工具：

* 对话提供了应记录的信息（例如升级标记、选定选项、用户提供的值）
* 已配置的状态更新依赖于 LLM 必须从对话中判断或提取的值

**参数**：

函数参数取决于工具的配置。每项使用 LLM 提取值的已配置状态更新，都会在架构中添加一个属性；该属性以此更新的动态变量命名，类型为 `string`、`number` 或 `boolean`。仅由常量或其他动态变量构建的状态更新不会添加任何参数。

**函数调用格式**：

```json
{
  "type": "function",
  "function": {
    "name": "update_state",
    "arguments": "{\"should_escalate\": true}"
  }
}
```

**实现方式**：智能体会使用提取出的参数和当前对话动态变量评估每个已配置表达式，然后将结果赋值给对应的动态变量。不会发出外部请求。

## 常见问题

#### 这个工具会进行外部调用吗？

不会。与所有系统工具一样，更新状态只会修改对话内部状态，不会调用外部 API 或客户端函数。

#### 调用此工具是否始终需要 LLM 提取参数？

不需要。只有状态更新的表达式包含 LLM 提取的值时，工具才会让 LLM 提取参数。如果所有配置的更新都由常量和/或现有动态变量构成，函数调用将不需要参数。

#### 此工具设置的动态变量可在哪里使用？

可在任何支持动态变量的位置使用：系统提示词、首条消息、工具参数和标头，以及覆盖设置。详情请参阅[动态 变量](/docs/zh/eleven-agents/customization/personalization/dynamic-variables)。

#### 能否通过 API 配置此工具？

目前可通过智能体控制台配置更新状态。暂不支持 API 和 SDK。