動的変数

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

概要

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

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

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

• ユーザー名を使った挨拶のパーソナライズ
• 応答へのアカウント詳細の追加
• ツール呼び出しへのデータの受け渡し
• サブスクリプションプランに応じた動作のカスタマイズ
• 会話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__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__を付けます。

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

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

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

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

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

割り当ては各Webhookツールのフィールドであり、こちらに記載されています。

ガイド

前提条件

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

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は”Jane”（Base64エンコードされたvarsから）ではなく、“John”（var_user_nameから）になります。

実装例

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

サポートされる型

動的変数では、以下の値の型がサポートされています：

トラブルシューティング