上下文管理

“上下文”一词有多重含义。您可能主要关注以下两类上下文：

本地上下文：代码在运行期间可以访问的内容，包括工具、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，但默认不会获得应用状态的独立副本。

`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 可见上下文

调用 LLM 时，它只能看到对话历史记录中的数据。要让它获得更多信息，您可以使用以下几种方式：

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