动态变量

动态变量可将运行时值注入智能体的消息、系统提示词和工具中。无需创建多个智能体，即可使用用户专属数据个性化每次对话。

概览

动态变量可集成到智能体的多个部分：

• 使用 系统提示词 自定义行为和上下文
• 使用 首条消息 个性化问候语
• 使用 工具参数和标头 传递用户专属数据

以下是动态变量的一些常见用途：

• 使用用户名 个性化问候语
• 在回复中 包含账户详情
• 向工具调用 传递数据
• 根据订阅套餐 自定义行为
• 访问对话 ID 或通话时长等 系统信息

动态变量可包含任意 JSON 值：

将列表或对象插入提示词、URL 或其他文本模板时，会以其 JSON 文本形式插入。绑定到列表变量的工具参数会接收列表本身。

对话详情 API 和通话后 webhook会按原样返回动态变量，包括下方的 system__ 变量。将 dynamic_variables 解析为 JSON 值映射。请勿拒绝不认识的键或值类型，因为可能会新增 system__ 变量。

系统动态变量

无需运行时配置，智能体即可在每次对话中访问内置的 system__* 变量。这些变量带有保留的 system__ 命名空间前缀，并会随对话进行自动更新。自定义动态变量不能使用 system__ 前缀，也不能覆盖系统变量。

标有 † 的变量会在轮次之间变化。将其放入提示词文本可能会阻止提示词缓存；替代方案请参阅最佳实践。

智能体和对话身份

时间和时区

电话和消息

这些变量会在适用的电话和消息渠道中填充：

每轮对话状态

对话历史记录格式

system__conversation_history 变量包含以下结构的 JSON 对象：

{
  "x-elevenlabs-history": true,
  "entries": [
    { "role": "user", "message": "Hello" },
    { "role": "agent", "message": "Hi, how can I help?" },
    {
      "role": "agent",
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
    },
    {
      "role": "tool",
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
    }
  ]
}

每个条目都包含一个 role（"user"、"agent" 或 "tool"）以及以下其中一项：

• message：该轮的文本内容
• tool_requests：智能体发起的工具调用数组，包含已解析的参数值
• tool_results：工具响应数组

如果工具结果或参数包含嵌套对话历史记录，将被脱敏为占位符（如 [conversation_history (5 turns)]），以避免无限递归展开。

此变量适合将对话上下文传递给工具（如 webhook 或自定义 LLM），也可在交接期间将对话历史记录包含在子智能体提示词中。

上传文件

system__uploaded_file_ids 会列出用户在聊天中附加的文件 ID，例如在小组件或 WhatsApp 中。它会在每轮更新，因此智能体调用工具时，当前消息中附加的文件已在列表中。

要在对话仍处于活动状态时处理附件，请将此列表与 system__conversation_id 一起绑定到服务器工具的数组参数。如果智能体在用户附加文件前调用工具，参数将接收空列表。

"request_body_schema": {
  "type": "object",
  "required": ["file_ids", "conversation_id"],
  "properties": {
    "file_ids": {
      "type": "array",
      "description": "",
      "dynamic_variable": "system__uploaded_file_ids",
      "items": { "type": "string", "description": "File ID" }
    },
    "conversation_id": {
      "type": "string",
      "dynamic_variable": "system__conversation_id"
    }
  }
}

然后，服务器会使用 API 密钥下载每个文件：

curl https://api.elevenlabs.io/v1/convai/conversations/$CONVERSATION_ID/files/$FILE_ID \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -o attachment

响应为原始文件，并带有其 Content-Type（例如 image/jpeg 或 application/pdf）。不属于该对话的文件 ID 会返回 404。列表中的最后一个 ID 是最新上传的文件。

私密动态变量

私密动态变量的填充方式与普通动态变量相同，但会告知 ElevenAgents，它们只能用于动态变量标头，绝不能作为智能体系统提示词或首条消息的一部分发送给 LLM 提供商。

对于不应发送给 LLM 的身份验证令牌或私有 ID，请使用私密动态变量。要创建私密动态变量，请为动态变量添加 secret__ 前缀。

从工具更新动态变量

如果工具调用返回有效的 JSON 对象，即可创建或更新动态变量。使用点表示法设置对象路径，以指定应提取的内容。若字段或路径不存在，则不会更新任何内容。

响应对象和点表示法示例：

• Status 对应路径：response.status
• users 数组中第一个用户的电子邮箱对应路径：response.users.0.email

{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}

要将动态变量更新为第一个用户的电子邮箱，请按如下方式设置赋值。

赋值在每个 webhook 工具中配置；请参阅 API 参考文档中的工具赋值。

指南

前提条件：

• 一个 ElevenLabs 账户
• 已配置的 ElevenAgents 智能体（按照快速入门创建）

import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)
dynamic_vars = {
    "user_name": "Angelo",
}
config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)
conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment the below if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
)
conversation.start_session()
signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

公开对话页面集成

公开对话页面支持通过 URL 参数传递动态变量，因此分享智能体链接时可个性化对话。这尤其适合在网站、电子邮件或营销活动中嵌入个性化智能体。

URL 参数方法

可通过两种方法向公开对话页面传递动态变量：

方法 1：Base64 编码的 JSON

使用 vars 参数将变量作为 Base64 编码的 JSON 对象传递：

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

vars 参数包含 Base64 编码的 JSON：

{ "user_name": "John", "account_type": "premium" }

方法 2：单独的查询参数

使用带 var_ 前缀的查询参数传递变量：

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium

参数优先级

同时使用两种方法时，单独的 var_ 参数优先于 Base64 编码变量，以避免冲突：

https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John

在此示例中，user_name 将为 "John"（来自 var_user_name），而非 "Jane"（来自 Base64 编码的 vars）。

实现示例

// Method 1: Base64-encoded JSON
function generateTalkToURL(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const encodedVars = btoa(JSON.stringify(variables));
  return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
}
// Method 2: Individual parameters
function generateTalkToURLWithParams(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const params = new URLSearchParams({ agent_id: agentId });
  Object.entries(variables).forEach(([key, value]) => {
    params.append(`var_${key}`, encodeURIComponent(value));
  });
  return `${baseURL}?${params.toString()}`;
}
// Usage
const variables = {
  user_name: "John Doe",
  account_type: "premium",
  session_id: "sess_123"
};
const urlMethod1 = generateTalkToURL("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
const urlMethod2 = generateTalkToURLWithParams("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);

最佳实践

故障排除