上下文管理
“上下文”一词有多种含义。您可能需要关注的上下文主要分为两类:
- 本地上下文:代码在运行期间可以访问的上下文,包括工具、
onHandoff等回调和生命周期钩子所需的依赖项或数据。 - LLM 可见上下文:语言模型在生成响应时可以看到的上下文。
本地上下文由 RunContext<T> 类型表示。您可以创建任意对象来保存状态或依赖项,并将其传递给 Runner.run()。所有工具调用和钩子都会收到一个 RunContext 包装对象,以便读取或修改该对象。
import { Agent, run, RunContext, tool } from '@openai/agents';import { z } from 'zod';
interface UserInfo { name: string; uid: number;}
const fetchUserAge = tool({ name: 'fetch_user_age', description: 'Return the age of the current user', parameters: z.object({}), execute: async ( _args, runContext?: RunContext<UserInfo>, ): Promise<string> => { return `User ${runContext?.context.name} is 47 years old`; },});
async function main() { const userInfo: UserInfo = { name: 'John', uid: 123 };
const agent = new Agent<UserInfo>({ name: 'Assistant', tools: [fetchUserAge], });
const result = await run(agent, 'What is the age of the user?', { context: userInfo, });
console.log(result.finalOutput); // The user John is 47 years old.}
main().catch((error) => { console.error(error); process.exit(1);});参与同一次运行的所有智能体、工具和钩子都必须使用相同类型的上下文。
本地上下文可用于保存以下内容:
- 与运行相关的数据(用户名、ID 等)
- 日志记录器或数据获取器等依赖项
- 辅助函数
在同一次运行中,派生上下文共享底层的应用上下文、审批状态和用量追踪。嵌套的 agent.asTool() 运行可能会附带不同的 toolInput,但默认情况下不会获得应用状态的独立副本。
基于本地上下文的能力可见性
Section titled “基于本地上下文的能力可见性”当函数工具、本地 MCP 工具和交接依赖同一请求策略时,请将策略输入或辅助函数保存在应用上下文中。SDK 的各个接口通过各自的回调暴露当前运行上下文:
- 通过
tool()创建的函数工具,其isEnabled判断函数会收到一个对象,该对象的runContext属性为当前的RunContext。 - 交接的
isEnabled判断函数会收到一个对象,该对象的runContext属性为当前的RunContext。 - 可调用的 MCP
toolFilter会收到MCPToolFilterContext,其runContext属性为当前的RunContext。
请将共享的应用策略适配到这些回调中,而不是维护单独的能力列表。这些回调控制 SDK 在当前轮次向模型提供哪些能力;它们在模型生成工具参数或交接参数之前运行,因此无法对模型生成的参数或资源选择进行授权。对于函数工具,应在 execute 内执行这些授权检查,或在适当时添加工具输入护栏和人机协作审批机制。MCP 服务器必须自行对其受保护的操作进行授权。对于设置了 inputType 的交接,请在 onHandoff 开始时、应用产生任何副作用之前检查解析后的输入,并在授权失败时抛出异常。onHandoff 成功返回后,交接会继续进行,而且工具输入护栏不会在交接时运行。有关回调生命周期,请参阅交接输入。
如果可调用的 MCP toolFilter 依赖请求上下文,请对智能体管理的服务器保持禁用 cacheToolsList。缓存条目包含的是已过滤的工具列表,而可调用过滤器的默认缓存键并不区分请求上下文。直接调用 getAllMcpTools(...) 的代码可以改为提供一个包含相关策略标识的 generateMCPToolCacheKey。请参阅 MCP 缓存指南。
RunContext 暴露的内容
Section titled “RunContext 暴露的内容”RunContext<T> 是对应用自定义上下文对象的包装。实际使用中,您最常用到的是:
runContext.context:用于保存您自己的可变应用状态和依赖项。runContext.usage:用于获取当前运行汇总的 token 和请求用量。runContext.toolInput:用于获取当前运行在agent.asTool()内部执行时的结构化输入。runContext.approveTool(...)/runContext.rejectTool(...):用于以编程方式更新审批状态。
只有 runContext.context 是应用自定义的对象。其他字段都是由 SDK 管理的运行时元数据。
如果您之后为了人机协作而序列化 RunState,这些运行时元数据会随状态一同保存。如果您打算持久化或传输序列化后的状态,请避免在 runContext.context 中放入机密信息。
如果您创建了 RunContext 的子类,请确认嵌套运行或派生运行仍会保留您所依赖的子类特有实例状态。SDK 会在嵌套运行期间于内部创建分叉上下文。
LLM 可见上下文
Section titled “LLM 可见上下文”调用 LLM 时,它唯一能看到的数据来自对话历史记录。要提供更多信息,您有以下几种方式:
- 将信息添加到智能体的
instructions中,也称为系统消息或开发者消息。它可以是静态字符串,也可以是接收上下文并返回字符串的函数。 - 调用
Runner.run()时,将信息包含在input中。这与使用 instructions 的方式类似,但可以将消息置于指令层级中较低的层级。 - 通过函数工具提供额外信息,让 LLM 可以按需获取。
- 使用检索或 Web 搜索工具,让响应以文件、数据库或 Web 中的相关数据为依据。