動的変数

実行時の値を渡して、エージェントの動作をパーソナライズします。

動的変数 を使用すると、実行時の値をエージェントのメッセージ、システムプロンプト、ツールに挿入できます。複数のエージェントを作成せずに、ユーザー固有のデータで各会話をパーソナライズできます。

概要

動的変数は、エージェントのさまざまな要素に組み込めます。

動作やコンテキストをカスタマイズする システムプロンプト
挨拶をパーソナライズする 最初のメッセージ
ユーザー固有のデータを渡す ツールのパラメータとヘッダー

動的変数が役立つ例をいくつか紹介します。

ユーザー名を使った 挨拶のパーソナライズ
応答への アカウント情報の追加
ツール呼び出しへの データの受け渡し
サブスクリプションのプランに応じた 動作のカスタマイズ
会話IDや通話時間などの システム情報へのアクセス

動的変数は、エージェントの設定にハードコードすべきではないユーザー固有のデータを挿入するのに最適です。

システム動的変数

エージェントでは、以下のシステム変数を自動的に利用できます。

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形式でシリアライズした表現。参照された時点で遅延評価されます。以下の形式の詳細を参照してください。

システム変数は次のとおりです。

実行時の設定なしで利用可能
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)]）に置き換えられます。

この変数は、会話コンテキストをツール（例：Webhook、カスタムLLM）に渡したり、引き継ぎ時にサブエージェントのプロンプトに会話履歴を含めたりする際に便利です。

シークレット動的変数

シークレット動的変数は通常の動的変数と同じ方法で設定されますが、エージェントのシステムプロンプトや最初のメッセージの一部としてLLMプロバイダーに送信せず、動的変数ヘッダーでのみ使用するようElevenAgentsに指示します。

LLMに送信すべきではない認証トークンや非公開IDには、これらを使用することをおすすめします。シークレット動的変数を作成するには、動的変数に secret__ を付けるだけです。

シークレット値は、通話後のWebhookや会話APIを含め、<REDACTED> としてマスキングされて返されます。会話後に読み戻す必要がある値には、secret__ プレフィックスを使用しないでください。そうした値は通常の動的変数として渡すか、機密性のない識別子を渡して、ご自身のシステムで機密値を検索してください。

ツールから動的変数を更新する

ツール呼び出しは、有効なJSONオブジェクトを返す場合、動的変数を作成または更新できます。抽出する内容を指定するには、ドット記法でオブジェクトパスを設定します。フィールドまたはパスが存在しない場合は、何も更新されません。

レスポンスオブジェクトとドット記法の例：

Statusは次のパスに対応します：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"
      }
    ]
  }
}

動的変数を最初のユーザーのメールアドレスに更新するには、次のように割り当てを設定します。

割り当ては各Webhookツールのフィールドです。詳細はこちらを参照してください。

ガイド

前提条件

ElevenLabsアカウント
設定済みのElevenLabs会話型エージェント（こちらで作成）

プロンプトで動的変数を定義

システムプロンプト、最初のメッセージ、ツールパラメータに、二重波括弧 {{variable_name}} を使って変数を追加します。

ツールで動的変数を定義

ツール設定でも動的変数を定義できます。新しい動的変数を作成するには、値のタイプを「Dynamic variable」に設定し、+ ボタンをクリックします。

プレースホルダーを設定

実行時に変数を渡さずにテストするためのデフォルト値を設定します。

ダッシュボードで更新

CLIで更新

APIで更新

エージェントのダッシュボードで、各動的変数のデフォルト値を設定します。

実行時に変数を渡す

会話を開始する際に、コード内で動的変数を指定します。

最新バージョンの 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(),
    # 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())

公開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が含まれます。

{ "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生成

PythonでのURL生成

手動でのURL構築

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

対応する型

動的変数では、次の値の型をサポートしています。

文字列

テキスト値

数値

ブール値

true／false値

トラブルシューティング

変数が置き換えられない

次を確認してください。

変数名が完全に一致している（大文字・小文字を区別）
変数に二重波括弧を使用している：{{ variable_name }}
変数がdynamic_variablesオブジェクトに含まれている

型エラー

次を確認してください。

変数の値が想定される型と一致している
値が文字列、数値、またはブール値のみである