工具

工具让智能体能够执行操作——获取数据、调用外部 API、执行代码，甚至操作计算机。JavaScript/TypeScript SDK 支持七个类别：

当您已阅读智能体，明确应由哪个智能体负责该任务，并希望赋予它相应能力后，再阅读此页面。如果您仍在选择不同的委派模式，请参阅智能体编排。

1. OpenAI 托管工具——与模型一同在 OpenAI 服务器上运行。（Web 搜索、文件搜索、Code Interpreter、图像生成、工具搜索）
2. 内置执行工具——由 SDK 提供、在模型之外执行的工具。（计算机操作和 apply_patch 在本地运行；shell 可以在本地或托管容器中运行）
3. 函数工具——使用 JSON Schema 封装任意本地函数，以便 LLM 调用。
4. Agents as tools——将整个智能体公开为可调用工具。
5. MCP 服务器——连接本地或远程的 Model Context Protocol 服务器。
6. 沙盒能力——将工作区范围内的 shell、文件系统、技能、记忆或压缩工具连接到 SandboxAgent。
7. 实验性功能：Codex 工具——将 Codex SDK 封装为函数工具，以运行可感知工作区的任务。

---

工具类别

本指南的其余部分将首先介绍每种工具类别，然后总结贯穿各类别的工具选择和提示指导。

1. 托管工具（OpenAI Responses API）

使用 OpenAIResponsesModel 时，可以添加以下内置工具：

工具	类型字符串	用途
Web 搜索	'web_search'	互联网搜索。
文件/检索搜索	'file_search'	查询托管在 OpenAI 上的向量存储。
Code Interpreter	'code_interpreter'	在沙盒环境中运行代码。
图像生成	'image_generation'	根据文本生成图像。
工具搜索	'tool_search'	在运行时加载延迟加载的函数工具、命名空间或可搜索的 MCP 工具。
编程式工具调用	'programmatic_tool_calling'	运行模型生成的 JavaScript，以协调符合条件的工具。

托管工具

import {
  Agent,
  codeInterpreterTool,
  fileSearchTool,
  imageGenerationTool,
  webSearchTool,
} from '@openai/agents';

const agent = new Agent({
  name: 'Travel assistant',
  tools: [
    webSearchTool({ searchContextSize: 'medium' }),
    fileSearchTool('VS_ID', { maxNumResults: 3 }),
    codeInterpreterTool(),
    imageGenerationTool({ size: '1024x1024' }),
  ],
});

SDK 提供了用于返回托管工具定义的辅助函数：

辅助函数	说明
webSearchTool(options?)	适合 JS 使用的选项，例如 searchContextSize、userLocation、filters.allowedDomains、searchContentTypes 和 imageSettings。
fileSearchTool(ids, options?)	第一个参数接受一个或多个向量存储 ID，并支持 maxNumResults、includeSearchResults、rankingOptions 和过滤器等选项。
codeInterpreterTool(options?)	未提供 container 时，默认使用自动管理的容器。
imageGenerationTool(options?)	支持图像生成配置，例如 model、size、quality、background、inputFidelity、inputImageMask、moderation、outputCompression、partialImages 和输出格式。
toolSearchTool(options?)	添加内置的 tool_search 辅助工具。可与设置了 deferLoading: true 的延迟加载函数工具或托管 MCP 工具配合使用。默认支持托管执行，也支持通过 execution: 'client' 和 execute 进行客户端执行。
programmaticToolCallingTool()	启用编程式工具调用。可与 allowedCallers 包含 'programmatic' 的工具配合使用。

这些辅助函数会将适合 JavaScript/TypeScript 使用的选项名称映射到对应的 OpenAI Responses API 工具载荷。若要请求图像搜索结果，请在 webSearchTool({ searchContentTypes }) 中包含 'image'。使用 imageSettings.maxResults 请求大于零的图像数量，并使用 imageSettings.caption 请求可用的说明文字。当 searchContentTypes 包含 'image' 时，SDK 会请求原始 Web 搜索结果，并通过 Web 搜索调用项的 providerData.results 公开返回的图像 URL 和元数据。

有关完整的工具模式和高级选项（例如排序选项或语义过滤器），请参阅官方 OpenAI 工具指南；有关图像结果字段，请参阅官方 Web 搜索指南；有关当前的内置工具搜索流程和模型可用性，请参阅官方工具搜索指南；有关模型支持和底层协议行为，请参阅官方编程式工具调用指南。

---

2. 内置执行工具

这些工具内置于 SDK 中，但执行发生在模型响应本身之外：

• 计算机操作——实现 Computer 接口并将其传递给 computerTool()。它始终使用您提供的本地 Computer 实现运行。
• Shell——提供本地 Shell 实现，或通过 shellTool({ environment }) 配置托管容器环境。
• 应用补丁——实现 Editor 接口并将其传递给 applyPatchTool()。它始终使用您提供的本地 Editor 实现运行。
• 沙盒 shell 和文件系统工具——当相关操作应在沙盒工作区内运行时，在 SandboxAgent 上使用 shell()、filesystem()、skills()、memory() 或 compaction()。

工具调用仍由模型发起，但实际工作由您的应用程序或配置的执行环境完成。

沙盒能力工具不同于进程范围的内置工具：它们绑定到当前 SandboxAgent 运行的实时沙盒会话。当工具应操作智能体的隔离工作区，而不是您的应用程序进程时，请使用快速入门。

内置执行工具

import {
  Agent,
  applyPatchTool,
  computerTool,
  shellTool,
  Computer,
  Editor,
  Shell,
} from '@openai/agents';

const computer: Computer = {
  environment: 'browser',
  dimensions: [1024, 768],
  screenshot: async () => '',
  click: async () => {},
  doubleClick: async () => {},
  scroll: async () => {},
  type: async () => {},
  wait: async () => {},
  move: async () => {},
  keypress: async () => {},
  drag: async () => {},
};

const shell: Shell = {
  run: async () => ({
    output: [
      {
        stdout: '',
        stderr: '',
        outcome: { type: 'exit', exitCode: 0 },
      },
    ],
  }),
};

const editor: Editor = {
  createFile: async () => ({ status: 'completed' }),
  updateFile: async () => ({ status: 'completed' }),
  deleteFile: async () => ({ status: 'completed' }),
};

const agent = new Agent({
  name: 'Local tools agent',
  model: 'gpt-5.4',
  tools: [
    computerTool({ computer }),
    shellTool({ shell, needsApproval: true }),
    applyPatchTool({ editor, needsApproval: true }),
  ],
});

计算机工具详情

computerTool() 接受以下任一项：

• 具体的 Computer 实例。
• 为每次运行创建 Computer 的初始化函数。
• 当您需要运行范围内的初始化和清理时，使用包含 { create, dispose } 的提供程序对象。

若要使用 OpenAI 当前的计算机操作路径，请设置支持计算机操作的模型，例如 gpt-5.4。当请求模型已明确指定时，SDK 会发送正式发布版内置 computer 工具的结构。如果实际使用的模型仍来自已存储的提示或其他较旧的集成，SDK 会继续使用旧版 computer_use_preview 协议结构以保持兼容，除非您通过 modelSettings.toolChoice: 'computer' 明确选择正式发布版路径。

正式发布版计算机调用可在单个 computer_call 中包含批量的 actions[]。SDK 会按顺序执行这些操作，针对每个操作评估 needsApproval，并将最终屏幕截图作为工具输出返回。如果您使用 interruption.rawItem 构建审批界面，请在存在 actions 时读取它，否则回退到用于旧版预览项的 action。

当高影响的计算机操作需要暂停并由用户审核时，请使用 needsApproval；当您希望确认或拒绝为计算机调用报告的待处理安全检查时，请使用 onSafetyCheck。有关模型端指导和迁移详情，请参阅官方 OpenAI 计算机操作指南及其迁移说明。

Shell 工具详情

shellTool() 有两种模式：

• 本地模式：提供 shell，还可以选择提供 environment: { type: 'local', skills }，并使用 needsApproval 和 onApproval 进行自动审批处理。
• 托管容器模式：提供 type 为 'container_auto' 或 'container_reference' 的 environment。

在本地模式下，environment.skills 允许您通过 name、description 和文件系统 path 挂载本地技能。

在托管容器模式下，使用以下任一种方式配置 shellTool({ environment })：

• 使用 type: 'container_auto' 为本次运行创建托管容器。
• 使用 type: 'container_reference' 通过 containerId 复用现有容器。

托管的 container_auto 环境支持：

• networkPolicy，包括带有 domainSecrets 的允许列表。
• 用于挂载已上传文件的 fileIds。
• 用于设置容器规格的 memoryLimit。
• skills，可使用 skill_reference 或内联 zip 包。

托管 shell 环境不接受 shell、needsApproval 或 onApproval，因为执行发生在托管容器环境中，而不是您的本地进程中。

有关端到端用法，请参阅 examples/tools/local-shell.ts、examples/tools/container-shell-skill-ref.ts 和 examples/tools/container-shell-inline-skill.ts。

应用补丁工具详情

applyPatchTool() 沿用 shellTool() 的本地审批流程：使用 needsApproval 在编辑文件前暂停；当您希望通过应用级回调自动批准或拒绝时，使用 onApproval。

---

3. 函数工具

您可以使用 tool() 辅助函数将任意函数转换为工具。

使用 Zod 参数的函数工具

import { tool } from '@openai/agents';
import { z } from 'zod';

const getWeatherTool = tool({
  name: 'get_weather',
  description: 'Get the weather for a given city',
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

选项参考

字段	必需	说明
name	否	默认为函数名称（例如 get_weather）。
description	是	向 LLM 显示的清晰、易于理解的说明。
parameters	是	Zod 模式、受支持的 Standard Schema 值或原始 JSON Schema 对象。验证模式会自动启用严格模式。
strict	否	为 true（默认值）时，如果参数未通过验证，SDK 会返回模型错误。设置为 false 可使用模糊匹配。
execute	是	(args, context, details) => string | unknown | Promise<...>——您的业务逻辑。非字符串输出会进行序列化后提供给模型。context 是可选的 RunContext；details 包含 toolCall、resumeState 和 signal 等元数据。
allowedCallers	否	仅适用于 Responses 的非空列表，用于控制工具可以被直接调用、以编程方式调用，还是两者皆可。使用 'direct'、'programmatic' 或同时使用这两个值。
outputSchema	否	仅适用于 Responses 的工具结果模式。Zod 模式会约束 execute 的返回类型，并验证和转换运行时结果；原始 JSON Schema 仅描述协议契约。
errorFunction	否	自定义处理程序 (context, error, details) => result，用于将内部错误转换为模型可见的结果。设置 outputSchema 时，结果必须符合该模式。默认处理程序处于禁用状态，因此原始错误会被重新抛出。
timeoutMs	否	每次调用的超时时间，以毫秒为单位。必须大于 0 且小于或等于 2147483647。
timeoutBehavior	否	超时模式：error_as_result 返回模型可见的结果，raise_exception 抛出 ToolTimeoutError。未设置 outputSchema 时默认为 error_as_result；设置后默认为 raise_exception。
timeoutErrorFunction	否	error_as_result 的自定义处理程序 (context, timeoutError, details) => result。设置 outputSchema 时，必须提供此处理程序，且其结果必须符合该模式。
customDataExtractor	否	回调 (context) => Record<string, unknown> | null | undefined，用于将仅供 SDK 使用的元数据附加到生成的 RunToolCallOutputItem.customData。这些数据不会发送回模型。
needsApproval	否	执行前需要人工批准。请参阅人机协作。
isEnabled	否	按每次运行有条件地公开工具；接受布尔值或谓词。
inputGuardrails	否	工具执行前运行的护栏；可以拒绝或抛出错误。请参阅护栏。
outputGuardrails	否	工具执行后运行的护栏；可以拒绝或抛出错误。请参阅护栏。

条件式工具可用性

使用 isEnabled 控制请求范围内的能力可见性、特定环境中的可用性、功能标志或实验。运行器会在准备当前轮次对模型可见的工具集时评估该谓词。

isEnabled 不能取代依赖工具参数或所访问资源的授权，因为谓词会在模型生成这些参数之前运行。请在 execute 中实施参数级和资源级授权，或在适当时添加工具输入护栏和审批。MCP 服务器必须对自身受保护的操作进行授权。有关将同一应用策略应用于函数工具、本地 MCP 工具和交接的模式，请参阅上下文管理。

受支持的 Standard Schema 参数会转换为供模型使用的 JSON Schema，并在 execute 运行前于本地进行验证。验证输出类型（包括库转换和默认值）将成为推断出的 execute 参数类型。有关 Valibot 代码示例和当前限制，请参阅模式验证。

仅供 SDK 使用的自定义数据

当您的应用程序需要在工具结果旁提供渲染提示、内部 ID 或其他与 JSON 兼容的元数据时，请使用 customDataExtractor。该回调会接收运行上下文、工具定义、模型工具调用、已解析输入、输出以及克隆的原始输出项。返回的数据存储在 RunToolCallOutputItem.customData 和 RunState 中，但会从 history 和模型重放中排除。

函数工具超时

使用 timeoutMs 限制每次函数工具调用的时长。

• timeoutBehavior: 'error_as_result' 向模型返回 Tool '<name>' timed out after <timeoutMs>ms.。未设置 outputSchema 时，这是默认行为。
• timeoutBehavior: 'raise_exception' 抛出 ToolTimeoutError，您可以将其作为运行异常的一部分进行捕获。
• timeoutErrorFunction 允许您在 error_as_result 模式下自定义超时文本。
• 设置 outputSchema 后，默认行为会更改为 raise_exception。使用 error_as_result 时，必须提供返回符合模式值的 timeoutErrorFunction。
• 超时会中止 details.signal，因此监听取消信号的长时间运行工具可以及时停止。

如果直接调用函数工具，请使用 invokeFunctionTool，以实施与正常智能体运行相同的超时行为。

非严格 JSON Schema 工具

如果需要模型推测无效或不完整的输入，可以在使用原始 JSON Schema 时禁用严格模式：

非严格 JSON Schema 工具

import { tool } from '@openai/agents';

interface LooseToolInput {
  text: string;
}

const looseTool = tool({
  description: 'Echo input; be forgiving about typos',
  strict: false,
  parameters: {
    type: 'object',
    properties: { text: { type: 'string' } },
    required: ['text'],
    additionalProperties: true,
  },
  execute: async (input) => {
    // because strict is false we need to do our own verification
    if (typeof input !== 'object' || input === null || !('text' in input)) {
      return 'Invalid input. Please try again';
    }
    return (input as LooseToolInput).text;
  },
});

使用工具搜索进行延迟加载

工具搜索允许模型仅在运行时加载所需的工具定义，而无需预先发送所有模式。在 SDK 中，您可以通过这种方式使用延迟加载的顶层函数工具、toolNamespace() 组，以及配置了 deferLoading: true 的托管 MCP 工具。

仅将工具搜索与 GPT-5.4 及更新的、在 Responses API 中支持该功能的模型版本配合使用。

使用工具搜索进行延迟加载

import { Agent, tool, toolNamespace, toolSearchTool } from '@openai/agents';
import { z } from 'zod';

const customerIdParams = z.object({
  customerId: z.string().describe('The customer identifier to look up.'),
});

// Keep a standalone deferred tool at the top level when it represents a
// single searchable capability that does not need a shared namespace.
const shippingLookup = tool({
  name: 'get_shipping_eta',
  description: 'Look up a shipment ETA by customer identifier.',
  parameters: customerIdParams,
  deferLoading: true,
  async execute({ customerId }) {
    return {
      customerId,
      eta: '2026-03-07',
      carrier: 'Priority Express',
    };
  },
});

// Group related tools into a namespace when one domain description should
// cover several deferred tools and let tool search load them together.
const crmTools = toolNamespace({
  name: 'crm',
  description: 'CRM tools for customer profile lookups.',
  tools: [
    tool({
      name: 'get_customer_profile',
      description: 'Fetch a basic customer profile.',
      parameters: customerIdParams,
      deferLoading: true,
      async execute({ customerId }) {
        return {
          customerId,
          tier: 'enterprise',
        };
      },
    }),
  ],
});

const agent = new Agent({
  name: 'Operations assistant',
  model: 'gpt-5.4',
  // Mixing namespaced and top-level deferred tools in one request is supported.
  tools: [shippingLookup, ...crmTools, toolSearchTool()],
});

该代码示例有意混合了两种样式：

• shippingLookup 保留在顶层，因为它是一个独立的可搜索能力。
• crmTools 使用 toolNamespace()，因为相关的 CRM 工具共享一个高级标签和说明。
• 支持在同一请求中混合使用带命名空间和顶层的延迟加载工具；工具搜索可以同时加载 crm 等命名空间路径和 get_shipping_eta 等顶层路径。

使用工具搜索时：

• 使用 deferLoading: true 标记每个延迟加载的函数工具。
• 当多个相关工具应共享一个领域说明并作为一组加载时，使用 toolNamespace({ name, description, tools })。
• 当工具是单个独立能力，且工具名称本身适合作为搜索目标时，将其保留在顶层。
• 只要有任何延迟加载的函数工具或托管 MCP 工具使用 deferLoading: true，就应将 toolSearchTool() 添加到同一个 tools 数组中。
• 将 modelSettings.toolChoice 保持为 'auto'。SDK 不允许强制指定内置 tool_search 工具或按名称指定延迟加载的函数工具。
• 默认使用托管执行。如果设置 toolSearchTool({ execution: 'client', execute })，标准 run() 循环仅支持内置的 { paths: string[] } 客户端查询结构；自定义客户端模式需要您自行实现 Responses 循环。
• 一个命名空间可以混合包含立即加载和延迟加载的成员。立即加载的成员无需工具搜索即可调用，而同一命名空间中的延迟加载成员则按需加载。
• 工具发现结果归执行搜索的智能体所有，不会随交接转移。当该智能体的名称在运行图中唯一时，SDK 会在通过历史记录或 Session 重放同一逻辑智能体时保留发现结果。如果缺少归属信息或归属存在歧义，则必须重新搜索。因此，如果持久化的发现结果需要在重建后继续使用，请为智能体设置唯一名称。
• 延迟加载的函数工具和 toolNamespace() 仅适用于 Responses。Chat Completions 会拒绝它们，AI SDK 适配器也不支持延迟加载 Responses 工具的流程。

---

4. Agents as tools

有时，您希望一个智能体协助另一个智能体，而不是完全交接对话。请使用 agent.asTool()：

如果您仍在 agent.asTool() 和 handoff() 之间做选择，请比较智能体和智能体编排中的模式。

Agents as tools

import { Agent } from '@openai/agents';

const summarizer = new Agent({
  name: 'Summarizer',
  instructions: 'Generate a concise summary of the supplied text.',
});

const summarizerTool = summarizer.asTool({
  toolName: 'summarize_text',
  toolDescription: 'Generate a concise summary of the supplied text.',
});

const mainAgent = new Agent({
  name: 'Research assistant',
  tools: [summarizerTool],
});

在底层，SDK 会：

• 创建一个包含单个 input 参数的函数工具。
• 调用该工具时，使用该输入运行子智能体。
• 返回最后一条消息，或返回由 customOutputExtractor 提取的输出。

当智能体作为工具运行时，Agents SDK 会创建一个 Runner，并使用该运行器在函数工具调用内执行智能体。传递 runConfig 以配置嵌套运行器，传递 runOptions 以配置嵌套运行。

您还可以通过 asTool() 选项为智能体工具设置 needsApproval 和 isEnabled，以便与人工干预流程和条件式工具可用性集成。

在 customOutputExtractor 中，使用 result.agentToolInvocation 检查当前的 Agent.asTool() 调用。在该回调中，结果始终来自 Agent.asTool()，因此 agentToolInvocation 始终已定义，并公开 toolName、toolCallId 和 toolArguments。使用 result.runContext.context 获取应用程序上下文。使用默认的单 input 模式时，result.runContext.toolInput 未定义；请改用 result.agentToolInvocation.toolArguments 读取调用参数。配置自定义 parameters 或 inputBuilder 时，result.runContext.toolInput 会包含捕获的结构化参数。agentToolInvocation 元数据的作用域仅限当前嵌套调用，不会序列化到 RunState 中。

读取智能体工具调用元数据

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Handle billing questions and subscription changes.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  customOutputExtractor(result) {
    console.log('tool', result.agentToolInvocation.toolName);
    // Direct invoke() calls may not have a model-generated tool call id.
    console.log('call', result.agentToolInvocation.toolCallId);
    console.log('args', result.agentToolInvocation.toolArguments);

    return String(result.finalOutput ?? '');
  },
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

agent.asTool() 的高级结构化输入选项：

• parameters：使用 Zod 模式、受支持的 Standard Schema 值或原始 JSON Schema 替换默认的 { input: string } 结构。
• inputBuilder：将结构化工具参数映射到嵌套智能体的输入载荷。
• includeInputSchema：在嵌套运行中包含输入 JSON Schema，以获得更强的模式感知行为。
• resumeState：控制恢复嵌套的序列化 RunState 时所用的上下文协调策略：'merge'（默认值）将实时审批/上下文状态合并到序列化状态中；'replace' 改用当前运行上下文；'preferSerialized' 使用未更改的序列化上下文恢复运行。

智能体工具的流式事件

智能体工具可以将所有嵌套运行事件以流式方式传回您的应用程序。请根据工具的构建方式选择合适的钩子样式：

智能体工具的流式传输

import { Agent } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing Agent',
  instructions: 'Answer billing questions and compute simple charges.',
});

const billingTool = billingAgent.asTool({
  toolName: 'billing_agent',
  toolDescription: 'Handles customer billing questions.',
  // onStream: simplest catch-all when you define the tool inline.
  onStream: (event) => {
    console.log(`[onStream] ${event.event.type}`, event);
  },
});

// on(eventName) lets you subscribe selectively (or use '*' for all).
billingTool.on('run_item_stream_event', (event) => {
  console.log('[on run_item_stream_event]', event);
});
billingTool.on('raw_model_stream_event', (event) => {
  console.log('[on raw_model_stream_event]', event);
});

const orchestrator = new Agent({
  name: 'Support Orchestrator',
  instructions: 'Delegate billing questions to the billing agent tool.',
  tools: [billingTool],
});

• 事件类型与 RunStreamEvent['type'] 一致：raw_model_stream_event、run_item_stream_event、agent_updated_stream_event。
• onStream 是最简单的”捕获全部”方式，很适合以内联方式声明工具时使用（tools: [agent.asTool({ onStream })]）。如果不需要按事件路由，请使用此方式。
• on(eventName, handler) 允许您选择性订阅事件（也可以使用 '*'），最适合需要更精细的处理，或希望在创建后附加监听器的场景。
• 如果提供 onStream 或任意 on(...) 处理程序，作为工具的智能体会自动以流式传输模式运行；如果均未提供，则使用非流式传输路径。
• 处理程序会并行调用，因此缓慢的 onStream 回调不会阻塞 on(...) 处理程序，反之亦然。
• 通过模型工具调用来调用工具时，会提供 toolCallId；直接调用 invoke() 或提供程序的特殊行为可能会导致其缺失。

---

5. MCP 服务器

您可以通过 Model Context Protocol (MCP) 服务器公开工具，并将其连接到智能体。例如，可以使用 MCPServerStdio 启动并连接 stdio MCP 服务器：

本地 MCP 服务器

import { Agent, MCPServerStdio } from '@openai/agents';

const server = new MCPServerStdio({
  fullCommand: 'pnpm exec mcp-server-filesystem ./sample_files',
});

await server.connect();

const agent = new Agent({
  name: 'Assistant',
  mcpServers: [server],
});

有关完整代码示例，请参阅 filesystem-example.ts。此外，如果您需要 MCP 服务器工具集成的完整指南，请参阅 MCP 集成了解详情。管理多个服务器（或部分故障）时，请使用 connectMcpServers，并遵循 MCP 集成中的生命周期指导。

---

6. 实验性功能：Codex 工具

@openai/agents-extensions/experimental/codex 提供了 codexTool()。这是一个函数工具，会将模型工具调用路由到 Codex SDK，使智能体可以自主运行工作区范围内的任务（shell、文件编辑、MCP 工具）。此接口为实验性功能，可能会发生变化。

请先安装依赖项：

npm install @openai/agents-extensions @openai/codex-sdk

快速开始：

实验性 Codex 工具

import { Agent } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

export const codexAgent = new Agent({
  name: 'Codex Agent',
  instructions:
    'Use the codex tool to inspect the workspace and answer the question. When skill names, which usually start with `$`, are mentioned, you must rely on the codex tool to use the skill and answer the question.',
  tools: [
    codexTool({
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        networkAccessEnabled: true,
        webSearchEnabled: false,
      },
    }),
  ],
});

注意事项：

• 身份验证：提供 CODEX_API_KEY（推荐）或 OPENAI_API_KEY，也可以传递 codexOptions.apiKey。
• 输入：使用严格模式——inputs 必须包含至少一个 { type: 'text', text } 或 { type: 'local_image', path }。
• 安全性：将 sandboxMode 与 workingDirectory 配合使用；如果该目录不是 Git 仓库，请设置 skipGitRepoCheck。
• 线程：useRunContextThreadId: true 会读取最新线程 ID 并将其存储在 runContext.context 中，这对于在应用状态中跨轮次复用非常有用。
• 线程 ID 优先级：工具调用的 threadId（如果您的模式中包含它）优先级最高，其次是运行上下文线程 ID，最后是 codexTool({ threadId })。
• 运行上下文键：当 name: 'codex' 时，默认为 codexThreadId；对于 name: 'engineer' 等名称，默认为 codexThreadId_<suffix>（规范化后为 codex_engineer）。
• 可变上下文要求：启用 useRunContextThreadId 时，应向 run(..., { context }) 传递可变对象或 Map。
• 命名：工具名称会规范化到 codex 命名空间中（engineer 会变为 codex_engineer），并且智能体中不允许出现重复的 Codex 工具名称。
• 流式传输：onStream 会同步 Codex 事件（推理、命令执行、MCP 工具调用、文件更改、Web 搜索），以便您记录或追踪进度。
• 输出：工具结果包含 response、usage 和 threadId，Codex token 用量会记录在 RunContext 中。
• 结构：outputSchema 可以是描述符、JSON Schema 对象或 Zod 对象。对于 JSON 对象模式，additionalProperties 必须为 false。

运行上下文线程复用代码示例：

Codex 运行上下文线程复用

import { Agent, run } from '@openai/agents';
import { codexTool } from '@openai/agents-extensions/experimental/codex';

// Derived from codexTool({ name: 'engineer' }) when runContextThreadIdKey is omitted.
type ExampleContext = {
  codexThreadId_engineer?: string;
};

const agent = new Agent<ExampleContext>({
  name: 'Codex assistant',
  instructions: 'Use the codex tool for workspace tasks.',
  tools: [
    codexTool({
      // `name` is optional for a single Codex tool.
      // We set it so the run-context key is tool-specific and to avoid collisions when adding more Codex tools.
      name: 'engineer',
      // Reuse the same Codex thread across runs that share this context object.
      useRunContextThreadId: true,
      sandboxMode: 'workspace-write',
      workingDirectory: '/path/to/repo',
      defaultThreadOptions: {
        model: 'gpt-5.4',
        approvalPolicy: 'never',
      },
    }),
  ],
});

// The default key for useRunContextThreadId with name=engineer is codexThreadId_engineer.
const context: ExampleContext = {};

// First turn creates (or resumes) a Codex thread and stores the thread ID in context.
await run(agent, 'Inspect src/tool.ts and summarize it.', { context });
// Second turn reuses the same thread because it shares the same context object.
await run(agent, 'Now list refactoring opportunities.', { context });

const threadId = context.codexThreadId_engineer;

---

编程式工具调用

编程式工具调用允许受支持的 Responses 模型生成 JavaScript，在托管执行环境中协调多次工具调用。您的应用程序仍会执行由客户端控制的工具，因此现有的验证、权限、审批、护栏和副作用仍然适用。

编程式工具调用

import { Agent, programmaticToolCallingTool, tool } from '@openai/agents';
import { z } from 'zod';

const getInventory = tool({
  name: 'get_inventory',
  description: 'Return inventory for a SKU.',
  parameters: z.object({ sku: z.string() }),
  allowedCallers: ['programmatic'],
  outputSchema: z.object({
    sku: z.string(),
    availableUnits: z.number(),
  }),
  async execute({ sku }) {
    return { sku, availableUnits: 42 };
  },
});

const getDemand = tool({
  name: 'get_demand',
  description: 'Return requested units for a SKU.',
  parameters: z.object({ sku: z.string() }),
  allowedCallers: ['programmatic'],
  outputSchema: z.object({
    sku: z.string(),
    requestedUnits: z.number(),
  }),
  async execute({ sku }) {
    return { sku, requestedUnits: 31 };
  },
});

const agent = new Agent({
  name: 'Inventory planner',
  model: 'gpt-5.6',
  instructions: `
Use Programmatic Tool Calling to fetch inventory and demand concurrently.
Return the source values and the calculated shortage in the final answer.
  `.trim(),
  tools: [getInventory, getDemand, programmaticToolCallingTool()],
});

设置分为两部分：

1. 将 programmaticToolCallingTool() 添加到智能体。
2. 在生成的程序可以调用的每个工具上设置 allowedCallers。

allowedCallers	行为
省略或 ['direct']	模型可以直接调用该工具。
['programmatic']	只有生成的程序可以调用该工具。
['direct', 'programmatic']	模型或生成的程序都可以调用该工具。

SDK 支持通过编程方式调用使用 tool() 创建的工具、本地或托管的 shellTool()、applyPatchTool()、hostedMcpTool() 和 codeInterpreterTool()。

SDK 会在发送请求前验证配置。仅允许编程式调用的工具需要 programmaticToolCallingTool()。除非请求中包含工具搜索，或包含能够提供符合条件工具的已存储提示，否则该辅助工具还要求至少有一个符合条件的工具。

当函数工具必须返回结构化数据时，请使用 outputSchema。Zod 模式会约束 execute 的返回类型，并验证和转换运行时结果。原始 JSON Schema 描述协议契约，但不会添加 SDK 端的结果验证。无效的 Zod 结果会引发 InvalidToolOutputError。

structured outputs 也会改变失败处理方式：

• 默认的 errorFunction 处于禁用状态，因此执行错误会被重新抛出。自定义处理程序必须返回与 outputSchema 兼容的值。
• 默认超时行为会变为 'raise_exception'。
• 若要使用 'error_as_result'，请提供返回值符合 outputSchema 的 timeoutErrorFunction。
• 输出护栏替换的值也必须符合 outputSchema。

编程式工具调用仅适用于 Responses。Chat Completions、Voice agents 和 AI SDK 模型适配器会拒绝这些选项。当符合条件的工具采用延迟加载时，必须先由工具搜索加载它，后续生成的程序才能调用它。

有关完整代码示例，请参阅 examples/tools/programmatic-tool-calling.ts。

---

工具策略与最佳实践

工具使用行为

有关如何控制模型何时以及如何使用工具（modelSettings.toolChoice、toolUseBehavior 等），请参阅智能体。

---

最佳实践

• 简短、明确的说明——说明工具能做什么以及何时使用。
• 输入验证——尽可能使用 Zod 或受支持的 Standard Schema 值进行严格的 JSON 验证。
• 避免在错误处理程序中产生副作用——errorFunction 应返回有帮助的字符串，而不是抛出错误。
• 每个工具只承担一种职责——小型、可组合的工具有助于模型进行更好的推理。

---

相关指南

• 智能体：定义配备工具的智能体并控制 toolUseBehavior。
• 智能体编排：决定何时使用 Agents as tools，何时使用交接。
• 运行智能体：了解执行流程、流式传输和对话状态。
• 模型：了解托管 OpenAI 模型配置和 Responses 传输选项。
• 护栏：验证工具输入或输出。
• 深入查阅 tool() 和各种托管工具类型的 TypeDoc 参考文档。