> 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や通話時間などの **システム情報へのアクセス** > **Info** > > 動的変数は、エージェントの設定にハードコードすべきではないユーザー固有のデータを挿入するのに最適です。 ## システム動的変数 エージェントでは、以下のシステム変数を自動的に利用できます。 * `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` - 現在のサブエージェントが行った会話ターン数。ワークフローが別のノードに移行するたびにリセットされます。 * `system__is_text_only` - 会話がテキストのみモードで動作している場合はtrue、それ以外の場合はfalse。 * `system__conversation_history` - 現在の会話履歴をJSON形式でシリアライズした表現。参照された時点で遅延評価されます。以下の [形式の詳細](#conversation-history-format) を参照してください。 システム変数は次のとおりです。 * 実行時の設定なしで利用可能 * `system__`（予約済みプレフィックス）で始まる * 会話中に自動で更新される > **Warning** > > カスタム動的変数には、予約済みの `system__` プレフィックスを使用できません。 ### 会話履歴の形式 `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)]`）に置き換えられます。 この変数は、会話コンテキストをツール（例：Webhook、カスタムLLM）に渡したり、引き継ぎ時にサブエージェントのプロンプトに会話履歴を含めたりする際に便利です。 ## シークレット動的変数 シークレット動的変数は通常の動的変数と同じ方法で設定されますが、エージェントのシステムプロンプトや最初のメッセージの一部としてLLMプロバイダーに送信せず、動的変数ヘッダーでのみ使用するようElevenAgentsに指示します。 LLMに送信すべきではない認証トークンや非公開IDには、これらを使用することをおすすめします。シークレット動的変数を作成するには、動的変数に `secret__` を付けるだけです。 > **Warning** > > シークレット値は、通話後のWebhookや会話APIを含め、`` としてマスキングされて返されます。会話後に読み戻す必要がある値には、`secret__` プレフィックスを使用しないでください。そうした値は通常の動的変数として渡すか、機密性のない識別子を渡して、ご自身のシステムで機密値を検索してください。 ## ツールから動的変数を更新する [ツール呼び出し](https://elevenlabs.io/docs/eleven-agents/customization/tools) は、有効なJSONオブジェクトを返す場合、動的変数を作成または更新できます。抽出する内容を指定するには、ドット記法でオブジェクトパスを設定します。フィールドまたはパスが存在しない場合は、何も更新されません。 レスポンスオブジェクトとドット記法の例： * Statusは次のパスに対応します：`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-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp) 割り当ては各Webhookツールのフィールドです。詳細は[こちら](/docs/ja/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments)を参照してください。 ## ガイド ### 前提条件 * [ElevenLabsアカウント](https://elevenlabs.io) * 設定済みのElevenLabs会話型エージェント（[こちらで作成](/docs/ja/eleven-agents/quickstart)） #### プロンプトで動的変数を定義 システムプロンプト、最初のメッセージ、ツールパラメータに、二重波括弧 `{{variable_name}}` を使って変数を追加します。 ![メッセージ内の動的変数](/docs/_fern-img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp) ![メッセージ内の動的変数](/docs/_fern-img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp) #### ツールで動的変数を定義 ツール設定でも動的変数を定義できます。 新しい動的変数を作成するには、値のタイプを「Dynamic variable」に設定し、`+` ボタンをクリックします。 ![プレースホルダーの設定](/docs/_fern-img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp) ![プレースホルダーの設定](/docs/_fern-img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp) #### プレースホルダーを設定 実行時に変数を渡さずにテストするためのデフォルト値を設定します。 #### ダッシュボードで更新 エージェントのダッシュボードで、各動的変数のデフォルト値を設定します。 ![プレースホルダーの設定](/docs/_fern-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/ja/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(), # 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()) ``` **`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_id_goes_here', // Replace with your actual agent ID 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="ウィジェット" ``` ## 公開Talk-toページのインテグレーション 公開Talk-toページではURLパラメータによる動的変数に対応しており、エージェントリンクを共有する際に会話をパーソナライズできます。これは、パーソナライズされたエージェントをWebサイト、メール、マーケティングキャンペーンに埋め込む場合に特に便利です。 ### URLパラメータの方法 公開Talk-toページに動的変数を渡すには、次の2つの方法があります。 #### 方法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 ``` ## 対応する型 動的変数では、次の値の型をサポートしています。 #### 文字列 テキスト値 #### 数値 数値 #### ブール値 true／false値 ## トラブルシューティング #### 変数が置き換えられない 次を確認してください。 * 変数名が完全に一致している（大文字・小文字を区別） * 変数に二重波括弧を使用している：`{{ variable_name }}` * 変数がdynamic_variablesオブジェクトに含まれている #### 型エラー 次を確認してください。 * 変数の値が想定される型と一致している * 値が文字列、数値、またはブール値のみである