> 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. # 动态变量 **动态变量** 可将运行时值注入智能体的消息、系统提示词和工具中。无需创建多个智能体，即可通过用户专属数据个性化每次对话。 ## 概述 动态变量可集成到智能体的多个方面： * 使用 **系统提示词** 自定义行为和上下文 * 使用 **首条消息** 个性化问候语 * 使用 **工具参数和标头** 传递用户专属数据 以下是动态变量的一些常见用途： * 使用用户名 **个性化问候语** * 在回复中 **包含账户详情** * 向工具调用 **传递数据** * 根据订阅等级 **自定义行为** * 访问对话 ID 或通话时长等 **系统信息** 动态变量支持 3 种值类型： #### 字符串 文本值 #### 数字 数值 #### 布尔值 真/假值 ## 系统动态变量 每次对话中，智能体无需运行时配置即可访问内置的 `system__*` 变量。这些变量带有保留的 `system__` 命名空间前缀，并会随对话进展自动更新。自定义动态变量不能使用 `system__` 前缀，也不能覆盖系统变量。 标有 † 的变量会在轮次间变化。将其放入提示词文本可能会导致提示词无法缓存；替代方案请参阅[最佳实践](#best-practices)。 ### 智能体和对话标识 | 变量 | 类型 | 说明 | 示例 | | -------------------------- | ---------------- | --------------------------------------------------------------------------- | -------------------------------------- | | `system__agent_id` | `string` | 发起对话的智能体唯一标识符。在对话期间不会变化。 | `"agent_8401kp8bt0jdf14rzzcv5veq94yg"` | | `system__current_agent_id` | `string` | 当前活跃智能体的唯一标识符。对话转接至另一智能体时会更新。 | `"agent_8401kp8bt0jdf14rzzcv5veq94yg"` | | `system__conversation_id` | `string` | ElevenLabs 唯一对话标识符。 | `"conv_1801kp8qtb2begztn7zyf446v4jk"` | | `system__user_id` | `string \| null` | 客户端提供的用户 ID，用于跟踪和分析。不得用于身份验证。 | `"G6yhJW8MktQdhUquvXD1iKpPHql2"` | | `system__initiator_id` | `string \| null` | 与发起对话时所用身份验证方式对应的标识符。 | `"user_1801kp8qtb2begztn7zyf446v4jk"` | | `system__channel` | `string` | 发起对话的渠道来源。 | `"slack_integration"` | | `system__is_text_only` | `boolean` | 对话以纯文本（聊天）模式运行时为 `true`；语音通话时为 `false`。 | `true` | | `system__environment` | `string` | 对话运行的环境，用于解析[环境变量](/docs/zh/eleven-agents/integrate/environment-variables)。 | `"production"` | ### 时间和时区 | 变量 | 类型 | 说明 | 示例 | | ----------------------- | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------ | | `system__timezone` | `string \| null` | 配置的时区（`conversation_config.agent.prompt.timezone`）或调用方提供的 IANA 时区。未设置时默认为 UTC。 | `"America/New_York"` | | `system__time` † | `string` | 配置时区中的当前日期和时间（`%A, %H:%M %d %B %Y`）。每轮都会重新计算（每分钟变化一次）。 | `"Friday, 12:33 12 December 2025"` | | `system__time_utc` † | `string` | ISO 8601 格式的当前 UTC 时间戳。每轮都会重新计算。 | `"2025-12-12T12:33:45.123456+00:00"` | | `system__time_date` | `string` | 配置时区中的当前日期（未设置时为 UTC）（`%A, %d %B %Y`）。每天变化一次。 | `"Friday, 12 December 2025"` | | `system__time_hour` | `integer` | 配置时区中的当前小时（`0`–`23`）（未设置时为 UTC）。最多每小时变化一次。 | `12` | | `system__time_minute` † | `integer` | 配置时区中的当前分钟（`0`–`59`）（未设置时为 UTC）。每分钟变化一次。 | `33` | | `system__time_second` † | `integer` | 配置时区中的当前秒数（`0`–`59`）（未设置时为 UTC）。每轮都会变化。 | `45` | ### 电话和消息 以下变量会在适用时为电话和消息渠道填充： | 变量 | 类型 | 说明 | 示例 | | ----------------------- | ---------------- | ---------------------------------------- | ---------------------------------------- | | `system__caller_id` | `string \| null` | 来电方电话号码（语音/SMS/WhatsApp/Amazon Connect）。 | `"+14155552671"` | | `system__called_number` | `string \| null` | 被叫目标电话号码。 | `"+18005551234"` | | `system__call_sid` | `string \| null` | Twilio Call SID（仅限 Twilio 通话）。 | `"CA3498076234a8bbf65c8f09fb8ad7ac1b"` | | `system__call_id` | `string \| null` | SIP Call-ID（仅限 SIP 中继通话）。 | `"757f72cf-e80f-44f7-87d6-a961ffbf5b3d"` | ### 每轮对话状态 | 变量 | 类型 | 说明 | 示例 | | ---------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `system__call_duration_secs` † | `integer` | 已过去的对话时长（秒）。每轮都会重新计算。 | `142` | | `system__agent_turns` † | `integer` | 当前对话中智能体轮次总数。每轮递增。 | `5` | | `system__current_agent_turns` † | `integer` | 当前智能体的轮次数量；智能体转接后会重置为 `0`。 | `3` | | `system__current_subagent_turns` † | `integer` | 当前 workflow 节点中的智能体轮次数量；节点切换时会重置为 `0`。 | `2` | | `system__conversation_history` † | `string` | 截至当前轮次的 JSON 序列化对话记录（`{"entries": [{"role": "user", "message": "..."}]}`）。参阅[对话历史记录格式](#conversation-history-format)。 | `'{"entries": [...]}'` | ### 对话历史记录格式 `system__conversation_history` 变量包含一个具有以下结构的 JSON 对象： ```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__` 前缀。 > **Warning** > > 机密值会以脱敏形式存储，因此 conversations API 会将其返回为 ``。 > 通话后的转录 webhook 会传递原始值，因此请确保 webhook 端点 > 将其视为机密处理。不要对需要从 > conversations API 读取的值使用 `secret__` 前缀。请将这些值作为普通动态变量传递，或传递非敏感标识符， > 然后在自己的系统中查找敏感值。 ## 从工具更新动态变量 如果[工具调用](/docs/zh/eleven-agents/customization/tools)返回有效的 JSON 对象，即可创建或更新动态变量。要指定需提取的内容，请使用点表示法设置对象路径。如果字段或路径不存在，则不会更新任何内容。 响应对象和点表示法示例： * 状态对应路径：`response.status` * users 数组中第一个用户的邮箱对应路径：`response.users.0.email` **`JSON`** ```JSON title="JSON" { "response": { "status": 200, "message": "Successfully found 5 users", "users": [ "user_1": { "user_name": "test_user_1", "email": "test_user_1@email.com" } ] } } ``` 要将动态变量更新为第一个用户的邮箱，请按如下方式设置赋值。 ![查询参数](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) 赋值在每个 webhook 工具中配置；请参阅 API 参考文档中的[工具赋值](/docs/zh/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments)。 ## 指南 前提条件： * 一个 [ElevenLabs 账户](https://elevenlabs.io) * 已配置的 ElevenAgents 智能体（按照[快速入门](/docs/zh/eleven-agents/quickstart)创建） #### 在提示词中定义动态变量 在以下位置使用双花括号 `{{variable_name}}` 添加变量： * 系统提示词 * 首条消息 * 工具参数 ![消息中的动态变量](/docs/_fern-img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp) ![消息中的动态变量](/docs/_fern-img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp) #### 在工具中定义动态变量 也可以在工具配置中定义动态变量。 要创建新的动态变量，请将值类型设为“动态变量”，然后点击 `+` 按钮。 ![设置占位符](/docs/_fern-img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp) ![设置占位符](/docs/_fern-img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp) #### 设置占位符 配置默认值，以便在运行时不传递变量的情况下进行测试。 #### 通过控制台更新 在智能体控制台中为每个动态变量设置默认值。 ![设置占位符](/docs/_fern-img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp) #### 通过 CLI 更新 #### 拉取智能体配置 ```bash elevenlabs agents pull --agent "" ``` #### 编辑 \`agent_configs/\.json\` 设置 `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders`。每个键都是变量名；值是测试期间使用的占位符： ```json { "conversation_config": { "agent": { "dynamic_variables": { "dynamic_variable_placeholders": { "user_name": "Angelo", "account_type": "premium" } } } } } ``` #### 推送更改 ```bash elevenlabs agents push --agent "" ``` #### 通过 API 更新 ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", conversation_config={ "agent": { "dynamic_variables": { "dynamic_variable_placeholders": { "user_name": "Angelo", "account_type": "premium", } } }, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { conversationConfig: { agent: { dynamicVariables: { dynamicVariablePlaceholders: { user_name: "Angelo", account_type: "premium", }, }, }, }, }); ``` #### 在运行时传递变量 启动对话时，在代码中提供动态变量： > **Tip** > > 请确保已安装最新版本的 [SDK](/docs/zh/eleven-agents/libraries/python)。 **`Python`** ```python title="Python" focus={10-23} maxLines=25 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()) ``` **`JavaScript`** ```javascript title="JavaScript" focus={7-20} maxLines=25 import { Conversation } from '@elevenlabs/client'; class VoiceAgent { ... async startConversation() { try { // Request microphone access await navigator.mediaDevices.getUserMedia({ audio: true }); this.conversation = await Conversation.startSession({ agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6', dynamicVariables: { user_name: 'Angelo' }, ... add some callbacks here }); } catch (error) { console.error('Failed to start conversation:', error); alert('Failed to start conversation. Please ensure microphone access is granted.'); } } } ``` **`Swift`** ```swift title="Swift" let dynamicVars: [String: DynamicVariableValue] = [ "customer_name": .string("John Doe"), "account_balance": .number(5000.50), "user_id": .int(12345), "is_premium": .boolean(true) ] // Create session config with dynamic variables let config = SessionConfig( agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6", dynamicVariables: dynamicVars ) // Start the conversation let conversation = try await Conversation.startSession( config: config ) ``` **`组件`** ```html title="组件" ``` ## 公开 talk-to 页面集成 公开 talk-to 页面通过 URL 参数支持动态变量，因此在分享智能体链接时可个性化对话。这尤其适合在网站、邮件或营销活动中嵌入个性化智能体。 ### URL 参数方法 可通过两种方法向公开 talk-to 页面传递动态变量： #### 方法 1：Base64 编码的 JSON 使用 `vars` 参数将变量作为 Base64 编码的 JSON 对象传递： ``` https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9 ``` `vars` 参数包含 Base64 编码的 JSON： ```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`）。 ### 实现示例 #### JavaScript URL 生成 ```javascript // 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); ``` #### Python URL 生成 ```python import base64 import json from urllib.parse import urlencode, quote def generate_talk_to_url(agent_id, variables): """Generate URL with base64-encoded variables""" base_url = "https://elevenlabs.io/app/talk-to" encoded_vars = base64.b64encode(json.dumps(variables).encode()).decode() return f"{base_url}?agent_id={agent_id}&vars={encoded_vars}" def generate_talk_to_url_with_params(agent_id, variables): """Generate URL with individual var_ parameters""" base_url = "https://elevenlabs.io/app/talk-to" params = {"agent_id": agent_id} for key, value in variables.items(): params[f"var_{key}"] = value return f"{base_url}?{urlencode(params)}" # Usage variables = { "user_name": "John Doe", "account_type": "premium", "session_id": "sess_123" } url_method1 = generate_talk_to_url("agent_7101k5zvyjhmfg983brhmhkd98n6", variables) url_method2 = generate_talk_to_url_with_params("agent_7101k5zvyjhmfg983brhmhkd98n6", variables) ``` #### 手动构建 URL ``` # Base64-encoded method 1. Create JSON: {"user_name": "John", "account_type": "premium"} 2. Encode to base64: eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9 3. Add to URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9 # Individual parameters method 1. Add each variable with var_ prefix 2. URL encode values if needed 3. Final URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium ``` ## 最佳实践 #### 设置时区，而非在提示词中加入当前时间 系统提示词、[workflow](/docs/zh/eleven-agents/customization/agent-workflows) 节点和[程序](/docs/zh/eleven-agents/customization/procedures)中的变量会在每轮解析。如果值在轮次间变化，提示词便无法缓存，从而增加成本和延迟。`{{system__time_utc}}` 和 `{{system__time_second}}` 每轮都会变化；`{{system__time}}` 和 `{{system__time_minute}}` 每分钟变化一次。 若要让智能体获取当前日期和时间，请在系统提示词编辑器中使用时区按钮设置时区（`conversation_config.agent.prompt.timezone`），而不要在提示词文本中加入 `{{system__time}}` 或 `{{system__time_utc}}`。设置时区后，平台会在缓存提示词前缀之外添加当前日期和时间，因此系统提示词可跨轮次保持缓存。未设置时区时，智能体不会获得当前日期和时间。 如果提示词需要内嵌日期或小时，可结合使用 `{{system__time_date}}`、`{{system__time_hour}}` 和 `{{system__timezone}}`（例如 `Today is {{system__time_date}}, hour {{system__time_hour}} ({{system__timezone}})`）。这些变量最多每小时变化一次。 #### 将实时状态变量绑定到工具参数和标头 如果工具需要带 † 标记的值，请将其绑定到工具参数或标头，而不要放入提示词。工具参数仅在调用工具时解析，因此不会影响提示词缓存。LLM 已可看到对话，因此提示词中很少需要 `{{system__conversation_history}}`。 #### 考虑替代提示词中轮次计数器的方案 如果提示词会检查 `{{system__agent_turns}}` 等轮次计数器，可考虑以下替代方案。对于静态开场问候或披露信息，请使用 `first_message`。 对于首次回复行为，可围绕对话历史记录编写指令（例如，*"On your first reply, when you have not yet greeted the caller..."*）。这依赖 LLM 遵循指令，因此请使用所选模型进行测试；若结果可靠性较低，请保留轮次计数器。 如果计数器仅用于决定何时分支或升级处理，可在提示词外使用 [workflow 边缘表达式条件](/docs/zh/eleven-agents/customization/agent-workflows#edges-and-flow-control)或结构化程序的 [If 步骤表达式](/docs/zh/eleven-agents/customization/procedures/structured-procedures#if-else-if-and-else)（例如 `system__agent_turns >= 5`）处理。这不适用于 LLM 本身需要该值的情况。 #### 仅将 secret\_\_ 用于保留在工具标头中的值 为身份验证令牌和 API 密钥添加 `secret__` 前缀，使其只能绑定到工具标头，且绝不会发送给 LLM。由于 `secret__` 值会在 conversations API 中以 `` 脱敏显示（通话后的转录 webhook 仍会收到原始值），需要从 conversations API 读取的值应作为普通动态变量传递，或传递非敏感标识符，然后在自己的系统中查找敏感值。 #### 不要依赖 system\_\_user_id 进行身份验证 `system__user_id` 由客户端提供，用于跟踪和分析，未经 ElevenAgents 验证。公开账户数据前，应通过[对话发起 webhook](/docs/zh/eleven-agents/customization/personalization#conversation-initiation-webhooks)、`secret__` 标头变量中的签名令牌，或验证工具调用来验证呼叫者身份。 #### 配置用于测试和预览的占位符 为提示词、首条消息和工具中使用的每个自定义变量，在 `dynamic_variable_placeholders` 中设置默认值。控制台中的对话预览和[模拟测试](/docs/zh/eleven-agents/customization/agent-testing)不会运行对话发起 webhook，因此未设置的变量在测试期间会保留为字面量 `{{variable_name}}` 占位符。 ## 故障排除 #### 变量未替换 请确认： * 变量名称完全一致（区分大小写） * 变量使用双花括号：`{{variable_name}}` * 变量已包含在 `dynamic_variables` 对象中 #### 类型错误 请确认： * 变量值与预期类型一致 * 值只能是字符串、数字或布尔值