동적 변수

동적 변수를 사용하면 런타임 값을 에이전트의 메시지, 시스템 프롬프트 및 도구에 삽입할 수 있습니다. 여러 에이전트를 만들지 않고도 사용자별 데이터로 각 대화를 개인화할 수 있습니다.

개요

동적 변수는 에이전트의 여러 요소에 통합할 수 있습니다.

• 동작과 컨텍스트를 맞춤 설정하는 시스템 프롬프트
• 인사말을 개인화하는 첫 메시지
• 사용자별 데이터를 전달하는 도구 매개변수 및 헤더

동적 변수가 유용한 몇 가지 예시는 다음과 같습니다.

• 사용자 이름으로 인사말 개인화
• 응답에 계정 세부 정보 포함
• 도구 호출에 데이터 전달
• 구독 등급에 따른 동작 맞춤 설정
• 대화 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)])로 가려집니다.

이 변수는 도구(예: 웹훅, 사용자 지정 LLM)에 대화 컨텍스트를 전달하거나 핸드오프 중 하위 에이전트 프롬프트에 대화 기록을 포함하는 데 유용합니다.

비밀 동적 변수

비밀 동적 변수는 일반 동적 변수와 같은 방식으로 채워지지만, 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"
      }
    ]
  }
}

동적 변수를 첫 번째 사용자의 이메일로 업데이트하려면 다음과 같이 할당을 설정하세요.

할당은 각 웹훅 도구의 필드이며, 여기에 설명되어 있습니다.

가이드

사전 요구 사항

• ElevenLabs 계정
• 구성된 ElevenLabs 대화형 에이전트(여기에서 만들기)

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은 base64 인코딩된 vars의 “Jane” 대신 var_user_name의 “John”이 됩니다.

구현 예시

// 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);

지원되는 유형

동적 변수는 다음 값 유형을 지원합니다.

문제 해결