代码工具

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

概述

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

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

工作原理

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

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}!` };
};

返回的值会成为工具结果，传回给智能体、显示在对话转录文本中，还可用于动态变量赋值。

ctx 对象

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

配置参数

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

配置上下文对象

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

网络访问

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

执行限制

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

测试代码

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

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

指南

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

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` };
};

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.

身份验证示例

使用密钥调用 API

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

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 映射为已配置的身份验证连接。引用的值是占位符：真实凭据会在出站时替换至标头中，代码永远无法看到它。

最佳实践

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

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

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

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

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

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

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

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

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

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

LLM 选择

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