Các biến động (Dynamic variable) trong ElevenAgents

Truyền các giá trị runtime để cá nhân hóa hành vi của agent.

Các biến động (Dynamic variable) cho phép bạn đưa các giá trị runtime vào tin nhắn, câu lệnh hệ thống (system prompt) và những công cụ của agent. Nhờ đó, bạn có thể cá nhân hóa từng cuộc hội thoại bằng dữ liệu dành riêng cho từng người dùng mà không cần phải tạo ra nhiều agent khác nhau.

Tổng quan

Các biến động có thể được tích hợp vào nhiều khía cạnh của agent:

• Câu lệnh hệ thống để tùy chỉnh hành vi và ngữ cảnh
• Tin nhắn đầu tiên để cá nhân hóa lời chào
• Tham số và tiêu đề công cụ để truyền dữ liệu dành riêng cho người dùng

Dưới đây là một vài ví dụ về việc các biến động hữu ích:

• Cá nhân hóa lời chào bằng tên người dùng
• Bao gồm chi tiết tài khoản trong phản hồi
• Truyền dữ liệu đến các lệnh gọi công cụ
• Tùy chỉnh hành vi dựa trên cấp độ đăng ký
• Truy cập thông tin hệ thống như ID cuộc trò chuyện hoặc thời lượng cuộc gọi

Các biến động hỗ trợ ba loại giá trị:

• Chuỗi: Giá trị văn bản
• Số: Giá trị số học
• Boolean: Giá trị True/False

Các biến động hệ thống

Agent của bạn có quyền truy cập vào các biến system__* tích hợp sẵn trong mọi cuộc trò chuyện mà không cần cấu hình thời gian chạy. Các biến này được đặt tiền tố bằng namespace  system__ dành riêng và tự động cập nhật khi cuộc trò chuyện diễn ra. Các biến động tùy chỉnh không thể sử dụng tiền tố system__ hoặc ghi đè lên các biến hệ thống.

Những biến được đánh dấu bằng † thay đổi giữa các lượt. Việc đặt chúng trong văn bản prompt có thể ngăn chặn việc lưu cache prompt.

Nhận dạng agent và cuộc trò chuyện

Thời gian và múi giờ

Điện thoại và nhắn tin

Những biến này được điền dữ liệu khi áp dụng cho các kênh điện thoại và nhắn tin:

Định dạng lịch sử hội thoại

Biến system__conversation_history chứa một đối tượng JSON với cấu trúc như sau:

{
  "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\"}" }]
    }
  ]
}

Mỗi mục bao gồm một vai trò (user, agent hoặc tool) cùng với một trong các thành phần sau:

• message: Nội dung văn bản của lượt tương tác.
• tool_requests: Một mảng các lệnh gọi công cụ do agent thực hiện, kèm theo các giá trị tham số đã được xác định.
• tool_results: Một mảng các phản hồi từ công cụ.

Nếu kết quả hoặc tham số của công cụ chứa lịch sử hội thoại lồng nhau, nội dung đó sẽ được thay thế bằng một trình giữ chỗ (ví dụ: [conversation_history (5 turns)]) để tránh việc mở rộng đệ quy không giới hạn.

Biến này hữu ích cho việc truyền ngữ cảnh hội thoại vào các công cụ (như webhook hoặc các mô hình ngôn ngữ lớn - LLM tùy chỉnh), hoặc để đưa lịch sử hội thoại vào prompt cho các sub-agent trong quá trình chuyển giao nhiệm vụ.

Các biến động (dynamic variable) bảo mật

Các biến động bảo mật được thiết lập theo cách tương tự như những biến động thông thường, nhưng chúng báo hiệu cho ElevenAgents rằng các biến này chỉ được phép sử dụng trong phần header của biến động và tuyệt đối không được gửi đến nhà cung cấp LLM dưới dạng một phần trong câu lệnh hệ thống (system prompt) hoặc thông điệp đầu tiên của agent.

Hãy sử dụng các biến động bảo mật cho auth token hoặc mã định danh (ID) riêng tư không nên để lộ cho LLM. Để tạo một biến động bảo mật, hãy thêm tiền tố secret__ vào tên biến.

Cập nhật các biến động thông qua công cụ

Các lệnh gọi công cụ có thể tạo hoặc cập nhật những biến động nếu chúng trả về một đối tượng JSON hợp lệ. Để chỉ định dữ liệu cần trích xuất, hãy thiết lập đường dẫn đến đối tượng đó bằng ký hiệu dấu chấm. Nếu trường hoặc đường dẫn không tồn tại, sẽ không có dữ liệu nào được cập nhật.

Ví dụ về đối tượng phản hồi và cách sử dụng ký hiệu dấu chấm:

• Trạng thái (Status) tương ứng với đường dẫn: response.status
• Email của người dùng đầu tiên trong mảng users tương ứng với đường dẫn: 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"
      }
    ]
  }
}

Để cập nhật một biến động (dynamic variable) thành địa chỉ email của người dùng đầu tiên, hãy thiết lập phép gán như sau.

Các phép gán được cấu hình trên từng công cụ webhook.

Hướng dẫn

Điều kiện tiên quyết:

• Một tài khoản ElevenLabs
• Một agent ElevenAgents đã được cấu hình (hãy làm theo hướng dẫn nhanh để tạo một agent)

1. Định nghĩa những biến động trong các prompt

Thêm các biến bằng cách sử dụng cặp dấu ngoặc nhọn {{tên_biến}} trong:

• Các câu lệnh hệ thống (System prompts)
• Các tin nhắn đầu tiên (First messages)
• Các tham số công cụ (Tool parameters)

2. Định nghĩa những biến động trong các công cụ

Bạn cũng có thể định nghĩa các biến động trong cấu hình công cụ. Để tạo một biến động mới, hãy đặt loại giá trị thành biến động (Dynamic variable) và nhấp vào nút +.

3. Thiết lập các giá trị giữ chỗ

Cấu hình những giá trị mặc định để phục vụ việc kiểm thử mà không cần truyền các biến vào runtime.

Cập nhật thông qua dashboard

Thiết lập các giá trị mặc định cho từng biến động trong dashboard của agent.

Cập nhật thông qua giao diện dòng lệnh (CLI)

Tải xuống cấu hình agent

elevenlabs agents pull --agent "<agent-name>"

Chỉnh sửa file agent_configs/<agent-name>.json

Thiết lập mục conversation_config.agent.dynamic_variables.dynamic_variable_placeholders. Mỗi key là tên biến; giá trị (value) tương ứng là phần giữ chỗ (placeholder) được sử dụng trong quá trình thử nghiệm:

{
  "conversation_config": {
    "agent": {
      "dynamic_variables": {
        "dynamic_variable_placeholders": {
          "user_name": "Angelo",
          "account_type": "premium"
        }
      }
    }
  }
}

Đẩy các thay đổi của bạn lên

elevenlabs agents push --agent "<agent-name>"

Cập nhật thông qua 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",
        },
      },
    },
  },
});

4. Truyền các biến vào runtime

Khi bắt đầu một cuộc hội thoại, hãy cung cấp các biến động trong code của bạn:

Đảm bảo rằng bạn đã cài đặt phiên bản SDK mới nhất.

Python

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

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

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
)

Widget

<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>

Tích hợp trang trò chuyện công khai 

Trang trò chuyện công khai hỗ trợ các biến động thông qua tham số URL, cho phép bạn cá nhân hóa các cuộc hội thoại khi chia sẻ liên kết đến agent. Tính năng này đặc biệt hữu ích khi nhúng các agent đã được cá nhân hóa vào trang web, email hoặc nhừn chiến dịch tiếp thị.

Các phương thức truyền tham số URL

Có hai phương thức để truyền các biến động vào trang trò chuyện công khai:

Phương thức 1: Sử dụng JSON mã hóa Base64

Truyền các biến dưới dạng một đối tượng JSON được mã hóa Base64 thông qua tham số vars:

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

Tham số vars chứa dữ liệu JSON đã được mã hóa Base64:

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

Phương thức 2: Sử dụng các tham số truy vấn riêng lẻ

Truyền các biến bằng cách sử dụng các tham số truy vấn có tiền tố var_:

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

Thứ tự ưu tiên của tham số

Khi cả hai phương thức được sử dụng đồng thời, các tham số riêng lẻ có tiền tố var_ sẽ được ưu tiên hơn so với những biến trong chuỗi JSON mã hóa Base64 để tránh xung đột:

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

Trong ví dụ này, user_name sẽ là John (lấy từ var_user_name) thay vì Jane (lấy từ tham số vars đã mã hóa Base64).

Ví dụ về cách triển khai

Tạo URL bằng JavaScript

// Phương pháp 1: JSON được mã hóa Base64
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}`;
}

// Phương pháp 2: Các tham số riêng lẻ
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);

Tạo URL bằng 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)

Xây dựng URL thủ công

# Phương thức mã hóa Base64
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

# Phương pháp các tham số riêng biệt
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