For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション

おすすめ

Agents API

Agents SDK

ChatKit

API Dashboard
ChatGPT を試す

マルチエージェント

エージェントから独立したサブエージェントに作業を委任できます。

マルチエージェントでは、エージェントがサブエージェントにタスクを委任できます。各サブエージェントは独自のコンテキストを持ち、他のサブエージェントと並行して作業できます。メインエージェントは各サブエージェントの作業を調整し、結果をまとめます。

サブエージェントの利用場面

別々のドキュメントのレビューや、障害の原因を異なる観点から調査するなど、独立したタスクにサブエージェントを使用します。各タスクで明らかにすべき問いと、期待する結果を明確に指定してください。

短いタスクや依存関係のある手順は、メインエージェントで処理します。同じファイルを編集するエージェント同士は、変更内容を調整する必要があります。

マルチエージェントオーケストレーションの有効化

セッションの作成時に、agent.multi_agent.enabled を true に設定します。ハーネスは、サブエージェントの作成、メッセージ送信、待機、中断を行うツールを提供します。これらのツールを自分で宣言する必要はありません。

次の例では、2 つのサブエージェントにそれぞれ別のリリースノートのレビューを依頼し、その結果をまとめます。環境の用意やツールの設定は不要です。

リリースノートの比較
from openai import OpenAI

client = OpenAI()

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Delegate each release to a separate subagent. Ask each to extract customer-visible changes and required migration steps using only its release notes. Wait for both results, then combine them into one release summary with release labels. Do not invent missing details.",
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 2},
    },
    environment={"type": "none"},
    input="Release A: Search now supports filtering by date. Existing queries continue to work. Release B: The export endpoint now returns a download URL instead of file bytes. Update clients to fetch that URL.",
    stream=True,
) as events:
    for event in events:
        print(event.model_dump_json())

environment.type: "none" を使用する場合は、作成リクエストに最初の input を含めます。stream: true を設定すると、最初のターンもストリーミングされます。ストリームの処理と復旧については、セッションのイベントとアイテムを参照してください。

同時実行数の設定

max_concurrent_subagents は、同時に実行できるサブエージェントの数を制限します。デフォルトは、コーディネーターを除いて 6 です。委任を有効にする場合は、正の整数を設定してください。

委任を無効にするには、multi_agent を省略するか、enabled を false に設定して上限を省略します。これらの設定はセッションの作成時に適用されます。保存済みエージェントへの変更は、新しいセッションに適用されます。

環境の利用

エージェントがファイルやコマンドの実行を必要とする場合は、環境を追加します。コーディネーターとサブエージェントは、その環境のファイルシステムを共有します。サブエージェントを作成しても、別の環境は作成されません。

次の例では、独自の環境で作業するためのセッションを作成します。

独自の環境での委任の有効化
const result = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Prepare release notes from the repository. Have one subagent identify customer-visible changes and another check migration guides and examples, then combine their findings.",
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 3,
    },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
  },
});

返されたセッション ID と環境 ID をアプリケーションに保存します。環境を接続してから、入力を送信して作業を開始します。

サブエージェントが利用できるツール

サブエージェントは、設定済みの MCP ツール、その認証情報と許可されたツールの設定、およびウェブ検索の設定を継承します。また、環境内のファイルやコマンドラインツールも使用できます。サブエージェントは関数ツールに対応していません。

委任状況の確認

セッションイベントストリームは、サブエージェントのアクティビティを通知します。

  • agent.session.subagent.created は、新しいサブエージェントの ID を提供します。
  • agent.session.turn.item.added と agent.session.turn.item.done は、連携に関するアクションを通知します。これらのアイテムの種類には、create_subagent_call、send_subagent_input_call、wait_for_subagents_call、interrupt_subagent_call があります。

これらのアクションはハーネスが実行します。作成や待機のアクションが完了しても、サブエージェントのタスクが完了したことを意味するわけではありません。作成アイテムの agent_id は、サブエージェントの作成をリクエストしたエージェントを識別します。

連携に関するアイテムでは、メッセージ内容が省略されることがあります。agent_message アイテムには、取得可能な場合にエージェント間でやり取りされたテキストが含まれますが、ストリームで会話の全記録が提供されるわけではありません。

まとめられた結果は、メインエージェントの応答で確認してください。各サブエージェントの履歴を含む過去の作業を調べるには、保存済みのアイテムとターンを使用します。

コマンドの実行元の特定

コマンドアイテムとそのセッション ID を使って、コマンドが実行されたターンを取得すると、実行元のエージェントを特定できます。メインエージェントの場合、ターンの subagent_id は null です。

コマンドを実行したエージェントの特定
// Use the saved session ID and command execution item from your application.
const turn = await client.beta.agents.sessions.turns.retrieve(
  command.turn_id,
  { session_id: sessionId }
);
console.log(turn.subagent_id);