탐색으로 건너뛰기

동적 변수

런타임 값을 전달해 에이전트의 동작을 개인화하세요.

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

개요

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

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

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

  • 사용자 이름으로 인사말 개인화
  • 응답에 계정 세부 정보 포함
  • 도구 호출에 데이터 전달
  • 구독 등급에 따라 동작 맞춤 설정
  • 대화 ID 또는 통화 시간과 같은 시스템 정보 액세스

동적 변수에는 모든 JSON 값을 저장할 수 있습니다.

문자열
텍스트 값
숫자
숫자 값
불리언
참/거짓 값
목록
모든 JSON 값의 배열
객체
중첩된 키-값 데이터

목록이나 객체를 프롬프트, URL 또는 기타 텍스트 템플릿에 삽입하면 해당 JSON 텍스트로 삽입됩니다. 목록 변수에 바인딩된 도구 매개변수는 목록 자체를 받습니다.

동적 변수는 아래 system__ 변수를 포함해 대화 세부 정보 API 및 통화 후 웹훅에서 있는 그대로 반환됩니다. dynamic_variables를 JSON 값의 맵으로 파싱하세요. 새 system__ 변수가 추가될 수 있으므로, 인식하지 못하는 키나 값 유형을 거부하지 마세요.

시스템 동적 변수

에이전트는 런타임 구성 없이도 모든 대화에서 기본 제공 system__* 변수에 액세스할 수 있습니다. 이 변수들은 예약된 system__ 네임스페이스 접두사를 사용하며 대화가 진행됨에 따라 자동으로 업데이트됩니다. 사용자 지정 동적 변수는 system__ 접두사를 사용하거나 시스템 변수를 재정의할 수 없습니다.

†로 표시된 변수는 턴 사이에 변경됩니다. 프롬프트 텍스트에 이러한 변수를 넣으면 프롬프트 캐싱이 방지될 수 있습니다. 대안은 모범 사례를 참조하세요.

에이전트 및 대화 식별 정보

변수유형설명예시
system__agent_idstring대화를 시작한 에이전트의 고유 식별자입니다. 대화 중에는 변경되지 않습니다."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__current_agent_idstring현재 활성화된 에이전트의 고유 식별자입니다. 대화가 다른 에이전트로 전환되면 업데이트됩니다."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__conversation_idstringElevenLabs의 고유 대화 식별자입니다."conv_1801kp8qtb2begztn7zyf446v4jk"
system__user_idstring | null추적 및 분석을 위해 클라이언트가 제공한 사용자 ID입니다. 인증에 신뢰해서는 안 됩니다."G6yhJW8MktQdhUquvXD1iKpPHql2"
system__initiator_idstring | null대화를 시작하는 데 사용된 인증 방법에 해당하는 식별자입니다."user_1801kp8qtb2begztn7zyf446v4jk"
system__channelstring대화가 시작된 채널 소스입니다."slack_integration"
system__is_text_onlyboolean대화가 텍스트 전용(채팅) 모드로 실행 중이면 true, 음성 통화이면 false입니다.true
system__environmentstring대화가 실행 중인 환경으로, 환경 변수를 확인하는 데 사용됩니다."production"

시간 및 시간대

변수유형설명예시
system__timezonestring | 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 †stringISO 8601 형식의 현재 UTC 타임스탬프입니다. 매 턴마다 다시 평가됩니다."2025-12-12T12:33:45.123456+00:00"
system__time_datestring구성된 시간대의 현재 날짜입니다(설정되지 않은 경우 UTC)(%A, %d %B %Y). 하루에 한 번 변경됩니다."Friday, 12 December 2025"
system__time_hourinteger구성된 시간대의 현재 시간(0–23)입니다(설정되지 않은 경우 UTC). 시간당 최대 한 번 변경됩니다.12
system__time_minute †integer구성된 시간대의 현재 분(0–59)입니다(설정되지 않은 경우 UTC). 분당 한 번 변경됩니다.33
system__time_second †integer구성된 시간대의 현재 초(0–59)입니다(설정되지 않은 경우 UTC). 매 턴마다 변경됩니다.45

전화 및 메시징

이 변수들은 전화 및 메시징 채널에 해당하는 경우 채워집니다.

변수유형설명예시
system__caller_idstring | null발신자의 전화번호입니다(음성/SMS/WhatsApp/Amazon Connect)."+14155552671"
system__called_numberstring | null통화한 대상 전화번호입니다."+18005551234"
system__call_sidstring | nullTwilio 통화 SID입니다(Twilio 통화에만 해당)."CA3498076234a8bbf65c8f09fb8ad7ac1b"
system__call_idstring | nullSIP 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현재 워크플로 노드의 에이전트 턴 수입니다. 노드 전환 시 0으로 재설정됩니다.2
system__conversation_history †string현재 턴까지의 JSON 직렬화 대화 기록입니다({"entries": [{"role": "user", "message": "..."}]}). 대화 기록 형식을 참조하세요.'{"entries": [...]}'
system__uploaded_file_ids †string[] | null현재까지 사용자가 대화에 첨부한 모든 파일의 ID이며, 오래된 순서로 정렬됩니다. 파일이 첨부되기 전까지는 null입니다. 업로드된 파일을 참조하세요.["01a1c47f-1427-71ab-9898-775cce521078"]

대화 기록 형식

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)에 전달하거나, 핸드오프 중 하위 에이전트 프롬프트에 대화 기록을 포함하는 데 유용합니다.

업로드된 파일

system__uploaded_file_ids에는 사용자가 위젯이나 WhatsApp 등의 채팅에서 첨부한 파일 ID가 나열됩니다. 매 턴마다 업데이트되므로, 사용자가 현재 메시지에 첨부한 파일은 에이전트가 도구를 호출할 때 이미 목록에 포함되어 있습니다.

대화가 아직 활성 상태인 동안 첨부 파일을 처리하려면 system__conversation_id와 함께 목록을 서버 도구의 배열 매개변수에 바인딩하세요. 사용자가 파일을 첨부하기 전에 에이전트가 도구를 호출하면 매개변수는 빈 목록을 받습니다.

"request_body_schema": {
"type": "object",
"required": ["file_ids", "conversation_id"],
"properties": {
"file_ids": {
"type": "array",
"description": "",
"dynamic_variable": "system__uploaded_file_ids",
"items": { "type": "string", "description": "File ID" }
},
"conversation_id": {
"type": "string",
"dynamic_variable": "system__conversation_id"
}
}
}

그런 다음 서버에서 API 키를 사용해 각 파일을 다운로드합니다.

curl https://api.elevenlabs.io/v1/convai/conversations/$CONVERSATION_ID/files/$FILE_ID \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-o attachment

응답은 원본 파일이며 Content-Type(예: image/jpeg 또는 application/pdf)을 포함합니다. 대화에 속하지 않는 파일 ID는 404를 반환합니다. 목록의 마지막 ID가 가장 최근 업로드입니다.

비밀 동적 변수

비밀 동적 변수는 일반 동적 변수와 동일한 방식으로 채워지지만, 동적 변수 헤더에서만 사용하고 에이전트의 시스템 프롬프트나 첫 메시지 일부로 LLM 제공업체에 전송해서는 안 된다는 것을 ElevenAgents에 알립니다.

LLM에 전송해서는 안 되는 인증 토큰이나 비공개 ID에는 비밀 동적 변수를 사용하세요. 비밀 동적 변수를 만들려면 동적 변수 앞에 secret__를 붙이세요.

비밀 값은 삭제 처리되어 저장되므로, 대화 API에서는 <REDACTED>로 반환됩니다. 통화 후 전사 웹훅은 원본 값을 전달하므로 웹훅 엔드포인트에서 해당 값을 비밀 정보로 처리하도록 하세요. 대화 API에서 다시 읽어야 하는 값에는 secret__ 접두사를 사용하지 마세요. 그러한 값은 일반 동적 변수로 전달하거나, 민감하지 않은 식별자를 전달한 후 자체 시스템에서 민감한 값을 조회하세요.

도구에서 동적 변수 업데이트

도구 호출은 유효한 JSON 객체를 반환하면 동적 변수를 생성하거나 업데이트할 수 있습니다. 추출할 항목을 지정하려면 점 표기법으로 객체 경로를 설정하세요. 필드나 경로가 없으면 아무것도 업데이트되지 않습니다.

응답 객체 및 점 표기법 예시:

  • 상태는 다음 경로에 해당합니다: response.status
  • users 배열의 첫 번째 사용자 이메일은 다음 경로에 해당합니다: response.users.0.email
JSON
{
"response": {
"status": 200,
"message": "Successfully found 5 users",
"users": [
"user_1": {
"user_name": "test_user_1",
"email": "test_user_1@email.com"
}
]
}
}

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

쿼리 매개변수

할당은 각 웹훅 도구에서 구성합니다. API 레퍼런스의 도구 할당을 참조하세요.

가이드

사전 요구 사항:

1

프롬프트에서 동적 변수 정의

다음 위치에서 이중 중괄호 {{variable_name}}를 사용해 변수를 추가하세요.

  • 시스템 프롬프트
  • 첫 메시지
  • 도구 매개변수

메시지의 동적 변수

메시지의 동적 변수

2

도구에서 동적 변수 정의

도구 구성에서도 동적 변수를 정의할 수 있습니다. 새 동적 변수를 만들려면 값 유형을 동적 변수로 설정하고 + 버튼을 클릭하세요.

자리 표시자 설정

자리 표시자 설정

3

자리 표시자 설정

런타임에 변수를 전달하지 않고 테스트할 수 있도록 기본값을 구성하세요.

에이전트 대시보드에서 각 동적 변수의 기본값을 설정하세요.

자리 표시자 설정

4

런타임에 변수 전달

대화를 시작할 때 코드에서 동적 변수를 제공하세요.

최신 SDK가 설치되어 있는지 확인하세요.

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())

공개 대화 페이지 통합

공개 대화 페이지는 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은 "Jane"(base64로 인코딩된 vars의 값)이 아니라 "John"(var_user_name의 값)이 됩니다.

구현 예시

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

모범 사례

시스템 프롬프트, 워크플로 노드, 프로시저의 변수는 매 턴마다 확인됩니다. 턴 사이에 값이 변경되면 프롬프트를 캐시할 수 없어 비용과 지연 시간이 증가합니다. {{system__time_utc}} 및 {{system__time_second}}는 매 턴마다 변경되며, {{system__time}} 및 {{system__time_minute}}는 매분 변경됩니다.

에이전트에 현재 날짜와 시간을 제공하려면 프롬프트 텍스트에 {{system__time}} 또는 {{system__time_utc}}를 넣는 대신 시스템 프롬프트 편집기의 시간대 버튼에서 시간대(conversation_config.agent.prompt.timezone)를 설정하세요. 시간대를 설정하면 플랫폼이 캐시된 프롬프트 접두사 외부에 현재 날짜와 시간을 추가하므로 시스템 프롬프트가 턴 전반에 걸쳐 캐시된 상태로 유지됩니다. 시간대를 설정하지 않으면 에이전트는 현재 날짜와 시간을 받지 못합니다.

프롬프트에 날짜 또는 시간을 인라인으로 넣어야 하는 경우 {{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이 지시를 따르는 것에 의존하므로 모델로 테스트하고, 결과의 신뢰도가 낮다면 턴 카운터를 유지하세요.

카운터가 분기 또는 에스컬레이션 시점만 결정하는 경우 워크플로 에지 표현식 조건이나 구조화된 프로시저의 If 단계 표현식(예: system__agent_turns >= 5)으로 프롬프트 외부에서 처리할 수 있습니다. 단, LLM 자체에 값이 필요한 경우에는 적용되지 않습니다.

인증 토큰과 API 키 앞에 secret__를 붙이면 도구 헤더에만 바인딩할 수 있으며 LLM으로 전송되지 않습니다. secret__ 값은 대화 API에서 <REDACTED>로 마스킹되므로(통화 후 전사 웹훅은 원래 값을 계속 수신함), 대화 API에서 다시 읽어야 하는 값은 일반 동적 변수로 전달하거나 민감하지 않은 식별자를 전달한 후 자체 시스템에서 민감한 값을 조회하세요.

system__user_id는 추적 및 분석을 위해 클라이언트에서 제공되며 ElevenAgents에서 검증되지 않습니다. 계정 데이터를 노출하기 전에 대화 시작 웹훅, secret__ 헤더 변수의 서명된 토큰 또는 인증 도구 호출을 통해 발신자 신원을 확인하세요.

프롬프트, 첫 메시지 및 도구에서 사용하는 모든 사용자 지정 변수에 대해 dynamic_variable_placeholders에서 기본값을 설정하세요. 대시보드의 대화 미리보기와 시뮬레이션 테스트는 대화 시작 웹훅을 실행하지 않으므로, 설정되지 않은 변수는 테스트 중에 리터럴 {{variable_name}} 플레이스홀더로 남습니다.

문제 해결

다음을 확인하세요.

  • 변수 이름이 정확히 일치하는지(대소문자 구분)
  • 변수에 큰 중괄호를 두 번 사용했는지: {{variable_name}}
  • 변수가 dynamic_variables 객체에 포함되어 있는지

다음을 확인하세요.

  • 변수 값이 예상 유형과 일치하는지
  • 값이 문자열, 숫자 또는 불리언만으로 구성되는지