동적 변수

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

개요

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

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

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

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

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

시스템 동적 변수

에이전트는 런타임 구성 없이 모든 대화에서 기본 제공 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)])로 삭제 처리됩니다.

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

비밀 동적 변수

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

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

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

할당은 각 웹훅 도구에서 구성합니다. 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())

공개 대화 페이지 통합

공개 대화 페이지는 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);

모범 사례

문제 해결