エージェントのバージョニング

エージェントのバージョニングでは、本番環境の設定にリスクを与えずに、エージェントのさまざまな構成を試せます。分離されたブランチを作成し、変更をテストして、トラフィックの割合によるデプロイで更新を段階的に展開できます。

概要

バージョニングシステムでは、次のことができます。

• 任意の時点におけるエージェント構成の不変スナップショット
• 本番環境に移行する前に変更をテストするための分離されたブランチ
• 一部のユーザーに対して段階的に変更を展開するためのトラフィック分割
• 任意のブランチから別のブランチへ変更を反映するマージ
• 最新のメインブランチの変更をブランチに取り込むリベース

基本概念

バージョン

バージョンは、特定の時点におけるエージェント構成の不変スナップショットです。各バージョンには一意のID（形式：agtvrsn_xxxx）があり、次の内容を含みます。

• conversation_config - システムプロンプト、LLM設定、音声設定、ツール、ナレッジベース
• platform_settings - 評価、ウィジェット、データ収集、セーフティ設定を含む、バージョン管理対象のサブセット
• workflow - ノードとエッジを含む完全なワークフロー定義

バージョン管理対象のエージェントへの変更を保存すると、バージョンは自動的に作成されます。作成後のバージョンは変更できません。

ブランチ

ブランチは、gitのブランチに似た、名前付きの開発ラインです。メインブランチにマージして戻す前に、変更を分離して作業できます。

• すべてのバージョン管理対象エージェントには、削除またはアーカイブできないMainブランチがあります
• 追加のブランチは、mainだけでなく、既存の任意のブランチ上の任意のバージョンから作成できます
• ブランチは任意の別のブランチにマージでき、main以外のブランチはmainにリベースして最新の変更を取り込めます
• 各ブランチには、ID（agtbrch_xxxx）、名前、説明、バージョンのリストがあります
• ブランチ名には、英字、数字、（） [] {} - / .を使用できます（最大140文字）

トラフィックデプロイ

トラフィックは割合により複数のブランチへ分割でき、段階的な展開とA/Bテストを可能にします。

• 割合の合計は常に正確に**100%**である必要があります
• トラフィックルーティングは会話IDに基づく決定論的なものです（同じユーザーは一貫して同じブランチにルーティングされます）
• アーカイブできるのは、トラフィックが0%のアーカイブされていないブランチのみです

下書き

未保存の変更は下書きとして保存されるため、すぐに新しいバージョンを作成せずに変更作業を行えます。

• 下書きはユーザーごと、ブランチごとです（各チームメンバーは自分の下書きを持ちます）
• 新しいバージョンがコミットされると、下書きは自動的に破棄されます
• ブランチにマージするときも、下書きは破棄されます

バージョニングを有効にする

バージョニングはオプトインで、明示的に有効にする必要があります。新しいエージェントの作成時、または既存のエージェントで有効にできます。

エージェント作成時に有効にする

既存のエージェントで有効にする

バージョニングを有効にすると、現在のエージェント設定を含む最初のバージョンとともに、初期の「Main」ブランチが作成されます。

ブランチを操作する

ブランチを作成する

ブランチは、mainだけでなく、任意のブランチ上の任意のバージョンから作成できます。新しいブランチの初期バージョンに適用する構成変更を、任意で含めることもできます。

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}")

ブランチを一覧表示する

branches = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

ブランチの詳細を取得する

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)}")

変更のコミット

バージョニングを有効にしたエージェントを更新する場合は、branch_idを指定してそのブランチに新しいバージョンを作成します。

指定したブランチには新しいバージョンが自動的に作成され、そのブランチ上のそのユーザーの既存ドラフトは破棄されます。

トラフィックのデプロイ

デプロイメントエンドポイントを使用して、ブランチ間にトラフィックを分配します。段階的なロールアウトやA/Bテストを実施できます。

deployment = client.conversational_ai.agents.deployments.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    deployments=[
        {"branch_id": "agtbrch_main", "percentage": 90},
        {"branch_id": "agtbrch_xxxx", "percentage": 10}
    ]
)

トラフィックルーティングは会話IDに基づいて決定されるため、同じユーザーはセッションをまたいでも一貫して同じブランチに接続されます。

ブランチのマージ

ブランチ上の変更に問題がなければ、別のブランチにマージします。アーカイブされていないブランチは、mainだけでなく、他の任意のアーカイブされていないブランチにマージできます。

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
)

マージすると、次の処理が行われます。

• ソースブランチの設定で、ターゲットブランチに新しいバージョンを作成します
• 必要に応じてソースブランチをアーカイブします（デフォルトの動作）
• ソースブランチからターゲットブランチへトラフィックを自動的に移行します

マージ競合の解決

分岐後にソースブランチとターゲットブランチの両方で設定が変更されている場合、デフォルトではより最近更新されたブランチの値が保持されます。タイムスタンプにかかわらず常にソースブランチの値を使用するには、force=Trueを設定します。

マージを確定する前に、上書きされるフィールドを含むマージ結果をプレビューします。

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)

ブランチをmainにリベース

リベースでは、git rebaseと同様に、mainブランチの最新の変更を別のブランチに取り込みます。これにより、ブランチ自身の変更をまだマージバックせずに、長期間使用するブランチをmainと最新の状態に保てます。

client.conversational_ai.agents.branches.rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

リベースすると、次の処理が行われます。

• mainの最新の変更を取り込んだ新しいバージョンをブランチに作成します
• ブランチ自身の変更を保持します。ブランチとmainの両方で設定が編集されている場合は、常にブランチの値が保持されます
• ブランチにmainのすべての変更がすでに含まれている場合は、branch_already_up_to_dateで失敗します

確定する前にリベース結果をプレビューします。

preview = client.conversational_ai.agents.branches.preview_rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
print(preview.overridden_fields)

ブランチのアーカイブ

不要になったブランチをアーカイブします。ブランチリストを整理しやすくなります。

client.conversational_ai.agents.branches.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    archived=True
)

archived=Falseを設定すると、アーカイブ済みのブランチを復元できます。

特定バージョンの取得

特定のバージョンまたはブランチの先端にあるエージェントを取得できます。

特定バージョンのエージェントを取得

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    version_id="agtvrsn_xxxx"
)

ブランチ先端のエージェントを取得

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

ドラフトの変更を含める

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    include_draft=True
)

設定リファレンス

バージョン管理される設定

これらの設定は、バージョンやブランチごとに異なる場合があります。

エージェント単位の設定

これらの設定はすべてのバージョンで共有されます。

ベストプラクティス

次のステップ