> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # 동적 변수 **동적 변수**를 사용하면 런타임 값을 에이전트의 메시지, 시스템 프롬프트, 도구에 삽입할 수 있습니다. 여러 에이전트를 만들지 않고도 사용자별 데이터로 각 대화를 개인화할 수 있습니다. ## 개요 동적 변수는 에이전트의 여러 요소에 통합할 수 있습니다. * 동작과 컨텍스트를 맞춤 설정하는 **시스템 프롬프트** * 인사말을 개인화하는 **첫 메시지** * 사용자별 데이터를 전달하는 **도구 파라미터 및 헤더** 동적 변수가 유용한 몇 가지 예는 다음과 같습니다. * 사용자 이름으로 **인사말 개인화** * 응답에 **계정 세부 정보 포함** * 도구 호출에 **데이터 전달** * 구독 등급에 따라 **동작 맞춤 설정** * 대화 ID나 통화 시간 같은 **시스템 정보 액세스** 동적 변수는 세 가지 값 유형을 지원합니다. #### 문자열 텍스트 값 #### 숫자 숫자 값 #### 불리언 참/거짓 값 ## 시스템 동적 변수 에이전트는 런타임 구성 없이 모든 대화에서 기본 제공 `system__*` 변수에 액세스할 수 있습니다. 이 변수는 예약된 `system__` 네임스페이스 접두사를 사용하며, 대화가 진행되는 동안 자동으로 업데이트됩니다. 사용자 지정 동적 변수에는 `system__` 접두사를 사용할 수 없으며 시스템 변수를 재정의할 수도 없습니다. †로 표시된 변수는 턴 사이에 변경됩니다. 프롬프트 텍스트에 이러한 변수를 넣으면 프롬프트 캐싱이 방지될 수 있습니다. 대안은 [모범 사례](#best-practices)를 참조하세요. ### 에이전트 및 대화 식별 정보 | 변수 | 유형 | 설명 | 예시 | | -------------------------- | ---------------- | --------------------------------------------------------------------------------------------- | -------------------------------------- | | `system__agent_id` | `string` | 대화를 시작한 에이전트의 고유 식별자입니다. 대화 중에는 절대 변경되지 않습니다. | `"agent_8401kp8bt0jdf14rzzcv5veq94yg"` | | `system__current_agent_id` | `string` | 현재 활성화된 에이전트의 고유 식별자입니다. 대화가 다른 에이전트로 전환되면 업데이트됩니다. | `"agent_8401kp8bt0jdf14rzzcv5veq94yg"` | | `system__conversation_id` | `string` | ElevenLabs의 고유 대화 식별자입니다. | `"conv_1801kp8qtb2begztn7zyf446v4jk"` | | `system__user_id` | `string \| null` | 추적 및 분석을 위해 클라이언트가 제공하는 사용자 ID입니다. 인증에 신뢰해서는 안 됩니다. | `"G6yhJW8MktQdhUquvXD1iKpPHql2"` | | `system__initiator_id` | `string \| null` | 대화를 시작하는 데 사용된 인증 방법에 해당하는 식별자입니다. | `"user_1801kp8qtb2begztn7zyf446v4jk"` | | `system__channel` | `string` | 대화가 시작된 채널 소스입니다. | `"slack_integration"` | | `system__is_text_only` | `boolean` | 대화가 텍스트 전용(채팅) 모드로 실행 중이면 `true`, 음성 통화이면 `false`입니다. | `true` | | `system__environment` | `string` | 대화가 실행되는 환경으로, [환경 변수](/docs/ko/eleven-agents/integrate/environment-variables)를 확인하는 데 사용됩니다. | `"production"` | ### 시간 및 시간대 | 변수 | 유형 | 설명 | 예시 | | ----------------------- | ---------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------ | | `system__timezone` | `string \| 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` † | `string` | ISO 8601 형식의 현재 UTC 타임스탬프입니다. 매 턴마다 다시 평가됩니다. | `"2025-12-12T12:33:45.123456+00:00"` | | `system__time_date` | `string` | 구성된 시간대의 현재 날짜입니다(설정되지 않은 경우 UTC)(`%A, %d %B %Y`). 하루에 한 번 변경됩니다. | `"Friday, 12 December 2025"` | | `system__time_hour` | `integer` | 구성된 시간대의 현재 시간(`0`–`23`)입니다(설정되지 않은 경우 UTC). 최대 한 시간에 한 번 변경됩니다. | `12` | | `system__time_minute` † | `integer` | 구성된 시간대의 현재 분(`0`–`59`)입니다(설정되지 않은 경우 UTC). 분당 한 번 변경됩니다. | `33` | | `system__time_second` † | `integer` | 구성된 시간대의 현재 초(`0`–`59`)입니다(설정되지 않은 경우 UTC). 매 턴마다 변경됩니다. | `45` | ### 전화 및 메시징 이 변수는 전화 및 메시징 채널에 해당하는 경우 채워집니다. | 변수 | 유형 | 설명 | 예시 | | ----------------------- | ---------------- | -------------------------------------------- | ---------------------------------------- | | `system__caller_id` | `string \| null` | 발신자 전화번호입니다(음성/SMS/WhatsApp/Amazon Connect). | `"+14155552671"` | | `system__called_number` | `string \| null` | 통화 대상 전화번호입니다. | `"+18005551234"` | | `system__call_sid` | `string \| null` | Twilio 통화 SID입니다(Twilio 통화만 해당). | `"CA3498076234a8bbf65c8f09fb8ad7ac1b"` | | `system__call_id` | `string \| null` | SIP 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": "..."}]}`). [대화 기록 형식](#conversation-history-format)을 참조하세요. | `'{"entries": [...]}'` | ### 대화 기록 형식 `system__conversation_history` 변수에는 다음 구조의 JSON 객체가 포함됩니다. ```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__`를 붙이세요. > **Warning** > > 비밀 값은 삭제 처리된 상태로 저장되므로, conversations API에서는 ``로 반환됩니다. > 통화 후 전사 웹훅은 원래 값을 전달하므로 웹훅 엔드포인트가 이를 비밀 정보로 > 처리하도록 하세요. conversations API에서 다시 읽어야 하는 값에는 `secret__` 접두사를 사용하지 마세요. > 해당 값은 일반 동적 변수로 전달하거나, 민감하지 않은 식별자를 전달한 뒤 > 자체 시스템에서 민감한 값을 조회하세요. ## 도구에서 동적 변수 업데이트 [도구 호출](/docs/ko/eleven-agents/customization/tools)은 유효한 JSON 객체를 반환하면 동적 변수를 만들거나 업데이트할 수 있습니다. 추출할 항목을 지정하려면 점 표기법을 사용해 객체 경로를 설정하세요. 필드 또는 경로가 존재하지 않으면 업데이트되지 않습니다. 응답 객체와 점 표기법의 예시: * 상태는 다음 경로에 해당합니다: `response.status` * users 배열의 첫 번째 사용자 이메일은 다음 경로에 해당합니다: `response.users.0.email` **`JSON`** ```JSON title="JSON" { "response": { "status": 200, "message": "Successfully found 5 users", "users": [ "user_1": { "user_name": "test_user_1", "email": "test_user_1@email.com" } ] } } ``` 동적 변수를 첫 번째 사용자의 이메일로 업데이트하려면 다음과 같이 할당을 설정하세요. ![쿼리 파라미터](/docs/_fern-files/_img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) 할당은 각 웹훅 도구에서 구성합니다. API 레퍼런스의 [도구 할당](/docs/ko/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments)을 참조하세요. ## 가이드 사전 요구 사항: * [ElevenLabs 계정](https://elevenlabs.io) * 구성된 ElevenAgents 에이전트(생성 방법은 [빠른 시작](/docs/ko/eleven-agents/quickstart) 참조) #### 프롬프트에서 동적 변수 정의 다음 위치에서 이중 중괄호 `{{variable_name}}`를 사용해 변수를 추가하세요. * 시스템 프롬프트 * 첫 메시지 * 도구 파라미터 ![메시지의 동적 변수](/docs/_fern-files/_img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp) ![메시지의 동적 변수](/docs/_fern-files/_img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp) #### 도구에서 동적 변수 정의 도구 구성에서도 동적 변수를 정의할 수 있습니다. 새 동적 변수를 만들려면 값 유형을 동적 변수로 설정하고 `+` 버튼을 클릭하세요. ![자리 표시자 설정](/docs/_fern-files/_img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp) ![자리 표시자 설정](/docs/_fern-files/_img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp) #### 자리 표시자 설정 런타임에 변수를 전달하지 않고 테스트할 수 있도록 기본값을 구성하세요. #### 대시보드에서 업데이트 에이전트 대시보드에서 각 동적 변수의 기본값을 설정하세요. ![자리 표시자 설정](/docs/_fern-files/_img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp) #### CLI에서 업데이트 #### 에이전트 구성 가져오기 ```bash elevenlabs agents pull --agent "" ``` #### \`agent_configs/\.json\` 편집 `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders`를 설정하세요. 각 키는 변수 이름이고, 값은 테스트 중 사용되는 자리 표시자입니다. ```json { "conversation_config": { "agent": { "dynamic_variables": { "dynamic_variable_placeholders": { "user_name": "Angelo", "account_type": "premium" } } } } } ``` #### 변경 사항 푸시 ```bash elevenlabs agents push --agent "" ``` #### 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", }, }, }, }, }); ``` #### 런타임에 변수 전달 대화를 시작할 때 코드에서 동적 변수를 제공하세요. > **Tip** > > 최신 [SDK](/docs/ko/eleven-agents/libraries/python)가 설치되어 있는지 확인하세요. **`Python`** ```python title="Python" focus={10-23} maxLines=25 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`** ```javascript title="JavaScript" focus={7-20} maxLines=25 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`** ```swift title="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 ) ``` **`위젯`** ```html title="위젯" ``` ## 공개 대화 페이지 통합 공개 대화 페이지는 URL 파라미터를 통해 동적 변수를 지원하므로, 에이전트 링크를 공유할 때 대화를 개인화할 수 있습니다. 이는 개인화된 에이전트를 웹사이트, 이메일 또는 마케팅 캠페인에 삽입할 때 특히 유용합니다. ### URL 파라미터 방식 공개 대화 페이지에 동적 변수를 전달하는 방법은 두 가지입니다. #### 방법 1: Base64 인코딩 JSON `vars` 파라미터를 사용하여 변수를 base64 인코딩된 JSON 객체로 전달합니다. ``` https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9 ``` `vars` 파라미터에는 base64 인코딩된 JSON이 포함됩니다. ```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"`이 됩니다. ### 구현 예시 #### JavaScript URL 생성 ```javascript // 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); ``` #### Python URL 생성 ```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) ``` #### 수동 URL 구성 ``` # Base64-encoded method 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 # Individual parameters method 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 ``` ## 모범 사례 #### 프롬프트에 현재 시간을 넣는 대신 시간대 설정 시스템 프롬프트, [워크플로](/docs/ko/eleven-agents/customization/agent-workflows) 노드 및 [절차](/docs/ko/eleven-agents/customization/procedures)의 변수는 매 턴마다 확인됩니다. 턴 사이에 값이 변경되면 프롬프트를 캐시할 수 없어 비용과 지연 시간이 늘어납니다. `{{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`를 사용하세요. 첫 응답 동작에는 대화 기록을 중심으로 지시문을 작성할 수 있습니다(예: *"첫 답변에서 아직 발신자에게 인사하지 않았다면..."*). 이 방식은 LLM이 지시를 따르는 것에 의존하므로 사용하는 모델로 테스트하고, 결과의 신뢰도가 낮다면 턴 카운터를 유지하세요. 카운터가 분기 또는 에스컬레이션 시점만 결정한다면 [워크플로 엣지 표현식 조건](/docs/ko/eleven-agents/customization/agent-workflows#edges-and-flow-control) 또는 구조화된 절차의 [If 단계 표현식](/docs/ko/eleven-agents/customization/procedures/structured-procedures#if-else-if-and-else)(예: `system__agent_turns >= 5`)으로 프롬프트 외부에서 처리할 수 있습니다. 이는 LLM 자체에 해당 값이 필요한 경우에는 적용되지 않습니다. #### 도구 헤더에만 유지되는 값에만 secret\_\_ 사용 인증 토큰과 API 키 앞에 `secret__`를 붙이면 도구 헤더에만 바인딩할 수 있으며 LLM으로 전송되지 않습니다. `secret__` 값은 conversations API에서 ``로 삭제 처리되므로(통화 후 전사 웹훅은 여전히 원래 값을 수신함), conversations API에서 다시 읽어야 하는 값은 일반 동적 변수로 전달하거나 민감하지 않은 식별자를 전달한 후 자체 시스템에서 민감한 값을 조회하세요. #### 인증에 system\_\_user_id를 사용하지 않기 `system__user_id`는 추적 및 분석을 위해 클라이언트가 제공하는 값이며 ElevenAgents에서 검증하지 않습니다. 계정 데이터를 노출하기 전에 [대화 시작 웹훅](/docs/ko/eleven-agents/customization/personalization#conversation-initiation-webhooks), `secret__` 헤더 변수의 서명된 토큰 또는 검증 도구 호출을 통해 발신자 신원을 확인하세요. #### 테스트 및 미리보기를 위한 자리 표시자 구성 프롬프트, 첫 메시지, 도구에서 사용하는 모든 사용자 지정 변수에 대해 `dynamic_variable_placeholders`에 기본값을 설정하세요. 대시보드의 대화 미리보기와 [시뮬레이션 테스트](/docs/ko/eleven-agents/customization/agent-testing)는 대화 시작 웹훅을 실행하지 않으므로, 설정되지 않은 변수는 테스트 중 리터럴 `{{variable_name}}` 자리 표시자로 남습니다. ## 문제 해결 #### 변수가 대체되지 않음 다음을 확인하세요. * 변수 이름이 정확히 일치하는지 확인하세요(대소문자 구분) * 변수가 이중 중괄호를 사용하는지 확인하세요: `{{variable_name}}` * 변수가 `dynamic_variables` 객체에 포함되어 있는지 확인하세요 #### 유형 오류 다음을 확인하세요. * 변수 값이 예상 유형과 일치하는지 확인하세요 * 값이 문자열, 숫자 또는 불리언만으로 구성되는지 확인하세요