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

執行智慧體

瞭解智慧體迴圈、延續對話的策略與串流輸出。

定義智慧體只是準備工作。執行時,你需要瞭解每次執行會做哪些事、下一個回合如何接續,以及工作流程為了等待核准或執行工具而暫停時會如何運作。

智慧體迴圈

SDK 的一次執行對應到應用程式層級的一個回合。執行器會重複以下步驟,直到符合停止條件:

  1. 使用準備好的輸入呼叫目前智慧體的模型。
  2. 檢查模型輸出。
  3. 如果模型產生工具呼叫,就執行這些呼叫,然後繼續迴圈。
  4. 如果模型將任務交接給另一個專責智慧體,就切換到該智慧體,然後繼續迴圈。
  5. 如果模型已產生最終答覆,且沒有其他工具需要執行,就傳回結果。

這個迴圈是 SDK 的核心。工具、交接、核准與串流功能都以它為基礎,並保留相同的執行流程。

選擇一種對話策略

要將狀態帶入下一個回合,常見的做法有四種:

策略 狀態儲存位置 適用情境 下一個回合要傳入的資料
result.history 你的應用程式 小型對話迴圈,或需要最大控制權的情境 可直接重播的對話紀錄
session 由 SDK 搭配你的儲存系統管理 需要持久保存對話狀態、恢復執行,或自行掌控儲存系統 同一個工作階段
conversationId OpenAI Conversations API 多個工作程序或服務需要共用由伺服器管理的狀態 相同的對話 ID,加上新回合的內容即可
previousResponseId OpenAI Responses API 需要以最輕量的方式,由伺服器接續前一次回應 上一次回應的 ID,加上新回合的內容即可

對大多數應用程式而言,每段對話選用一種策略即可。如果同時重播本機對話紀錄並使用伺服器管理的狀態,除非你主動比對並整合兩邊的資料,否則上下文可能會重複。

使用工作階段保存多個回合的狀態
import { Agent, MemorySession, run } from "@openai/agents";

const agent = new Agent({
  name: "Tour guide",
  instructions: "Answer with compact travel facts.",
});

const session = new MemorySession();

const firstTurn = await run(agent, "What city is the Golden Gate Bridge in?", {
  session,
});
console.log(firstTurn.finalOutput);

const secondTurn = await run(agent, "What state is it in?", { session });
console.log(secondTurn.finalOutput);

如果你需要持久保存記憶、在核准流程暫停後恢復執行,或由應用程式掌控儲存系統,工作階段是最合適的預設選擇。

使用伺服器管理的狀態延續對話
import { Agent, run } from "@openai/agents";
import OpenAI from "openai";

const agent = new Agent({
  name: "Assistant",
  instructions: "Reply very concisely.",
});

const client = new OpenAI();
const { id: conversationId } = await client.conversations.create({});

const first = await run(agent, "What city is the Golden Gate Bridge in?", {
  conversationId,
});
console.log(first.finalOutput);

const second = await run(agent, "What state is it in?", {
  conversationId,
});
console.log(second.finalOutput);

如果多個系統需要共用同一段具名對話,請使用 conversationId。如果想以最低成本接續前一次回應,請使用 previousResponseId。

執行期間逐步接收串流輸出

串流使用相同的智慧體迴圈與狀態管理策略。唯一的差別是,你可以在執行期間陸續接收並處理事件。

在執行期間逐步接收文字輸出
import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "Planet guide",
  instructions: "Answer with short facts.",
});

const stream = await run(agent, "Give me three short facts about Saturn.", {
  stream: true,
});

for await (const event of stream) {
  if (
    event.type === "raw_model_stream_event" &&
    event.data.type === "output_text_delta"
  ) {
    process.stdout.write(event.data.delta);
  }
}

await stream.completed;
console.log("\nFinal:", stream.finalOutput);

使用串流時,請遵循三項原則:

  • 等串流結束後,再將這次執行視為已告一段落。
  • 如果執行因等待核准而暫停,請處理 interruptions,再從 state 恢復執行,避免另開新的使用者回合。
  • 如果在回合中途取消串流,之後想繼續同一個回合,請從 state 恢復尚未完成的回合。

分別處理暫停與失敗

執行未按一般流程完成時,應區分兩類情況:

  • 執行或驗證失敗,例如達到回合數上限、觸發防護機制的例外狀況,或工具發生錯誤。
  • 預期中的暫停,例如要求人工核准。此時流程會刻意中斷執行,之後應從同一個狀態恢復。

遇到核准要求時,請將目前的執行視為暫停,並在處理完要求後接續原回合。這樣就能讓回合計數、對話紀錄,以及伺服器管理的接續 ID 保持一致。

後續步驟

瞭解執行迴圈後,請依接下來要設計的工作流程環節,選讀相應的指南。