如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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 保持一致。

后续步骤

了解运行时循环后,请根据接下来要设计的工作流环节选择相应指南。