动态变量

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

概述

动态变量可集成到智能体的多个方面：

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

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

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

动态变量支持 3 种值类型：

系统动态变量

每次对话中，智能体无需运行时配置即可访问内置的 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）传递对话上下文，或在交接时将对话历史记录纳入子智能体提示词。

机密动态变量

机密动态变量的填充方式与普通动态变量相同，但会告知 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 工具中配置；请参阅 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())

公开 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：

{ "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);

最佳实践

故障排除