> 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. # エージェントのバージョン管理 エージェントのバージョン管理では、本番環境の設定を危険にさらすことなく、エージェントのさまざまな構成を試せます。分離されたブランチを作成し、変更をテストして、トラフィック比率によるデプロイで更新を段階的にロールアウトできます。 > **Note** > > A/Bテストを実施したい場合は、実トラフィックに対するエージェント変更の推奨テスト手順について、[実験](/docs/ja/eleven-agents/operate/experiments)を参照してください。 ## 概要 バージョン管理システムでは、次のことができます。 * 任意の時点におけるエージェント設定の **不変スナップショット** * 本番公開前に変更をテストするための **分離ブランチ** * 一部のユーザーに対して変更を段階的にロールアウトするための **トラフィック分割** * 任意のブランチから別の任意のブランチへ変更を反映する **マージ** * 最新のmainブランチの変更をブランチに取り込む **リベース** > **Note** > > エージェントでバージョン管理を有効にすると、無効には戻せません。既存のエージェントで > バージョン管理を有効にする前に、この点を考慮してください。 ## 基本概念 ### バージョン バージョンは、特定の時点におけるエージェント設定の不変スナップショットです。各バージョンには一意のID（形式：`agtvrsn_xxxx`）があり、次の内容を含みます。 * `conversation_config` - システムプロンプト、LLM設定、音声設定、ツール、ナレッジベース * `platform_settings` - 評価、ウィジェット、データ収集、セーフティ設定などを含む、バージョン管理対象のサブセット * `workflow` - ノードとエッジを含む完全なワークフロー定義 バージョン管理が有効なエージェントで変更を保存すると、バージョンが自動的に作成されます。作成後のバージョンは変更できません。 ### ブランチ ブランチは、gitブランチに似た名前付きの開発ラインです。mainブランチへマージする前に、変更を分離して作業できます。 * バージョン管理が有効なすべてのエージェントには、削除もアーカイブもできない **Main** ブランチがあります * 追加のブランチは、mainだけでなく、既存ブランチ上の任意のバージョンから作成できます * ブランチは任意の別ブランチにマージでき、main以外のブランチはmainにリベースして最新の変更を取り込めます * 各ブランチには、ID（`agtbrch_xxxx`）、名前、説明、バージョンの一覧があります * ブランチ名に使用できるのは、英字、数字、`() [] {} - / .`です（最大140文字） ### トラフィックデプロイ トラフィックは割合で複数のブランチに分割できるため、段階的なロールアウトやA/Bテストを実施できます。 * 割合の合計は常に **100%** でなければなりません * トラフィックルーティングは会話IDに基づく **決定論的** なものです（同じユーザーは常に同じブランチにルーティングされます） * アーカイブできるのは、トラフィックが0%の未アーカイブブランチのみです ### 下書き 未保存の変更は下書きとして保存されるため、すぐに新しいバージョンを作成せずに変更作業を進められます。 * 下書きは **ユーザーごと・ブランチごと** です（各チームメンバーが自身の下書きを持ちます） * 新しいバージョンをコミットすると、下書きは自動的に破棄されます * ブランチへのマージ時にも下書きは破棄されます ## バージョン管理を有効にする バージョン管理はオプトイン方式で、明示的に有効にする必要があります。新しいエージェントの作成時、または既存のエージェントで有効にできます。 > **Warning** > > 一度有効にすると、バージョン管理を無効にはできません。これはエージェントに対する恒久的な変更です。 ### エージェント作成時に有効にする #### ダッシュボードで有効化 ダッシュボードでエージェントを開き、**設定** に移動してバージョン管理を有効にします。有効にすると、ブランチ、下書き、バージョン、トラフィックデプロイを管理するための **バージョン管理** タブが利用可能になります。 #### APIで有効化 ```python from elevenlabs.client import ElevenLabs from elevenlabs.types import * client = ElevenLabs(api_key="your-api-key") agent = client.conversational_ai.agents.create( conversation_config=ConversationalConfig( agent=AgentConfig( first_message="Hello! How can I help you today?", prompt={"prompt": "You are a helpful assistant."}, ) ), enable_versioning=True ) print(f"Agent created with versioning: {agent.agent_id}") ``` ```javascript import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js'; const client = new ElevenLabsClient({ apiKey: 'your-api-key' }); const agent = await client.conversationalAi.agents.create({ conversationConfig: { agent: { firstMessage: 'Hello! How can I help you today?', prompt: { prompt: 'You are a helpful assistant.', }, }, }, enableVersioning: true, }); console.log(`Agent created with versioning: ${agent.agentId}`); ``` ### 既存のエージェントで有効にする #### ダッシュボードで有効化 ダッシュボードでエージェントを開き、**設定** に移動してバージョン管理をオンにします。 #### APIで有効化 ```python agent = client.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", enable_versioning_if_not_enabled=True ) ``` ```javascript const agent = await client.conversationalAi.agents.update('agent_7101k5zvyjhmfg983brhmhkd98n6', { enableVersioningIfNotEnabled: true, }); ``` バージョン管理を有効にすると、現在のエージェント設定を含む最初のバージョンとともに、初期の「Main」ブランチが作成されます。 ## ブランチを操作する ### ブランチを作成する ブランチはmainだけでなく、任意のブランチ上の任意のバージョンから作成できます。必要に応じて、新しいブランチの初期バージョンに適用する設定変更を含めることもできます。 ```python branch = client.conversational_ai.agents.branches.create( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", parent_version_id="agtvrsn_xxxx", name="experiment-v2", description="Testing new prompt and voice settings" ) print(f"Created branch: {branch.created_branch_id}") print(f"Initial version: {branch.created_version_id}") ``` ```javascript const branch = await client.conversationalAi.agents.branches.create('agent_7101k5zvyjhmfg983brhmhkd98n6', { parentVersionId: 'agtvrsn_xxxx', name: 'experiment-v2', description: 'Testing new prompt and voice settings', }); console.log(`Created branch: ${branch.createdBranchId}`); console.log(`Initial version: ${branch.createdVersionId}`); ``` ### ブランチを一覧表示する ```python branches = client.conversational_ai.agents.branches.list( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6" ) for branch in branches.branches: print(f"{branch.name}: {branch.id}") ``` ```javascript const branches = await client.conversationalAi.agents.branches.list('agent_7101k5zvyjhmfg983brhmhkd98n6'); for (const branch of branches.branches) { console.log(`${branch.name}: ${branch.id}`); } ``` ### ブランチの詳細を取得する ```python branch = client.conversational_ai.agents.branches.get( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx" ) print(f"Branch: {branch.name}") print(f"Versions: {len(branch.versions)}") ``` ```javascript const branch = await client.conversationalAi.agents.branches.get('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx'); console.log(`Branch: ${branch.name}`); console.log(`Versions: ${branch.versions.length}`); ``` ## 変更をコミットする バージョン管理が有効なエージェントを更新する際は、`branch_id`を指定して、そのブランチに新しいバージョンを作成します。 #### ダッシュボードで更新 エージェントの **バージョン管理** タブを開き、対象ブランチに切り替えて設定を編集し、保存して新しいバージョンを作成します。 #### CLIで更新 `--branch`フラグを指定すると、名前またはIDで特定のブランチにプッシュできます。ブランチは事前に作成されている必要があります。 ```bash elevenlabs agents push --agent "" --branch "" ``` #### APIで更新 ```python agent = client.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx", conversation_config=ConversationalConfig( agent=AgentConfig( prompt={"prompt": "You are a friendly customer support agent."}, ) ) ) ``` ```javascript const agent = await client.conversationalAi.agents.update( 'agent_7101k5zvyjhmfg983brhmhkd98n6', { conversationConfig: { agent: { prompt: { prompt: 'You are a friendly customer support agent.', }, }, }, }, { branchId: 'agtbrch_xxxx' } ); ``` 指定したブランチに新しいバージョンが自動的に作成され、そのブランチにおけるそのユーザーの既存の下書きは破棄されます。 ## トラフィックをデプロイする deploymentsエンドポイントを使用して、トラフィックをブランチ間に分配します。これにより、段階的なロールアウトとA/Bテストが可能になります。 ```python deployment = client.conversational_ai.agents.deployments.create( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", deployments=[ {"branch_id": "agtbrch_main", "percentage": 90}, {"branch_id": "agtbrch_xxxx", "percentage": 10} ] ) ``` ```javascript const deployment = await client.conversationalAi.agents.deployments.create('agent_7101k5zvyjhmfg983brhmhkd98n6', { deployments: [ { branchId: 'agtbrch_main', percentage: 90 }, { branchId: 'agtbrch_xxxx', percentage: 10 }, ], }); ``` > **Warning** > > すべての割合の合計は必ず100%にしてください。合計が100%でない場合、デプロイは失敗します。 トラフィックルーティングは会話IDに基づく決定論的なものです。そのため、セッションをまたいでも同じユーザーは常に同じブランチに到達します。 ## ブランチをマージする ブランチ上の変更に満足したら、別のブランチにマージします。mainへのマージに限らず、任意の未アーカイブブランチを別の任意の未アーカイブブランチにマージできます。 > **Note** > > マージ前にブランチの変更をレビューしたい場合、または書き込み権限のないブランチに変更を反映したい場合は、 > 直接マージする代わりに[マージ提案](/docs/ja/eleven-agents/operate/merge-proposals)を作成してください。 ```python merge = client.conversational_ai.agents.branches.merge( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", source_branch_id="agtbrch_xxxx", target_branch_id="agtbrch_main", archive_source_branch=True, # Default: true force=False # Default: false ) ``` ```javascript const merge = await client.conversationalAi.agents.branches.merge('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', { targetBranchId: 'agtbrch_main', archiveSourceBranch: true, // Default: true force: false, // Default: false }); ``` マージでは次の処理が行われます。 * ソースブランチの設定で、ターゲットブランチに新しいバージョンを作成します * 必要に応じてソースブランチをアーカイブします（デフォルト動作） * ソースブランチからターゲットブランチへトラフィックを自動的に移行します > **Note** > > ソースブランチがターゲットブランチから作成され（かつターゲットブランチ以降の新しいコミットがない）場合は、 > `no_new_changes_to_merge`でマージに失敗します。すでにそのターゲットにマージ済みの場合は、 > `branch_already_merged`で失敗します。 ### マージ競合を解決する 分岐後にソースブランチとターゲットブランチの両方で設定が変更されている場合、デフォルトではより最近更新されたブランチの値が保持されます。タイムスタンプに関係なく常にソースブランチの値を使用するには、`force=True`を設定します。 マージを確定する前に、上書きされる可能性があるフィールドを含め、マージ結果をプレビューできます。 ```python preview = client.conversational_ai.agents.branches.preview_merge( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", source_branch_id="agtbrch_xxxx", target_branch_id="agtbrch_main", force=False ) print(preview.overridden_fields) print(preview.conflicts) ``` ```javascript const preview = await client.conversationalAi.agents.branches.previewMerge('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', { targetBranchId: 'agtbrch_main', force: false, }); console.log(preview.overriddenFields); console.log(preview.conflicts); ``` ## ブランチをmainにリベースする リベースでは、git rebaseと同様に、mainブランチの最新変更を別のブランチに取り込みます。これにより、ブランチ自体の変更をまだマージバックせずに、長期間使用するブランチをmainの最新状態に保てます。 ```python client.conversational_ai.agents.branches.rebase( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx" ) ``` ```javascript await client.conversationalAi.agents.branches.rebase('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx'); ``` リベースでは次の処理が行われます。 * mainの最新変更を取り込んだ新しいバージョンをブランチに作成します * ブランチ固有の変更を保持します。ブランチとmainの両方で設定が編集されている場合、常にブランチ側の値が保持されます * ブランチにmainのすべての変更がすでに含まれている場合、`branch_already_up_to_date`で失敗します > **Note** > > リベースできるのはmain以外のブランチのみで、リベース先はmainに限られます。mainブランチ自体を > リベースすると、`cannot_rebase_main`エラーが返されます。 確定する前にリベース結果をプレビューできます。 ```python preview = client.conversational_ai.agents.branches.preview_rebase( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx" ) print(preview.overridden_fields) ``` ```javascript const preview = await client.conversationalAi.agents.branches.previewRebase('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx'); console.log(preview.overriddenFields); ``` ## ブランチをアーカイブする 不要になったブランチをアーカイブします。これにより、ブランチ一覧を整理できます。 ```python client.conversational_ai.agents.branches.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx", archived=True ) ``` ```javascript await client.conversationalAi.agents.branches.update('agent_7101k5zvyjhmfg983brhmhkd98n6', 'agtbrch_xxxx', { archived: true, }); ``` > **Warning** > > トラフィックが割り当てられているブランチはアーカイブできません。アーカイブする前に、すべてのトラフィックを削除してください。 `archived=False`を設定すると、アーカイブ済みブランチを復元できます。 ## バージョン管理されたエージェントを複製する エージェントを複製すると、mainブランチだけでなく、ソースエージェントのすべての未アーカイブブランチのコピーを含む新しいエージェントが作成されます。 ```python duplicate = client.conversational_ai.agents.duplicate( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", name="Copy of my agent" ) print(duplicate.agent_id) ``` ```javascript const duplicate = await client.conversationalAi.agents.duplicate('agent_7101k5zvyjhmfg983brhmhkd98n6', { name: 'Copy of my agent', }); console.log(duplicate.agentId); ``` 複製されたエージェントでは、次のようになります。 * mainブランチは、ソースエージェントのmainブランチにおける最新バージョンから作成されます * その他の未アーカイブブランチは、同じ名前と説明で再作成され、それぞれのブランチの最新バージョンから開始します * バージョン履歴はコピーされないため、各ブランチは単一のバージョンで開始します * アーカイブ済みブランチと下書きはコピーされません * トラフィックデプロイはコピーされないため、他のブランチに[トラフィックをデプロイ](#deploying-traffic)するまで、すべてのトラフィックはmainブランチに送られます 複製先のブランチIDとバージョンIDは新しく作成されるため、ソースエージェントのIDへの参照を更新してください。 ## 特定のバージョンを取得する 特定のバージョンまたはブランチの先端にあるエージェントを取得できます。 ### 特定のバージョンのエージェントを取得する ```python agent = client.conversational_ai.agents.get( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", version_id="agtvrsn_xxxx" ) ``` ```javascript const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', { versionId: 'agtvrsn_xxxx', }); ``` ### ブランチ先端のエージェントを取得する ```python agent = client.conversational_ai.agents.get( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx" ) ``` ```javascript const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', { branchId: 'agtbrch_xxxx', }); ``` ### 下書きの変更を含める ```python agent = client.conversational_ai.agents.get( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbrch_xxxx", include_draft=True ) ``` ```javascript const agent = await client.conversationalAi.agents.get('agent_7101k5zvyjhmfg983brhmhkd98n6', { branchId: 'agtbrch_xxxx', includeDraft: true, }); ``` ## 設定リファレンス ### バージョン管理対象の設定 これらの設定は、バージョンやブランチごとに異なる場合があります。 | カテゴリー | 設定 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **会話設定** | システムプロンプト、エージェントのパーソナリティ、LLMの選択とパラメーター、音声設定（TTSモデル、音声ID）、ツール設定、ナレッジベース、最初のメッセージ、言語設定、ターン検出、割り込み設定 | | **バージョン管理対象のプラットフォーム設定** | `evaluation` - 評価基準、`widget` - ウィジェットの外観と動作、`data_collection` - 構造化データの抽出、`overrides` - 会話開始の上書き設定、`workspace_overrides` - webhook設定、`testing` - テスト設定、`safety` - ガードレール（IVC／非IVC設定） | | **ワークフロー** | 完全なワークフロー定義（ノードとエッジ） | ### エージェント単位の設定 これらの設定はバージョンではなくエージェントに属するため、すべてのブランチで共有されます。 | 設定 | 説明 | | --------------------------------------- | ---------------------------- | | `name`, `tags` | エージェント名とタグ | | `auth` | 認証設定と許可リスト | | `call_limits` | 同時実行数と1日の上限 | | `queueing_config` | 同時実行数の上限を超えた発信者向けの待機キューと保留音声 | | `privacy` | 保持設定、保持なしモード、ユーザーメモリー | | `analysis_llm` | 通話後分析に使用するLLM | | `topic_discovery`, `sentiment_analysis` | エージェントレベルの分析設定 | | `simulation_library` | シミュレーションライブラリの設定 | | `alerting` | アラートwebhookとモニターしきい値 | | `ban` | BANステータス（管理者のみ） | > **Warning** > > エージェント単位の設定はmainブランチでのみ変更できます。他のブランチではダッシュボード上で > 読み取り専用として表示され、main以外のブランチにバージョンを公開すると、それらに対する変更は破棄されます。 > その後ブランチをmainにマージしても、これらの変更は適用されません。変更するにはmainブランチに切り替えてください。 > そこで公開すると、変更はすべてのブランチに適用されます。 ## ベストプラクティス #### ブランチ作成前にテストを作成する 新しいブランチを作成する前に、想定される動作を捉える[自動テスト](/docs/ja/eleven-agents/customization/agent-testing)を 設定してください。これによりベースラインを確立し、実験を繰り返す際に 早期にリグレッションを検出できます。 #### わかりやすいブランチ名を使用する 実験の目的が明確に伝わるブランチ名を選びます。参照しやすいように、機能名、仮説、チケット番号を 含めてください（例：`feature/new-greeting-flow`、 `experiment/shorter-responses`）。 #### ブランチの目的を記録する ブランチの説明フィールドを使用して、テストする仮説、成功を判断する指標、依存関係や考慮事項を 説明します。これにより、チームメンバーが進行中の実験を把握しやすくなります。 #### 進行中の作業には下書きを使用する 変更を繰り返す間は、下書きをこまめに保存してください。これにより不要なバージョンを作成せずに 作業を保存できます。テストまたはデプロイの準備ができたときだけコミットしてください。 #### 少ないトラフィック比率から開始する 新しいブランチをデプロイする際は、トラフィックの5～10%から始めます。これにより、意味のあるデータを得ながら 問題が発生した場合の影響を抑えられます。 #### トラフィックを増やす前に主要指標を監視する [分析ダッシュボード](/docs/ja/eleven-agents/dashboard)を使用して、ブランチのパフォーマンスを比較します。 通話完了率、平均会話時間、成功評価スコア、 ツール実行率を確認してください。指標がmainブランチの ベースラインを満たす、または上回る場合にのみトラフィックを増やします。 #### トラフィックを段階的に増やす 確信が高まるにつれて、段階的にトラフィックを増やします（10% → 25% → 50% → 100%）。この方法では、 各段階でパフォーマンスを検証しながらリスクを最小限に抑えられます。 #### ブランチを長期間維持しない 設定の乖離を避けるため、成功した実験は速やかにマージしてください。より長く 開いたままにする必要があるブランチは、定期的にmainへリベースして、大きく乖離して マージが困難にならないようにします。 ## 次のステップ #### [実験](/docs/ja/eleven-agents/operate/experiments) ブランチとトラフィックデプロイを使ってA/Bテストを実施 #### [テスト](/docs/ja/eleven-agents/customization/agent-testing) エージェントのバージョン用に自動テストを設定 #### [分析](/docs/ja/eleven-agents/dashboard) 異なるブランチ間のパフォーマンスを監視 #### [CLI](/docs/ja/eleven-agents/operate/cli) コマンドラインからバージョン管理