定義智慧體只是準備工作。執行時,你需要瞭解每次執行會做哪些事、下一個回合如何接續,以及工作流程為了等待核准或執行工具而暫停時會如何運作。
智慧體迴圈
SDK 的一次執行對應到應用程式層級的一個回合。執行器會重複以下步驟,直到符合停止條件:
- 使用準備好的輸入呼叫目前智慧體的模型。
- 檢查模型輸出。
- 如果模型產生工具呼叫,就執行這些呼叫,然後繼續迴圈。
- 如果模型將任務交接給另一個專責智慧體,就切換到該智慧體,然後繼續迴圈。
- 如果模型已產生最終答覆,且沒有其他工具需要執行,就傳回結果。
這個迴圈是 SDK 的核心。工具、交接、核准與串流功能都以它為基礎,並保留相同的執行流程。
選擇一種對話策略
要將狀態帶入下一個回合,常見的做法有四種:
| 策略 | 狀態儲存位置 | 適用情境 | 下一個回合要傳入的資料 |
|---|---|---|---|
result.history |
你的應用程式 | 小型對話迴圈,或需要最大控制權的情境 | 可直接重播的對話紀錄 |
session |
由 SDK 搭配你的儲存系統管理 | 需要持久保存對話狀態、恢復執行,或自行掌控儲存系統 | 同一個工作階段 |
conversationId |
OpenAI Conversations API | 多個工作程序或服務需要共用由伺服器管理的狀態 | 相同的對話 ID,加上新回合的內容即可 |
previousResponseId |
OpenAI Responses API | 需要以最輕量的方式,由伺服器接續前一次回應 | 上一次回應的 ID,加上新回合的內容即可 |
對大多數應用程式而言,每段對話選用一種策略即可。如果同時重播本機對話紀錄並使用伺服器管理的狀態,除非你主動比對並整合兩邊的資料,否則上下文可能會重複。
使用工作階段保存多個回合的狀態
TypeScript
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);如果你需要持久保存記憶、在核准流程暫停後恢復執行,或由應用程式掌控儲存系統,工作階段是最合適的預設選擇。
使用伺服器管理的狀態延續對話
TypeScript
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
執行期間逐步接收串流輸出
串流使用相同的智慧體迴圈與狀態管理策略。唯一的差別是,你可以在執行期間陸續接收並處理事件。
在執行期間逐步接收文字輸出
TypeScript
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 保持一致。
後續步驟
瞭解執行迴圈後,請依接下來要設計的工作流程環節,選讀相應的指南。