定义智能体只是准备工作。您还需要了解一次运行会执行哪些步骤、下一轮交互如何接续,以及工作流因等待审批或工具执行而暂停时会发生什么。
智能体循环
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 保持一致。
后续步骤
了解运行时循环后,请根据接下来要设计的工作流环节选择相应指南。