动态变量

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

概述

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

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

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

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

系统动态变量

智能体可访问以下自动提供的系统变量：

• system__agent_id - 发起对话的智能体唯一标识符（在整个对话期间保持不变）
• system__current_agent_id - 当前活跃智能体的唯一标识符（智能体转接后会更改）
• system__caller_id - 来电者电话号码（仅限语音通话）
• system__called_number - 目标电话号码（仅限语音通话）
• system__call_duration_secs - 通话时长，单位为秒
• system__time_utc - 当前 UTC 时间（ISO 格式）
• system__time - 指定时区的当前时间（人类可读格式，例如“Friday, 12:33 12 December 2025”）
• system__timezone - 用户提供的时区（必须对 tzinfo 有效）
• system__conversation_id - ElevenLabs 的唯一对话标识符
• system__call_sid - 通话 SID（仅限 twilio 通话）
• system__call_id - SIP 中继通话的唯一标识符（仅限 SIP 中继通话）
• system__agent_turns - 智能体在此次对话中进行的对话轮次数总计。
• system__current_agent_turns - 当前智能体进行的对话轮次数。对话转接至其他智能体时会重置。
• system__current_subagent_turns - 当前子智能体进行的对话轮次数。workflow 转换至其他节点时会重置。
• system__is_text_only - 如果对话以纯文本模式进行，则为 true；否则为 false。
• system__conversation_history - 当前对话历史记录的 JSON 序列化表示。在被引用时才会计算。请参阅下方格式详情。

系统变量：

• 无需运行时配置即可使用
• 以 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），或在交接期间将对话历史记录包含在子智能体提示词中。

密钥动态变量

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

建议将其用于不应发送给 LLM 的身份验证令牌或私有 ID。要创建密钥动态变量，只需为动态变量添加 secret__ 前缀。

从工具更新动态变量

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

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

• 状态对应路径：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 工具的字段，相关说明请参阅此处。

指南

前提条件

• 一个 ElevenLabs 账户
• 已配置的 ElevenLabs 对话式 AI 智能体（在此创建）

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(),
    # Simple 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);

支持的类型

动态变量支持以下值类型：

故障排除