如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

多智慧體協作

讓智慧體將任務委派給可獨立作業的子代理程式。

透過多智慧體協作,智慧體可以將任務委派給子代理程式。每個子代理程式都有自己的上下文,可與其他子代理程式平行作業。主智慧體負責協調工作並彙整結果。

何時使用子代理程式

將彼此獨立的任務交給子代理程式,例如分別審閱不同文件,或各自調查同一故障的不同可能原因。為每項任務明確指出要回答的問題和預期結果。

簡短的任務和有相依關係的步驟應由主智慧體處理。如果多個智慧體編輯同一批檔案,就必須協調各自的修改。

啟用多智慧體協調功能

建立工作階段時,將 agent.multi_agent.enabled 設為 true。任務執行框架會提供工具,讓智慧體建立子代理程式、向其傳送訊息、等待其回應,以及中斷其執行。你無須自行宣告這些工具。

這個範例在使用者輸入中明確要求使用兩個子代理程式。每個子代理程式各自審閱一組版本資訊,再由主智慧體彙整審閱結果。此範例無須環境,也無須設定工具:

比較版本資訊
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="Use two subagents, one for each release, and combine their findings into a labeled summary. 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,
).with_result_collection() as stream:
    for event in stream:
        print(event.model_dump_json())
    result = stream.get_final_result()
print(result.output_text)

使用 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);