上下文管理

上下文是一个含义很多的术语。您可能需要关注两类主要的上下文：

代码在运行期间可访问的本地上下文：工具所需的依赖或数据、诸如 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 中——也称为 system 或 developer message。它可以是静态字符串，也可以是接收上下文并返回字符串的函数。
在调用 Runner.run() 时将其包含在 input 中。这与 instructions 的方式类似，但可以让您将消息放在命令链中更低的位置。
通过函数工具暴露这些信息，以便 LLM 按需获取数据。
使用检索或 Web 搜索工具，让响应基于来自文件、数据库或 Web 的相关数据。