動的変数

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

概要

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

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

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

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

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

システム動的変数

エージェントは、実行時の設定なしで、すべての会話で組み込みの 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)] など）に置き換えられます。

この変数は、会話コンテキストをツール（Webhookやカスタム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"
      }
    ]
  }
}

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

割り当てはWebhookツールごとに設定します。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パラメータの方法

公開通話ページに動的変数を渡す方法は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);

ベストプラクティス

トラブルシューティング