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

# 代码工具

**代码工具**让智能体能在沙盒化的服务端环境中运行自定义 JavaScript，无需自行搭建和托管 webhook 端点。在内置代码编辑器中编写一次逻辑后，智能体每次调用该工具时，ElevenLabs 都会执行它。

> **Note**
>
> 这是仅限企业版的功能。

## 概述

代码工具是在智能体调用时运行的 JavaScript 函数。你需要编写完整函数体，因此工具可根据任务需求执行任意复杂度的操作：

* **自定义计算**：仅使用工具调用参数应用定价规则、单位换算、评分逻辑或日期计算。无需网络访问。
* **调用外部 API**：从允许列表中的域名执行 `fetch`，并将工作区密钥和身份验证连接注入函数上下文。
* **整合多个来源**：调用两个或三个 API，并在返回单一答案前合并、比较或核对结果。
* **条件分支**：根据工具调用参数运行不同逻辑，无需为每个分支单独创建工具。
* **重构数据**：返回希望智能体看到的确切结构，而非原始上游响应。

> **Info**
>
> 对于无需自定义逻辑的单次外部 API 调用，[webhook 工具](/docs/zh/eleven-agents/customization/tools/webhook-tools)通常更容易设置。要在用户的浏览器或应用中触发操作，请改用[客户端 工具](/docs/zh/eleven-agents/customization/tools/client-tools)。

## 工作原理

代码是一个 JavaScript 模块，导出单个默认异步函数。该函数接收 `ctx` 对象并返回工具结果：

```javascript
export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;

  return { message: `Hello from ${city}!` };
};
```

返回的值会成为工具结果，传回给智能体、显示在对话转录文本中，还可用于[动态变量赋值](/docs/zh/eleven-agents/customization/tools/webhook-tools#tool-configuration)。

### `ctx` 对象

`ctx` 是工具在调用时可访问所有内容的入口。智能体提供的参数始终位于 `ctx.args`；密钥、配置值和身份验证连接均为可选项，仅当你在工具的 **上下文对象** 部分映射后才会出现。

| 属性                     | 说明                                                                                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx.args`             | 智能体提供的工具调用参数。                                                                                                                                                                       |
| `ctx.config`           | 已映射至该工具上下文的纯字符串变量。                                                                                                                                                                  |
| `ctx.secrets`          | 已映射至该工具上下文、用于请求标头的工作区密钥。原始密钥绝不会暴露给代码；注入仅在出站时发生，且仅限标头中。                                                                                                                              |
| `ctx.auth_connections` | 已映射至该工具上下文的已配置[身份验证连接](/docs/zh/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods)引用，用于 `X-With-Auth-Connection` 请求标头。底层凭据绝不会暴露给代码；注入仅在出站时发生，且仅限标头中。 |

> **Note**
>
> 智能体调用工具时，只有 `ctx.args` 对其可见。密钥、配置值和身份验证连接绝不会透露给智能体。

#### 配置参数

参数是智能体调用工具时提供的值，会出现在 `ctx.args` 中。可在工具配置表单的 **参数** 部分定义，也可在代码编辑器 **Params** 标签页的 **Define Params** 子标签页中定义。每个参数都需要数据类型、标识符和描述，智能体会根据描述从对话中确定正确值。代码会通过标识符读取该值，例如下方的 `ctx.args.appointment_datetime`。

![定义代码工具参数](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp)

#### 配置上下文对象

在工具的 **上下文对象** 部分添加密钥、配置值和身份验证连接。每个条目都需要类型和名称。面板会显示每个条目的准确访问器，例如下方的 `ctx.secrets.DEMO_KEY`。

![将工作区密钥映射到代码工具的上下文对象](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp)

### 网络访问

在沙盒中运行的代码只能访问工作区明确允许的域名。在工作区 **常规设置** 的 **代码工具允许的域名** 下，添加代码需要调用的域名。请求任何其他域名都会失败。

> **Warning**
>
> 编辑 **代码工具允许的域名** 列表需要工作区管理员权限。

### 执行限制

* **超时**：每次运行必须在工具配置的响应超时时间内完成，范围为 1 至 30 秒。
* **不支持外部包**：代码工具目前不支持 npm 依赖项。

### 测试代码

保存前，使用代码编辑器中的 **Run**，通过示例参数值执行代码：

* **Params** — 为工具定义的每个参数设置测试值。
* **Output** — 查看返回结果，或执行失败时的错误。
* **Logs** — 查看通过 `console.log`、`console.warn` 或 `console.error` 写入的内容，以及构建和执行耗时。

## 指南

本指南将创建一个代码工具，用于转换温度并返回友好的格式化字符串：

#### 创建代码工具

在智能体设置页面的 **Agent** 部分，选择 **Add Tool**。选择 **Code** 作为工具类型，然后设置名称和描述：

| 字段 | 值                   |
| -- | ------------------- |
| 名称 | convert_temperature |
| 描述 | 在摄氏度和华氏度之间转换温度      |

#### 定义参数

添加两个参数，让 LLM 知道需要提供什么：

| 数据类型   | 标识符       | 必填   | 描述                     |
| ------ | --------- | ---- | ---------------------- |
| number | value     | true | 要转换的温度值                |
| string | from_unit | true | 要转换的原始单位：`"C"` 或 `"F"` |

#### 编写代码

打开代码编辑器，并将默认源代码替换为：

```javascript
export default async (ctx) => {
  const { value, from_unit } = ctx.args;

  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }

  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};
```

保存前，使用 **Run** 和几个示例值（例如 `value: 100, from_unit: "C"`）确认输出。

#### 编排

更新智能体的系统提示词，让它知道何时调用该工具：

**`系统提示词`**

```plaintext 系统提示词
When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.
```

#### 测试

开始对话并尝试：

> *100 摄氏度等于多少华氏度？*

智能体应调用工具并读出转换后的值。

### 身份验证示例

**使用密钥调用 API**

```javascript
export default async (ctx) => {
  const { order_id } = ctx.args;

  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }

  return await response.json();
};
```

在工具的 **上下文对象** 部分，将 `EXAMPLE_API_KEY` 映射为工作区密钥，然后将 `api.example.com` 添加到 **代码工具允许的域名**，以允许请求出站。引用的值是占位符：真实密钥会在出站时替换至标头中，代码永远无法看到它。

**使用 OAuth 身份验证连接调用 API**

```javascript
export default async (ctx) => {
  const { customer_id } = ctx.args;

  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });

  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }

  return await response.json();
};
```

在工具的 **上下文对象** 部分，将 `EXAMPLE_CRM` 映射为已配置的[身份验证连接](/docs/zh/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods)。引用的值是占位符：真实凭据会在出站时替换至标头中，代码永远无法看到它。

## 最佳实践

#### 使用直观的工具名称和详细说明

如果发现助手没有调用正确的工具，可能需要更新工具名称和说明，让助手更清楚地理解何时应选择各个工具。避免使用缩写或首字母缩略词来简化工具和参数名称。

还可以详细说明应在何时调用工具。对于复杂工具，应为每个参数添加说明，帮助助手了解需要向用户询问哪些信息来收集该参数。

#### 使用直观的工具参数名称和详细说明

为工具参数使用清晰且描述性强的名称。适用时，请在说明中指定参数的预期格式（例如日期采用 YYYY-mm-dd 或 dd/mm/yy）。

#### 考虑在助手的系统提示词中提供有关如何及何时调用工具的补充信息

在系统提示词中提供清晰指示，可显著提高助手调用工具的准确性。例如，可使用以下指示引导助手：

```plaintext
Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.
```

为复杂场景提供上下文。例如：

```plaintext
Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.
```

#### LLM 选择

> **Warning**
>
> 使用工具时，建议选择 GPT 5.2、Gemini-2.5-Flash 或
> Claude Sonnet 4.5 等高智能模型，并避免使用 Gemini-2.0-Flash。

请注意，LLM 的选择会影响函数调用的成功率。某些 LLM 可能难以从对话中提取相关参数。