跳转到内容

运行智能体

智能体不会自行执行任何操作,您需要使用 Runner 类或 run() 实用函数来运行它们。

在阅读智能体后,如果您想执行轮次、流式传输事件或管理对话状态,请阅读本页。如果您还在考虑如何定义智能体,请先阅读智能体。

简单运行
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'You are a helpful assistant',
});
const result = await run(
agent,
'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);
// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

如果不需要自定义 Runner,也可以使用 run() 实用函数,它使用默认的 Runner 单例实例来运行。

或者,您可以创建自己的 Runner 实例:

简单运行
import { Agent, Runner } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'You are a helpful assistant',
});
// You can pass custom configuration to the runner
const runner = new Runner();
const result = await runner.run(
agent,
'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);
// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

运行智能体后,您会收到一个执行结果对象,其中包含最终输出和本次运行的完整历史记录。

使用 Runner 的 run 方法时,需要传入起始智能体和输入。输入可以是字符串(视为用户消息),也可以是输入项列表,其中的输入项就是 OpenAI Responses API 中的项。

随后,Runner 会执行一个循环:

  1. 使用当前输入调用当前智能体的模型。
  2. 检查 LLM 响应。
    • 最终输出 → 返回。
    • 交接 → 切换到新的智能体,保留累积的对话历史记录,回到第 1 步。
    • 工具调用 → 执行工具,将其结果追加到对话中,回到第 1 步。
  3. 达到 maxTurns 时抛出 MaxTurnsExceededError,除非 maxTurns 为 null。

在应用启动时创建一个 Runner,并在各个请求之间复用它。该实例存储模型提供商和追踪选项等全局配置。只有在需要完全不同的配置时,才创建另一个 Runner。对于简单脚本,也可以调用 run(),它在内部使用默认的 Runner。

run() 方法接收的参数包括:用于启动运行的初始智能体、本次运行的输入以及一组选项。

输入可以是字符串(视为用户消息)、输入项列表,或者在构建人机协作智能体时使用的 RunState 对象。

其他选项如下:

选项默认值说明
streamfalse如果为 true,调用将返回 StreamedRunResult,并在收到模型事件时发出相应事件。
context–传递给每个工具、护栏和交接的上下文对象。详情请参阅上下文管理。
maxTurns10安全限制,达到上限时抛出 MaxTurnsExceededError。传入 null 可禁用此限制。
signal–用于取消操作的 AbortSignal。
session–会话持久化实现。请参阅会话。
sessionInputCallback–用于合并会话历史记录和新输入的自定义逻辑,在模型调用之前运行。请参阅会话。
callModelInputFilter–在调用模型前修改模型输入(输入项和可选的 instructions)的钩子。请参阅模型调用输入过滤器。
toolErrorFormatter–用于自定义返回给模型的工具错误消息的钩子。请参阅工具错误格式化器。
reasoningItemIdPolicy–控制将先前的运行项转换回模型输入时,是保留还是省略推理项的 id。请参阅推理项 ID 策略。
tracing–单次运行的追踪配置覆盖项。设置 includeTaskAndTurnSpans: false 可省略默认的任务/轮次 span 层级结构。
sandbox–用于 SandboxAgent 运行的沙盒客户端、活动会话、会话状态、快照、清单覆盖配置或并发限制。请参阅概念。
toolExecution–本地工具调用在 SDK 侧的执行设置。使用 toolExecution.maxFunctionToolConcurrency 限制同时运行的函数工具数量,使用 toolExecution.preApprovalInputGuardrails 在产生待审批请求之前运行函数工具的输入护栏。
toolNotFoundBehavior'raise_error'控制如何处理模型发出的无法解析的函数工具调用。使用 'return_error_to_model' 可返回模型可见的工具错误,并继续运行。
toolNameCollisionPolicy'warn'控制已启用的函数工具与交接的名称冲突。使用 'error' 可在模型请求之前报错,而不是发出警告并仅暴露当前分派选中的对象。
errorHandlers–受支持的运行时错误的处理器。请参阅错误处理器。
conversationId–复用服务器端对话(仅适用于 OpenAI Responses API + Conversations API)。
previousResponseId–从上一次 Responses API 调用继续,而不创建对话(仅适用于 OpenAI Responses API)。

流式传输还会在 LLM 运行期间提供事件。StreamedRunResult 会随着运行推进累积信息。当执行结果的 completed promise 兑现后,执行结果的摘要属性将包含所有新生成的输出。您可以使用 for await 循环遍历流式事件。详情请参阅流式传输。

如果创建自己的 Runner 实例,可以传入 RunConfig 对象来配置 Runner。

字段类型用途
modelstring | Model强制本次运行中的所有智能体使用指定模型。
modelProviderModelProvider解析模型名称,默认使用 OpenAI 提供商。
modelSettingsModelSettings覆盖各智能体设置的全局调优参数。详情请参阅模型,其中也介绍了可选择启用的重试配置。
handoffInputFilterHandoffInputFilter执行交接时修改输入项(如果交接本身尚未定义输入过滤器)。
inputGuardrailsInputGuardrail[]应用于初始用户输入的护栏。
outputGuardrailsOutputGuardrail[]应用于最终输出的护栏。
tracingDisabledboolean完全禁用 OpenAI 追踪。
traceIncludeSensitiveDataboolean从追踪中排除 LLM/工具的输入和输出,同时仍生成 span。
workflowNamestring显示在 Traces 控制面板中,便于对相关运行进行分组。
traceId / groupIdstring手动指定追踪或组 ID,而不是让 SDK 生成。
traceMetadataRecord<string, string>附加到每个 span 的任意元数据。
tracingTracingConfigRunner 级别的追踪默认配置,包括导出用的 API 密钥和 includeTaskAndTurnSpans。单次运行选项可以覆盖这些值。
sessionInputCallbackSessionInputCallback此 Runner 上所有运行的默认历史记录合并策略。
callModelInputFilterCallModelInputFilter在每次模型调用前修改模型输入的全局钩子。
toolErrorFormatterToolErrorFormatter自定义返回给模型的工具错误消息的全局钩子。
reasoningItemIdPolicyReasoningItemIdPolicy将生成的项回放到后续模型调用中时,保留或省略推理项 id 的默认策略。
sandboxSandboxRunConfigSandboxAgent 运行的默认沙盒运行时配置。
toolExecutionToolExecutionConfig本地工具调用在 SDK 侧的默认执行设置。maxFunctionToolConcurrency 限制每轮本地函数工具的并发数量;不设置或设为 null 时,会启动该轮发出的所有函数工具调用。preApprovalInputGuardrails 用于选择在产生待审批请求之前运行函数工具的输入护栏。
toolNotFoundBehaviorToolNotFoundBehavior无法解析的函数工具调用的默认处理方式。'raise_error' 会抛出 ModelBehaviorError;'return_error_to_model' 会返回模型可见的工具错误,并让运行继续。
toolNameCollisionPolicyToolNameCollisionPolicy已启用的函数工具与交接的默认名称冲突策略。'warn' 会记录警告并暴露当前分派选中的对象;'error' 会在调用模型之前抛出 UserError。

toolExecution.maxFunctionToolConcurrency 必须是大于或等于 1 的整数。此设置仅限制本地函数工具在 SDK 侧的执行,不会更改提供商侧的 modelSettings.parallelToolCalls。

toolExecution.preApprovalInputGuardrails 默认禁用。设为 true 时,需要审批的本地函数工具会在 SDK 记录待审批中断之前运行其输入护栏。如果护栏返回 rejectContent,SDK 会将该拒绝消息作为工具输出返回,而不是请求审批。如果护栏允许调用,仍会发起审批请求,并在审批完成后、工具执行前再次运行相同的输入护栏。

toolNameCollisionPolicy 仅控制已启用的函数工具与交接的名称冲突。针对命名空间工具、延迟加载工具以及重复的本地 MCP 工具名称,现有的严格验证规则保持不变。

将状态传递到下一轮通常有四种方式:

策略状态存储位置适用场景下一轮传入的内容
result.history应用内存小型聊天循环、完全手动控制、任意提供商result.history
session您的存储 + SDK持久化聊天状态、可恢复的运行、自定义存储同一个 session 实例(或由存储支持的实例)
conversationIdOpenAI Conversations API在工作进程/服务之间共享服务器端状态同一个 conversationId,外加新的用户轮次内容
previousResponseId仅限 OpenAI Responses API无需创建对话、由服务器管理的最简单的续接方式result.lastResponseId,外加新的用户轮次内容

result.history 和 session 由客户端管理。conversationId 和 previousResponseId 由 OpenAI 管理,仅在使用 OpenAI Responses API 时适用。在大多数应用中,每个对话应选择一种持久化策略。混用客户端管理的历史记录和服务器管理的状态可能导致上下文重复,除非您有意协调这两个层面的状态。

沙盒智能体增加了另一个状态层:活动的沙盒工作区。使用常规 SDK 的 session、conversationId 或 previousResponseId 管理对话历史记录,使用 sandbox.session、sandbox.sessionState、RunState 或快照管理沙盒文件系统状态。有关工作区生命周期,请参阅概念。

每次调用 runner.run()(或 run() 实用函数)都代表应用级对话中的一个轮次。您可以选择向最终用户展示多少 RunResult 内容:有时仅展示 finalOutput,有时展示每个生成的项。

沿用对话历史记录的示例
import { Agent, run } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents';
let thread: AgentInputItem[] = [];
const agent = new Agent({
name: 'Assistant',
});
async function userSays(text: string) {
const result = await run(
agent,
thread.concat({ role: 'user', content: text }),
);
thread = result.history; // Carry over history + newly generated items
return result.finalOutput;
}
await userSays('What city is the Golden Gate Bridge in?');
// -> "San Francisco"
await userSays('What state is it in?');
// -> "California"

交互式版本请参阅聊天代码示例。

您可以让 OpenAI Responses API 为您持久化对话历史记录,而不必在每一轮发送完整的本地对话历史记录。这在协调长对话或多个服务时很有用。使用以下任一种服务器管理方式时,每次请求都只需传入新一轮的输入。API 会为您复用先前的状态。详情请参阅对话状态指南。

OpenAI 提供两种复用服务器端状态的方式:

1. 使用 conversationId 管理整个对话
Section titled “1. 使用 conversationId 管理整个对话”

您可以通过 Conversations API 创建一次对话,然后在每一轮复用其 ID。SDK 会自动仅包含新生成的项。

复用服务器端对话
import { Agent, run } from '@openai/agents';
import { OpenAI } from 'openai';
const agent = new Agent({
name: 'Assistant',
instructions: 'Reply very concisely.',
});
async function main() {
// Create a server-managed conversation:
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);
// -> "San Francisco"
const second = await run(agent, 'What state is it in?', { conversationId });
console.log(second.finalOutput);
// -> "California"
}
main().catch(console.error);
2. 使用 previousResponseId 从上一轮继续
Section titled “2. 使用 previousResponseId 从上一轮继续”

如果您只想使用 Responses API 起步,可以使用上一次响应返回的 ID 将各个请求串联起来。这样无需创建完整的对话资源,也能在各轮之间保留上下文。

使用 previousResponseId 串联请求
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'Assistant',
instructions: 'Reply very concisely.',
});
async function main() {
const first = await run(agent, 'What city is the Golden Gate Bridge in?');
console.log(first.finalOutput);
// -> "San Francisco"
const previousResponseId = first.lastResponseId;
const second = await run(agent, 'What state is it in?', {
previousResponseId,
});
console.log(second.finalOutput);
// -> "California"
}
main().catch(console.error);

conversationId 和 previousResponseId 互斥。如果需要可跨系统共享的命名对话资源,请使用 conversationId;如果只是希望以开销最低的 SDK 级基本组件从一个响应延续到下一个响应,请使用 previousResponseId。

使用 callModelInputFilter 可在调用模型之前的最后一步修改模型输入。此钩子接收当前智能体、上下文以及合并后的输入项(如果存在会话历史记录,也会包含在内)。返回更新后的 input 数组和可选的 instructions,即可隐去敏感数据、删除旧消息或注入额外的系统指导。

可以在 runner.run(..., { callModelInputFilter }) 中为单次运行设置,也可以在 Runner 配置中将其设为默认值(RunConfig 中的 callModelInputFilter)。

返回值必须是 ModelInputData 对象:{ input: AgentInputItem[], instructions? }。input 字段为必填项,且必须是数组。返回任何其他结构都会抛出 UserError。

SDK 会在调用过滤器之前克隆准备好的本轮输入。如果还使用了 session,持久化的将是过滤后的副本,因此这里进行的敏感数据隐去或截断操作也会反映在存储的会话历史记录中。

如果过滤器依靠对象标识,在重复的模型调用之间缓存处理结果,请在过滤器上设置 preserveInputIdentity = true。这样,只要 SDK 准备的某一项仍保留在准备好的输入中,SDK 就会保留该项的对象标识,但每次调用过滤器时传入的数组仍是新的。此选项不会保留最初传给 run() 的调用方对象的标识。

保留准备好的输入项的对象标识
import { CallModelInputFilter, Runner } from '@openai/agents';
const inspectedItems = new WeakSet<object>();
const inspectInputOnce: CallModelInputFilter = ({ modelData }) => {
for (const item of modelData.input) {
if (item && typeof item === 'object' && !inspectedItems.has(item)) {
inspectedItems.add(item);
recordPreparedItem(item);
}
}
return modelData;
};
// Keep SDK-prepared item identities stable across repeated model calls so the
// WeakSet can recognize items that this filter already inspected. Do not mutate
// the items or their nested values.
inspectInputOnce.preserveInputIdentity = true;
const runner = new Runner({ callModelInputFilter: inspectInputOnce });
declare function recordPreparedItem(item: object): void;
export { runner };

此模式需要主动启用,因为 SDK 不会冻结准备好的项或其嵌套值。过滤器及其调用的每个辅助函数都必须将这些项视为不可变对象,返回替代值,而不是直接修改它们。过滤器返回后,模型请求和会话输入仍是独立副本。

使用 conversationId 或 previousResponseId 时,钩子会处理为下一次 Responses API 调用准备好的负载。先前由服务器管理的上下文由 API 恢复,因此,该次调用中过滤后的数组可能已经只包含新一轮的增量内容,而不是完整回放之前的历史记录。如果需要在这最后的过滤步骤之前更改已存储历史记录与当前轮次的合并方式,请使用 sessionInputCallback。

使用 toolErrorFormatter 可自定义发送回模型的工具错误消息。这样可以返回特定领域的表述(例如合规指导),而不是 SDK 的默认消息。

格式化器可以针对单次运行设置(runner.run(..., { toolErrorFormatter })),也可以在 RunConfig 中全局设置(new Runner(...) 中的 toolErrorFormatter)。

此格式化器是审批被拒绝时的全局回退方式。如果使用 result.state.reject(interruption, { message: '...' }) 拒绝某个特定中断,该次调用的 message 优先于 toolErrorFormatter。如果两者都未提供,SDK 会回退到默认拒绝文本:Tool execution was not approved.

当 toolNotFoundBehavior: 'return_error_to_model' 将无法解析的函数工具调用转换为模型可见的工具输出时,也会运行此格式化器。此时,默认消息为 Tool '<name>' not found.

格式化器接收以下内容:

  • kind('approval_rejected' 或 'tool_not_found')
  • toolType('function'、'computer'、'shell' 或 'apply_patch')
  • toolName
  • callId
  • defaultMessage(SDK 针对当前错误类型的回退消息)
  • runContext

返回字符串可覆盖消息,返回 undefined 则保留 SDK 默认消息。如果格式化器抛出异常(或返回非字符串值),SDK 会记录警告,并回退到当前错误类型的默认消息。

当 SDK 将先前生成的运行项转换回 AgentInputItem[],用作后续模型输入时,可以使用 reasoningItemIdPolicy 控制是否保留推理项的 id 字段。

这会影响 SDK 将生成的模型项作为输入回放的场景,例如:

  • 同一次运行中的后续模型调用(例如工具执行后),
  • 将生成的项作为输入/历史记录复用的后续轮次,
  • 从已保存的 RunState 恢复的运行,
  • 派生的执行结果视图,如 result.history / result.output(其数组结构与模型输入相同)。
  • 'preserve'(默认值)保留推理项 ID。
  • 'omit' 在将推理项作为输入重新发送之前,移除其中的 id 字段。
  • 非推理项不受影响。

此策略不会更改以下内容:

  • 原始模型响应(result.rawResponses),
  • 运行项(result.newItems),
  • 提供商返回的模型当前轮次输出。

换句话说,该策略在 SDK 根据先前生成的项构建下一次输入时生效。

您可以针对单次运行设置该策略(runner.run(..., { reasoningItemIdPolicy: 'omit' })),也可以将其设为 Runner 默认值(new Runner({ reasoningItemIdPolicy: 'omit', ... }))。从已保存的 RunState 恢复时,除非显式覆盖,否则会复用先前确定的策略。

reasoningItemIdPolicy 在 callModelInputFilter 之前应用。如果需要自定义行为,callModelInputFilter 仍然可以检查准备好的输入,并在模型调用前手动重新添加或移除推理项 ID。

如果希望将回放的推理项统一为不带 ID 的形式,请使用 'omit'(例如,为了简化转发/回放的模型输入,或满足应用流水线中的集成要求)。

如果后端/提供商因请求验证错误而拒绝回放的推理项(例如,后续输入中与推理项 ID 相关的 HTTP 400 错误),这也是一个有用的故障排除选项。在这些情况下,使用 'omit' 移除回放的推理项 ID,可以避免发送后端认为对新请求无效的 ID。

如果希望 SDK 在回放的输入中保留推理项 ID,并且您的集成能够接受这些 ID,请保留 'preserve'。

使用 errorHandlers 可将受支持的运行时错误转换为最终输出,而不是抛出异常。支持的键包括 maxTurns、modelRefusal 和 invalidFinalOutput。

  • errorHandlers.maxTurns 仅处理达到最大轮数的错误。
  • errorHandlers.modelRefusal 处理以 ModelRefusalError 形式报告的模型拒绝。
  • errorHandlers.invalidFinalOutput 处理因缺少结构化最终输出或未通过输出模式验证而抛出的 ModelBehaviorError 实例。处理器返回经过验证的回退输出,不会重试模型调用或重复执行工具的副作用。
  • errorHandlers.default 用作受支持错误类型的回退处理器。
  • 处理器接收 { error, context, runData },并可返回 { finalOutput, includeInHistory? }。返回的 finalOutput 必须符合当前智能体的 outputType。对于 structured outputs,SDK 会在完成运行之前验证回退输出。返回 undefined 会保留该错误的默认处理行为。

SDK 会抛出少量可捕获的错误:

这些错误都继承自基类 AgentsError,该类可能提供 state 属性,用于访问当前运行状态。

下面是处理 GuardrailExecutionError 的代码示例。由于输入护栏只在首次用户输入时运行,因此该示例使用原始输入和上下文重新启动运行。它还展示了如何复用已保存的状态,在不再次调用模型的情况下重试输出护栏:

护栏执行错误
import {
Agent,
GuardrailExecutionError,
InputGuardrail,
InputGuardrailTripwireTriggered,
OutputGuardrail,
OutputGuardrailTripwireTriggered,
run,
} from '@openai/agents';
import { z } from 'zod';
// Shared guardrail agent to avoid re-creating it on every fallback run.
const guardrailAgent = new Agent({
name: 'Guardrail check',
instructions: 'Check if the user is asking you to do their math homework.',
outputType: z.object({
isMathHomework: z.boolean(),
reasoning: z.string(),
}),
});
async function main() {
const input = 'Hello, can you help me solve for x: 2x + 3 = 11?';
const context = { customerId: '12345' };
// Input guardrail example
const unstableInputGuardrail: InputGuardrail = {
name: 'Math Homework Guardrail (unstable)',
execute: async () => {
throw new Error('Something is wrong!');
},
};
const fallbackInputGuardrail: InputGuardrail = {
name: 'Math Homework Guardrail (fallback)',
execute: async ({ input, context }) => {
const result = await run(guardrailAgent, input, { context });
const isMathHomework =
result.finalOutput?.isMathHomework ??
/solve for x|math homework/i.test(JSON.stringify(input));
return {
outputInfo: result.finalOutput,
tripwireTriggered: isMathHomework,
};
},
};
const agent = new Agent({
name: 'Customer support agent',
instructions:
'You are a customer support agent. You help customers with their questions.',
inputGuardrails: [unstableInputGuardrail],
});
try {
// Input guardrails only run on the first turn of a run, so retries must start a fresh run.
await run(agent, input, { context });
} catch (e) {
if (e instanceof GuardrailExecutionError) {
console.error(`Guardrail execution failed (input): ${e}`);
try {
agent.inputGuardrails = [fallbackInputGuardrail];
// Retry from scratch with the original input and context.
await run(agent, input, { context });
} catch (ee) {
if (ee instanceof InputGuardrailTripwireTriggered) {
console.log('Math homework input guardrail tripped on retry');
} else {
throw ee;
}
}
} else {
throw e;
}
}
// Output guardrail example
const replyOutputSchema = z.object({ reply: z.string() });
const unstableOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
name: 'Answer review (unstable)',
execute: async () => {
throw new Error('Output guardrail crashed.');
},
};
const fallbackOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
name: 'Answer review (fallback)',
execute: async ({ agentOutput }) => {
const outputText =
typeof agentOutput === 'string'
? agentOutput
: (agentOutput?.reply ?? JSON.stringify(agentOutput));
const flagged = /math homework|solve for x|x =/i.test(outputText);
return {
outputInfo: { flaggedOutput: outputText },
tripwireTriggered: flagged,
};
},
};
const agent2 = new Agent<unknown, typeof replyOutputSchema>({
name: 'Customer support agent (output check)',
instructions: 'You are a customer support agent. Answer briefly.',
outputType: replyOutputSchema,
outputGuardrails: [unstableOutputGuardrail],
});
try {
await run(agent2, input, { context });
} catch (e) {
if (e instanceof GuardrailExecutionError && e.state) {
console.error(`Guardrail execution failed (output): ${e}`);
try {
agent2.outputGuardrails = [fallbackOutputGuardrail];
// Output guardrails can be retried using the saved state without another model call.
await run(agent2, e.state);
} catch (ee) {
if (ee instanceof OutputGuardrailTripwireTriggered) {
console.log('Output guardrail tripped after retry with saved state');
} else {
throw ee;
}
}
} else {
throw e;
}
}
}
main().catch(console.error);

输入护栏与输出护栏的重试区别:

  • 输入护栏仅在一次运行的首次用户输入时执行,因此必须使用相同的输入/上下文启动新的运行才能重试;传入已保存的 state 不会重新触发输入护栏。
  • 输出护栏在模型响应之后执行,因此可以复用 GuardrailExecutionError 中保存的 state,在不再次调用模型的情况下重新运行输出护栏。

运行上面的代码示例时,您会看到以下输出:

Guardrail execution failed (input): Error: Input guardrail failed to complete: Error: Something is wrong!
Math homework input guardrail tripped on retry
Guardrail execution failed (output): Error: Output guardrail failed to complete: Error: Output guardrail crashed.
Output guardrail tripped after retry with saved state

  • 智能体:在运行之前定义智能体。
  • 执行结果:了解 finalOutput、运行项、中断和恢复状态。
  • 会话:了解由 SDK 管理的持久化记忆。
  • 工具:了解运行循环中使用的能力。
  • 模型:了解提供商配置和 Responses 传输机制。
  • 添加护栏或追踪,为生产环境做好准备。