동적 변수
런타임 값을 전달해 에이전트의 동작을 개인화하세요.
동적 변수를 사용하면 런타임 값을 에이전트의 메시지, 시스템 프롬프트, 도구에 삽입할 수 있습니다. 여러 에이전트를 만들지 않고도 사용자별 데이터로 각 대화를 개인화할 수 있습니다.
개요
동적 변수는 에이전트의 여러 요소에 통합할 수 있습니다.
- 동작과 컨텍스트를 맞춤 설정하는 시스템 프롬프트
- 인사말을 개인화하는 첫 메시지
- 사용자별 데이터를 전달하는 도구 매개변수 및 헤더
동적 변수가 유용한 몇 가지 예시는 다음과 같습니다.
- 사용자 이름으로 인사말 개인화
- 응답에 계정 세부 정보 포함
- 도구 호출에 데이터 전달
- 구독 등급에 따라 동작 맞춤 설정
- 대화 ID 또는 통화 시간과 같은 시스템 정보 액세스
동적 변수에는 모든 JSON 값을 저장할 수 있습니다.
목록이나 객체를 프롬프트, URL 또는 기타 텍스트 템플릿에 삽입하면 해당 JSON 텍스트로 삽입됩니다. 목록 변수에 바인딩된 도구 매개변수는 목록 자체를 받습니다.
동적 변수는 아래 system__ 변수를 포함해 대화 세부 정보 API 및 통화 후 웹훅에서 있는 그대로 반환됩니다. dynamic_variables를 JSON 값의 맵으로 파싱하세요. 새 system__ 변수가 추가될 수 있으므로, 인식하지 못하는 키나 값 유형을 거부하지 마세요.
시스템 동적 변수
에이전트는 런타임 구성 없이도 모든 대화에서 기본 제공 system__* 변수에 액세스할 수 있습니다. 이 변수들은 예약된 system__ 네임스페이스 접두사를 사용하며 대화가 진행됨에 따라 자동으로 업데이트됩니다. 사용자 지정 동적 변수는 system__ 접두사를 사용하거나 시스템 변수를 재정의할 수 없습니다.
†로 표시된 변수는 턴 사이에 변경됩니다. 프롬프트 텍스트에 이러한 변수를 넣으면 프롬프트 캐싱이 방지될 수 있습니다. 대안은 모범 사례를 참조하세요.
에이전트 및 대화 식별 정보
시간 및 시간대
전화 및 메시징
이 변수들은 전화 및 메시징 채널에 해당하는 경우 채워집니다.
턴별 대화 상태
대화 기록 형식
system__conversation_history 변수에는 다음 구조의 JSON 객체가 포함됩니다.
각 항목에는 role("user", "agent" 또는 "tool")과 다음 중 하나가 포함됩니다.
message: 턴의 텍스트 콘텐츠tool_requests: 에이전트가 수행한 도구 호출 배열이며, 확인된 매개변수 값을 포함합니다.tool_results: 도구 응답 배열
도구 결과나 매개변수에 중첩된 대화 기록이 포함된 경우, 제한 없이 재귀적으로 확장되는 것을 방지하기 위해 자리 표시자(예: [conversation_history (5 turns)])로 삭제 처리됩니다.
이 변수는 대화 컨텍스트를 도구(예: 웹훅 또는 사용자 지정 LLM)에 전달하거나, 핸드오프 중 하위 에이전트 프롬프트에 대화 기록을 포함하는 데 유용합니다.
업로드된 파일
system__uploaded_file_ids에는 사용자가 위젯이나 WhatsApp 등의 채팅에서 첨부한 파일 ID가 나열됩니다. 매 턴마다 업데이트되므로, 사용자가 현재 메시지에 첨부한 파일은 에이전트가 도구를 호출할 때 이미 목록에 포함되어 있습니다.
대화가 아직 활성 상태인 동안 첨부 파일을 처리하려면 system__conversation_id와 함께 목록을 서버 도구의 배열 매개변수에 바인딩하세요. 사용자가 파일을 첨부하기 전에 에이전트가 도구를 호출하면 매개변수는 빈 목록을 받습니다.
그런 다음 서버에서 API 키를 사용해 각 파일을 다운로드합니다.
응답은 원본 파일이며 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
동적 변수를 첫 번째 사용자의 이메일로 업데이트하려면 다음과 같이 할당을 설정하세요.

할당은 각 웹훅 도구에서 구성합니다. API 레퍼런스의 도구 할당을 참조하세요.
가이드
사전 요구 사항:
- ElevenLabs 계정
- 구성된 ElevenAgents 에이전트(빠른 시작에 따라 생성)
공개 대화 페이지 통합
공개 대화 페이지는 URL 매개변수를 통해 동적 변수를 지원하므로 에이전트 링크를 공유할 때 대화를 개인화할 수 있습니다. 특히 웹사이트, 이메일 또는 마케팅 캠페인에 개인화된 에이전트를 삽입할 때 유용합니다.
URL 매개변수 방식
공개 대화 페이지에 동적 변수를 전달하는 방법은 두 가지입니다.
방법 1: Base64 인코딩 JSON
vars 매개변수를 사용해 변수를 base64로 인코딩된 JSON 객체로 전달합니다.
vars 매개변수에는 base64로 인코딩된 JSON이 포함됩니다.
방법 2: 개별 쿼리 매개변수
var_ 접두사가 붙은 쿼리 매개변수를 사용해 변수를 전달합니다.
매개변수 우선순위
두 방법을 동시에 사용하면 충돌을 방지하기 위해 개별 var_ 매개변수가 base64로 인코딩된 변수보다 우선합니다.
이 예시에서 user_name은 "Jane"(base64로 인코딩된 vars의 값)이 아니라 "John"(var_user_name의 값)이 됩니다.
구현 예시
JavaScript URL 생성
Python URL 생성
수동 URL 구성
모범 사례
현재 시간을 프롬프트에 넣는 대신 시간대 설정
시스템 프롬프트, 워크플로 노드, 프로시저의 변수는 매 턴마다 확인됩니다. 턴 사이에 값이 변경되면 프롬프트를 캐시할 수 없어 비용과 지연 시간이 증가합니다. {{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 자체에 값이 필요한 경우에는 적용되지 않습니다.
도구 헤더에 유지되는 값에만 secret__ 사용
인증 토큰과 API 키 앞에 secret__를 붙이면 도구 헤더에만 바인딩할 수 있으며 LLM으로 전송되지 않습니다. secret__ 값은 대화 API에서 <REDACTED>로 마스킹되므로(통화 후 전사 웹훅은 원래 값을 계속 수신함), 대화 API에서 다시 읽어야 하는 값은 일반 동적 변수로 전달하거나 민감하지 않은 식별자를 전달한 후 자체 시스템에서 민감한 값을 조회하세요.
인증에 system__user_id를 사용하지 않기
system__user_id는 추적 및 분석을 위해 클라이언트에서 제공되며 ElevenAgents에서 검증되지 않습니다. 계정 데이터를 노출하기 전에 대화 시작 웹훅, secret__ 헤더 변수의 서명된 토큰 또는 인증 도구 호출을 통해 발신자 신원을 확인하세요.
테스트 및 미리보기를 위한 플레이스홀더 구성
프롬프트, 첫 메시지 및 도구에서 사용하는 모든 사용자 지정 변수에 대해 dynamic_variable_placeholders에서 기본값을 설정하세요. 대시보드의 대화 미리보기와 시뮬레이션 테스트는 대화 시작 웹훅을 실행하지 않으므로, 설정되지 않은 변수는 테스트 중에 리터럴 {{variable_name}} 플레이스홀더로 남습니다.
문제 해결
변수가 대체되지 않음
다음을 확인하세요.
- 변수 이름이 정확히 일치하는지(대소문자 구분)
- 변수에 큰 중괄호를 두 번 사용했는지:
{{variable_name}} - 변수가
dynamic_variables객체에 포함되어 있는지
유형 오류
다음을 확인하세요.
- 변수 값이 예상 유형과 일치하는지
- 값이 문자열, 숫자 또는 불리언만으로 구성되는지




