オーバーライド

ユーザーごとにパーソナライズされたコンテキストを使い、会話を最適化します。

システムプロンプトや最初のメッセージを完全に置き換える場合は、引き続きオーバーライドを使用できますが、エージェントの応答のカスタマイズやリアルタイムデータの挿入には、動的変数の使用を推奨します。動的変数を使うと、保守性が向上し、より体系的にパーソナライズできます。

オーバーライド を使用すると、ユーザーとのやり取りごとにアシスタントの動作を調整できます。各会話の開始時にカスタムデータや設定を渡すことで、リアルタイムのコンテキストに基づいてアシスタントの応答や知識をパーソナライズできます。オーバーライドを指定すると、エージェントのダッシュボードで定義されたデフォルト値が完全に上書きされます。

概要

オーバーライドを使用すると、複数のエージェントを作成せずに、AIエージェントの動作をリアルタイムで変更できます。これにより、ユーザー固有のデータを使って応答をパーソナライズできます。

エージェントのセキュリティ設定では、次のフィールドに対してオーバーライドを有効にできます。

システムプロンプト
最初のメッセージ
言語
音声ID
LLM（大規模言語モデル）
LLMの推論量
ツール
ナレッジベース
テキスト専用モード
安定性
速度
類似度ブースト
ASRキーワード
プロシージャ

プロシージャ のオーバーライドでは、conversation_config_overrideを使用しません。代わりに、クライアントは会話開始時のクライアントデータのトップレベルでprocedure_idsとstart_procedure_idsを渡します。会話ごとにプロシージャを選択するを参照してください。

フィールドのオーバーライドを有効にしても、オーバーライドの指定は任意です。指定しない場合、エージェントのダッシュボードで定義されたデフォルト値が使用されます。ほとんどのフィールドでは、オーバーライドが有効になっていないフィールドにオーバーライドを指定するとエラーが発生します。

ASRキーワード では緩やかな拒否が適用されます。セキュリティの切り替えがオフの状態でクライアントが asr.keywordsを送信しても、会話は続行され、キーワードは無視されます（エラーは発生しません）。会話ごとのキーワードブーストを適用するには、セキュリティ設定で ASRキーワード のオーバーライドを有効にしてください。1回の会話につき最大50個のキーワードを使用できます。

推論量 は、エージェントのLLMがサポートするレベルに設定する必要があります。サポートされていない場合、会話は開始されず、該当するレベルを示すエラーとともに接続が終了します。セキュリティの切り替えがオフの場合、 prompt.reasoning_effortは無視され、エージェントに保存された推論量が使用されます。この値は会話全体で固定され、会話の開始後は変更できません。

オーバーライドは、たとえば次のような場合に役立ちます。

ユーザーの名前を使って 挨拶する
応答に アカウント固有の情報を含める
ユーザー設定に基づいて エージェントの言語 や口調を調整する
口座残高や注文状況などの リアルタイムデータを渡す
ASRキーワードを使用し、通話ごとの名前や用語（CRMに登録された会社名など）の 文字起こし精度を高める

オーバーライドは、やり取りのパーソナライズが必要なアプリケーションや、エージェントの基本設定に保存すべきでない機密性の高いユーザーデータを扱う場合に特に便利です。

ガイド

前提条件

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

このガイドでは、エージェントのデフォルトの システムプロンプト、最初のメッセージ、LLM、推論量、ツール、ナレッジベース、TTS設定、ASRキーワード をオーバーライドする方法を説明します。

オーバーライドを有効にする

セキュリティ上の理由から、オーバーライドはデフォルトで無効になっています。first_message、prompt.prompt、prompt.reasoning_effort、prompt.tool_ids、prompt.knowledge_base、language、asr.keywordsなど、オーバーライドを許可するフィールドを有効にしてください。

ダッシュボードから更新

CLIから更新

APIから更新

エージェントの設定に移動し、セキュリティ タブを選択します。最初のメッセージ、システムプロンプト、ツール、ナレッジベース、ASRキーワードに加え、LLMや推論量など、必要なオーバーライドを有効にします。

会話をオーバーライドする

コード内で会話を開始する際に、オーバーライドをパラメーターとして渡します。ツールとナレッジベースのオーバーライドは、その会話のデフォルト配列を置き換えます。ASRキーワードのオーバーライドは、その会話におけるエージェントのデフォルトのキーワードリストを置き換えます（最大50個）。

会話開始ペイロード

{
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "reasoning_effort": "high",
        "tool_ids": ["tool_7101k5zvyjhmfg983brhmhkd98n6"],
        "knowledge_base": [
          {
            "type": "file",
            "name": "Unladen Swallow Facts",
            "id": "5xM3yVvZQKV0EfqQpLrJ",
            "usage_mode": "auto"
          }
        ]
      }
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso", "Globex"]
    }
  }
}

最新のSDKがインストールされていることを確認してください。

from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
...
conversation_override = {
    "agent": {
        "prompt": {
            "prompt": f"The customer's bank account balance is {customer_balance}. They are based in {customer_location}.", # Optional: override the system prompt.
            "llm": "gpt-4o", # Optional: override the LLM model.
            "reasoning_effort": "high", # Optional: override the reasoning effort. Requires Security → Reasoning effort.
            "tool_ids": [
                "tool_7101k5zvyjhmfg983brhmhkd98n6"
            ], # Optional: replace the tools available to the agent.
            "knowledge_base": [
                {
                    "type": "file",
                    "name": "Unladen Swallow Facts",
                    "id": "5xM3yVvZQKV0EfqQpLrJ",
                    "usage_mode": "auto",
                }
            ], # Optional: replace the knowledge base available to the agent.
        },
        "first_message": f"Hi {customer_name}, how can I help you today?", # Optional: override the first_message.
        "language": "en" # Optional: override the language.
    },
    "tts": {
        "voice_id": "custom_voice_id", # Optional: override the voice.
        "stability": 0.7, # Optional: override stability (0.0 to 1.0).
        "speed": 1.1, # Optional: override speed (0.7 to 1.2).
        "similarity_boost": 0.9 # Optional: override similarity boost (0.0 to 1.0).
    },
    "conversation": {
        "text_only": True # Optional: enable text-only mode (no audio).
    },
    "asr": {
        "keywords": ["Acme Corp", "Contoso"] # Optional: boost ASR for per-call terms (max 50). Requires Security → ASR keywords.
    }
}
config = ConversationInitiationData(
    conversation_config_override=conversation_override
)
conversation = Conversation(
    ...
    config=config,
    ...
)
conversation.start_session()

オーバーライドを使用する場合、上書きしないフィールドには空文字列やnull値を設定せず、そのフィールド自体を省略してください。カスタマイズするフィールドだけを含めます。

正しいLLMモデル文字列を確認するには、サポートされているすべてのLLMモデルと正確な文字列識別子が記載されたエージェントAPIリファレンスを参照してください。