跳转到内容

执行结果

当您运行智能体时,会收到以下两种结果之一:

这两种结果类型都提供相同的核心结果接口,例如 finalOutput、newItems、interruptions 和 state。StreamedRunResult 还提供了 completed、toStream()、toTextStream() 和 currentAgent 等流式传输控制接口。

大多数应用只需要使用少数几个属性:

如果您需要…使用
向用户展示的最终答案finalOutput
包含完整本地对话记录、可用于重放的下一轮输入history
仅获取本次运行中新生成的、符合模型格式的条目output
包含智能体、工具、交接元数据的丰富运行条目newItems
通常应处理用户下一轮输入的智能体lastAgent 或 activeAgent
使用 previousResponseId 串联 OpenAI Responses API 调用lastResponseId
待处理的审批和可恢复的快照interruptions 和 state
应用上下文、审批、用量和嵌套智能体工具的输入runContext
当前嵌套 Agent.asTool() 调用的元数据,例如在 customOutputExtractor 中使用agentToolInvocation
原始模型调用或护栏诊断信息rawResponses 和护栏结果数组

finalOutput 属性包含最后运行的智能体的最终输出。此结果可能是以下类型之一:

  • string — 未定义 outputType 的智能体的默认类型
  • unknown — 如果智能体将 JSON 模式定义为输出类型。在这种情况下,JSON 已被解析,但您仍需手动验证其类型。
  • z.infer<outputType> — 如果智能体将 Zod 模式定义为输出类型。输出将自动按照此模式进行解析。
  • 推断出的验证输出类型 — 如果智能体将受支持的 Standard Schema 值定义为输出类型。输出将同步按照此模式进行解析和验证。
  • undefined — 如果智能体未生成输出(例如,在生成输出之前停止了运行)

当流式运行仍在进行中,或运行在生成最终输出之前因审批中断而暂停时,finalOutput 也为 undefined。

如果您使用的交涉及不同的输出类型,应使用 Agent.create() 方法而不是 new Agent() 构造函数来创建智能体。

这样,SDK 就能推断所有可能交接的输出类型,并为 finalOutput 属性提供联合类型。

例如:

交接的最终输出类型
import { Agent, run } from '@openai/agents';
import { z } from 'zod';
const refundAgent = new Agent({
name: 'Refund Agent',
instructions:
'You are a refund agent. You are responsible for refunding customers.',
outputType: z.object({
refundApproved: z.boolean(),
}),
});
const orderAgent = new Agent({
name: 'Order Agent',
instructions:
'You are an order agent. You are responsible for processing orders.',
outputType: z.object({
orderId: z.string(),
}),
});
const triageAgent = Agent.create({
name: 'Triage Agent',
instructions:
'You are a triage agent. You are responsible for triaging customer issues.',
handoffs: [refundAgent, orderAgent],
});
const result = await run(triageAgent, 'I need to a refund for my order');
const output = result.finalOutput;
// ^? { refundApproved: boolean } | { orderId: string } | string | undefined

这些属性分别用于回答不同的问题:

属性包含的内容最适用的场景
input本次运行的基础输入。如果交接输入过滤器改写了历史记录,此属性反映的是运行继续时使用的过滤后输入。审计本次运行实际使用的输入
output仅包含本次运行中生成的、符合模型格式的条目,不含智能体元数据。仅存储或重放新增的模型数据
newItems包含智能体、工具、交接元数据的丰富 RunItem 包装对象。日志、UI、审计和调试
history基于 input + newItems 构建的、可用于重放的下一轮输入。手动管理的聊天循环和客户端管理的对话状态

在实际使用中:

  • 在应用中手动维护整个对话时,使用 history。
  • 已在其他位置存储先前的历史记录,并且只需要本次运行中新生成的条目时,使用 output。
  • 需要智能体关联信息、工具输出、交接边界或审批条目时,使用 newItems。
  • 如果您使用 conversationId 或 previousResponseId,通常无需将 history 传回 run()。只需传入新的用户输入,并复用服务器管理的 ID。完整比较请参阅运行智能体。

在类似聊天的使用场景中,history 提供了一种维护完整历史记录的便捷方式:

历史记录循环
import { Agent, user, run } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions:
'You are a helpful assistant knowledgeable about recent AGI research.',
});
let history: AgentInputItem[] = [
// initial message
user('Are we there yet?'),
];
for (let i = 0; i < 10; i++) {
// run 10 times
const result = await run(agent, history);
// update the history to the new output
history = result.history;
history.push(user('How about now?'));
}

newItems 让您能够最全面地了解运行期间发生的情况。常见的条目类型包括:

如果您需要知道某个条目由哪个智能体生成,或它是否标记了工具、工具搜索、交接或审批的边界,请选择 newItems 而不是 output。使用 toolSearchTool() 时,这些工具搜索条目是查看常规工具调用之前加载了哪些延迟加载工具或命名空间的最便捷方式。

如果本地工具或 MCP 服务器定义了 customDataExtractor,对应的 RunToolCallOutputItem.customData 会包含其返回的、仅供 SDK 使用的元数据。这些数据可用于应用的 UI 状态,例如渲染器提示或内部 ID。它们会在 RunState 序列化过程中保留,但不会包含在 history 中,也不会发送回模型。

RunToolCallOutputItem.output 是 SDK 端的工具返回值。与 JSON 兼容的基本类型值、数组和普通对象会在 RunState 序列化过程中保留其结构。其他运行时值继续使用现有的字符串回退方式。此包装对象中的值与 rawItem.output 保持分离,后者是模型可见的工具输出,用于 history 和重放。

lastAgent 属性包含最后运行的智能体。在发生交接后,它通常最适合继续处理用户的下一轮输入。activeAgent 是同一值的别名。

在流式模式下,运行尚未结束时,currentAgent 会告诉您当前处于活动状态的智能体。

如果工具需要审批,运行会暂停,interruptions 中会包含待处理的 RunToolApprovalItem。这些审批可能由直接调用的工具、交接后调用的工具或嵌套的 agent.asTool() 运行发起。

通过 result.state.approve(...) / result.state.reject(...) 处理审批,然后将同一个 state 传回 run() 以恢复运行。您无需一次性处理所有中断。如果只处理了部分条目就重新运行,已处理的调用可以继续执行,而未处理的调用会保持待处理状态,并再次暂停运行。

state 属性是执行结果背后的可序列化快照。它适用于人机协作、重试流程,或任何需要稍后恢复已暂停运行的场景。

使用 OpenAI Responses API 串联调用时,lastResponseId 是下一轮应作为 previousResponseId 传入的值。

如果您已经通过 history、session 或 conversationId 继续对话,通常无需使用 lastResponseId。如果需要获取多步运行中的每个原始模型响应,请改为查看 rawResponses。

agentToolInvocation 用于嵌套的 Agent.asTool() 执行结果,尤其适合在 customOutputExtractor 内部获取当前工具调用的元数据。它并不是一个通用的”整个运行已完成”摘要字段。

在该嵌套上下文中,agentToolInvocation 提供以下字段:

  • toolName
  • toolCallId
  • toolArguments

如果还需要获取传入该嵌套智能体工具运行的结构化输入,可结合使用 result.runContext.toolInput。

在普通的顶层 run() 执行结果中,该属性通常为 undefined。这些元数据仅存在于运行时,不会序列化到 RunState 中。有关相关使用模式,请参阅Agents as tools。

StreamedRunResult 继承了上述相同的结果接口,同时增加了流式传输专用的控制接口:

  • toTextStream():仅获取助手文本。
  • toStream() 或 for await ... of stream:获取完整事件流。
  • completed:等待运行和所有后处理回调完成。
  • error 和 cancelled:查看流式传输的终止状态。
  • currentAgent:跟踪运行中的活动智能体。
  • currentTurn:查看实际到达请求阶段的模型轮次数。
  • maxTurns:查看本次流式运行的轮次上限(null 表示无限制)。

currentTurn 仅在模型请求获准执行时递增。如果最大轮次检查或阻塞式输入护栏阻止了请求,它不会递增;恢复的运行则从其 RunState 中保留的计数开始。

如果您需要流式运行的最终确定状态,请等待 completed 完成后再读取 finalOutput、history、interruptions 或其他摘要属性。有关逐事件处理的信息,请参阅流式传输指南。

如果流式运行被取消,completed 仍会在清理完成后兑现,且 cancelled 变为 true,但由于当前轮次未完成,finalOutput 等轮次结束字段可能仍未设置。请使用 result.state(如果使用了 session,还需使用同一个 session)恢复未完成的轮次,而不是追加一条新的用户消息。

runContext 属性是执行结果中受支持的运行上下文公共视图。result.runContext.context 是您的应用上下文,同一个 runContext 对象还包含 SDK 管理的运行时元数据,例如审批、用量和嵌套的 toolInput。完整结构请参阅上下文管理。

rawResponses 包含运行期间收集的原始模型响应。多步运行可能产生多个响应,例如跨越多次交接或重复的工具与模型调用循环。

如果输出护栏拒绝了用于结束运行的函数工具结果,SDK 会对 rawResponses 中的当前响应以及 SDK 管理的其他重放数据进行清理。不要假定仍可通过此属性查看被拒绝的最终工具输出。有关内容删改的边界和限制,请参阅护栏中的”被拒绝的最终工具输出”部分。

每个响应还可能包含 requestId,即提供方的请求标识符(如果可用)。OpenAI Responses 和 Chat Completions 模型会为流式和非流式 HTTP 请求填充此字段;请将其视为可选字段,因为某些提供方和传输机制不提供该标识符。

对于 Chat Completions 文本输出,可查看规范化后的 output_text 部分中的 providerData.annotations 来读取 URL 引用。非流式响应会保留提供方的消息注释。流式响应会保留随文本接收到的有效 url_citation 注释,对重复引用去重,并忽略格式错误或不受支持的注释结构。

对于 Chat Completions 音频,规范化后的模型响应会以包含 audio 内容部分的纯音频助手消息表示。当该消息成为运行条目时,可在 RunMessageOutputItem.rawItem 中查看同一个内容部分。如果非流式响应除了音频还包含文本或拒绝内容,规范化后的助手消息会保留文本或拒绝内容,而完整的提供方响应仍可在 rawResponses[].providerData 中获取。对于流式混合输出,如果需要在提供方音频块到达时获取它们,请查看原始模型流事件;完成后的 rawResponses 条目包含规范化后的文本或拒绝内容,但不包含重建的音频。流式传输辅助方法 toTextStream() 仅输出文本。

当 modelSettings.preserveRawUsage 为 true 时,每个已完成的响应还可提供 rawUsage,这是在 SDK 规范化之前捕获的独立快照,与 JSON 兼容。规范化后的 Usage 仍可通过 response.usage 获取;rawUsage 则保留提供方特有的字段名称,并在提供方数据中保留字段省略与显式赋值之间的区别。如果提供方省略了用量信息,或载荷无法安全复制,它可能为 undefined。rawUsage 仅存在于运行时,并且会有意从序列化的 RunState 中省略,因此请在持久化并恢复运行之前复制您需要的字段。

inputGuardrailResults 和 outputGuardrailResults 属性包含智能体级别的护栏结果。工具护栏结果则通过 toolInputGuardrailResults 和 toolOutputGuardrailResults 单独提供。

如果您想记录护栏的决策、查看护栏函数返回的额外元数据,或调试运行被阻止的原因,请使用这些数组。

对于被拒绝的、用于结束运行的函数工具结果,SDK 会有意清理当前响应的护栏元数据。在 outputGuardrailResults 中,agentOutput 会变为 Output withheld by an output guardrail.,且 outputInfo 会被移除。当前的 toolOutputGuardrailResults 会保留其判定,但省略 outputInfo,而 rejectContent 结果会使用相同的占位文本作为消息。之前已接受的历史结果保持不变。

如果某个护栏执行失败,其他已成功完成的同级护栏的结果仍会保留在运行状态中。对于流式运行,请在 completed 拒绝后查看结果数组;对于非流式运行,GuardrailExecutionError 会携带相同的最终确定 state。

Token 用量汇总在 result.state.usage 中,该属性会跟踪本次运行的请求数和 Token 总数。也可通过 result.runContext.usage 获取同一个用量对象。对于流式运行,这些数据会随着响应到达而更新。

一次已完成的流式或非流式 Chat Completions 调用会计为一个请求,即使提供方省略了用量对象也是如此。在这种情况下,由于提供方未报告 Token 数量,Token 总数会保持为零。

从 RunState 读取用量
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Usage Tracker',
instructions: 'Summarize the latest project update in one sentence.',
});
const result = await run(
agent,
'Summarize this: key customer feedback themes and the next product iteration.',
);
const usage = result.state.usage;
console.log({
requests: usage.requests,
inputTokens: usage.inputTokens,
outputTokens: usage.outputTokens,
totalTokens: usage.totalTokens,
});
if (usage.requestUsageEntries) {
for (const entry of usage.requestUsageEntries) {
console.log('request', {
endpoint: entry.endpoint,
inputTokens: entry.inputTokens,
outputTokens: entry.outputTokens,
totalTokens: entry.totalTokens,
});
}
}