エージェントのバージョン管理

エージェントのバージョン管理では、本番環境の設定を危険にさらすことなく、エージェントのさまざまな構成を試せます。分離されたブランチを作成し、変更をテストして、トラフィック比率によるデプロイで更新を段階的にロールアウトできます。

概要

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

• 任意の時点におけるエージェント設定の 不変スナップショット
• 本番公開前に変更をテストするための 分離ブランチ
• 一部のユーザーに対して変更を段階的にロールアウトするための トラフィック分割
• 任意のブランチから別の任意のブランチへ変更を反映する マージ
• 最新のmainブランチの変更をブランチに取り込む リベース

基本概念

バージョン

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

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

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

ブランチ

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

• バージョン管理が有効なすべてのエージェントには、削除もアーカイブもできない 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を指定して、そのブランチに新しいバージョンを作成します。

指定したブランチに新しいバージョンが自動的に作成され、そのブランチにおけるそのユーザーの既存の下書きは破棄されます。

トラフィックをデプロイする

deploymentsエンドポイントを使用して、トラフィックをブランチ間に分配します。これにより、段階的なロールアウトと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を設定すると、アーカイブ済みブランチを復元できます。

バージョン管理されたエージェントを複製する

エージェントを複製すると、mainブランチだけでなく、ソースエージェントのすべての未アーカイブブランチのコピーを含む新しいエージェントが作成されます。

duplicate = client.conversational_ai.agents.duplicate(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    name="Copy of my agent"
)
print(duplicate.agent_id)

複製されたエージェントでは、次のようになります。

• mainブランチは、ソースエージェントのmainブランチにおける最新バージョンから作成されます
• その他の未アーカイブブランチは、同じ名前と説明で再作成され、それぞれのブランチの最新バージョンから開始します
• バージョン履歴はコピーされないため、各ブランチは単一のバージョンで開始します
• アーカイブ済みブランチと下書きはコピーされません
• トラフィックデプロイはコピーされないため、他のブランチにトラフィックをデプロイするまで、すべてのトラフィックはmainブランチに送られます

複製先のブランチIDとバージョンIDは新しく作成されるため、ソースエージェントのIDへの参照を更新してください。

特定のバージョンを取得する

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

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

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
)

設定リファレンス

バージョン管理対象の設定

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

エージェント単位の設定

これらの設定はバージョンではなくエージェントに属するため、すべてのブランチで共有されます。

ベストプラクティス

次のステップ