跳转到内容

上下文管理

“上下文”一词有多种含义。您可能需要关注的上下文主要分为两类:

  1. 本地上下文:代码在运行期间可以访问的上下文,包括工具、onHandoff 等回调和生命周期钩子所需的依赖项或数据。
  2. 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,但默认情况下不会获得应用状态的独立副本。

当函数工具、本地 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<T> 是对应用自定义上下文对象的包装。实际使用中,您最常用到的是:

  • runContext.context:用于保存您自己的可变应用状态和依赖项。
  • runContext.usage:用于获取当前运行汇总的 token 和请求用量。
  • runContext.toolInput:用于获取当前运行在 agent.asTool() 内部执行时的结构化输入。
  • runContext.approveTool(...) / runContext.rejectTool(...):用于以编程方式更新审批状态。

只有 runContext.context 是应用自定义的对象。其他字段都是由 SDK 管理的运行时元数据。

如果您之后为了人机协作而序列化 RunState,这些运行时元数据会随状态一同保存。如果您打算持久化或传输序列化后的状态,请避免在 runContext.context 中放入机密信息。

如果您创建了 RunContext 的子类,请确认嵌套运行或派生运行仍会保留您所依赖的子类特有实例状态。SDK 会在嵌套运行期间于内部创建分叉上下文。

调用 LLM 时,它唯一能看到的数据来自对话历史记录。要提供更多信息,您有以下几种方式:

  1. 将信息添加到智能体的 instructions 中,也称为系统消息或开发者消息。它可以是静态字符串,也可以是接收上下文并返回字符串的函数。
  2. 调用 Runner.run() 时,将信息包含在 input 中。这与使用 instructions 的方式类似,但可以将消息置于指令层级中较低的层级。
  3. 通过函数工具提供额外信息,让 LLM 可以按需获取。
  4. 使用检索或 Web 搜索工具,让响应以文件、数据库或 Web 中的相关数据为依据。