# @arizeai/openinference-instrumentation-openai-agents 中文文档

规范地址：https://npmcn.com/package/%40arizeai/openinference-instrumentation-openai-agents/

版本：0\.3\.3
npm 元数据更新时间：2026-10-23T22:15:56.509Z
中文译文更新时间：2026-11-06T19:27:37.337Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arizeai/openinference-instrumentation-openai-agents
原文对照：https://npmcn.com/package/%40arizeai/openinference-instrumentation-openai-agents/?lang=original
项目主页：https://github.com/Arize-ai/openinference#readme
源码仓库：https://github.com/Arize-ai/openinference

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：802 kB，41 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：@openai/agents \>=0\.1\.0
- 首次发布：2026-06-11T17:18:09.027Z
- 最新版本发布：2026-10-23T22:15:56.171Z
- 近 30 天下载量：7190（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

OpenAI 代理 SDK 的 OpenInformation 仪器

## 安装

```sh
npm install @arizeai/openinference-instrumentation-openai-agents
```

也可以使用：`pnpm add @arizeai/openinference-instrumentation-openai-agents`、`yarn add @arizeai/openinference-instrumentation-openai-agents`、`bun add @arizeai/openinference-instrumentation-openai-agents`

## README

# OpenAI 代理 SDK (Node.js) 的 OpenInference 仪器

以 OpenTelemeth 为基础的仪器 [OpenAI 代理服务器 SDK](https://www.npmjs.com/package/@openai/agents) (单位:千美元)`@openai/agents`) (中文(简体) ). 将 SDK 的本地跟踪事件连接到 OpenTeleometry 之后的 [开源语义公约](https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md),因此可以在任何 OpenTeleometry 兼容后端中观察到代理运行,例如 [阿里兹·凤凰](https://github.com/Arize-ai/phoenix), (中文(简体) ), [调整 AX](https://arize.com/products/ax?utm_source=docs&utm_medium=web&utm_content=openinference)Jaeger 或者你的收藏家选择的.

## 安装

```bash
npm install @arizeai/openinference-instrumentation-openai-agents @arizeai/openinference-semantic-conventions @openai/agents
```

## 快速启动

```typescript
import * as agents from "@openai/agents";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { Resource } from "@opentelemetry/resources";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

import { OpenAIAgentsInstrumentation } from "@arizeai/openinference-instrumentation-openai-agents";

// 1. Configure OpenTelemetry.
const provider = new NodeTracerProvider({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: "my-agent-app",
  }),
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({ url: "http://localhost:6006/v1/traces" })),
  ],
});
provider.register();

// 2. Register the OpenInference processor with the agents SDK.
const instrumentation = new OpenAIAgentsInstrumentation({ tracerProvider: provider });
instrumentation.manuallyInstrument(agents);

// 3. Use the agents SDK as usual.
const agent = new agents.Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant.",
});

const result = await agents.run(agent, "What is the capital of France?");
console.log(result.finalOutput);
```

## 如何运作

与大多数 OpenInference 仪器不同,此软件包确实 **没有** 给SDK打个针 特工SDK曝光头等舱 `TracingProcessor` 接口; 此软件包通过 SDK 执行并注册 `setTraceProcessors` 编号 : `addTraceProcessor` APIs (英语).

| 模式 | 打电话 | 行为 |
| --- | --- | --- |
| 专属( 默认) | `instrument()` (CommonJS)或 (中文(简体) ) `manuallyInstrument(agents)` (ESM) (英语) | 以 Open Information 1 替换所有已有的微量处理器。 当 OpenTeleometry 是您唯一的追踪目的地时使用 . |
| 添加 | `instrument({ exclusiveProcessor: false })` (CommonJS)或 (中文(简体) ) `manuallyInstrument(agents, { exclusiveProcessor: false })` (ESM) (英语) | 将 OpenInference 处理器与任何已存在的处理器(例如 SDK 默认的 OpenAI 跟踪导出器)相并列. 需要 Open 推论时使用 _财务报告和审定财务报表_ OpenAI本土寻踪. |

当模块自动被补丁时(通过) `registerInstrumentations` 或 NodeSDK),通过构造器选择模式取而代之: `new OpenAIAgentsInstrumentation({ exclusiveProcessor: false })`。 。 。 .

为了停止追踪,打电话 `instrumentation.uninstrument()`。在添加剂模式下,SDK剂不会暴露出单处理器去除API,所以 `uninstrument()` 不清理其他 SDK 处理器而禁用已设置的 OpenInference 处理器.

对于仅限无害环境管理的环境,通过进口的SDK命名空间:

```typescript
import * as agents from "@openai/agents";

const instrumentation = new OpenAIAgentsInstrumentation({ tracerProvider: provider });
instrumentation.manuallyInstrument(agents, { exclusiveProcessor: false });
```

## 配置

```typescript
new OpenAIAgentsInstrumentation({
  // Optional: an OTel TracerProvider. Defaults to the global provider.
  tracerProvider,

  // Optional: processor registration mode (see "How it works" above).
  // This is the only way to choose additive mode when the module is patched
  // automatically (registerInstrumentations / NodeSDK). Defaults to true.
  exclusiveProcessor: true,

  // Optional: OpenInference trace configuration for masking/redacting
  // sensitive data on emitted spans.
  // See https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-core
  traceConfig: {
    hideInputs: true,
    hideOutputs: true,
  },

  // Optional: maximum number of root trace spans kept in memory while traces
  // are in flight. If the limit is exceeded, the oldest root span is ended
  // and evicted. Defaults to 1000.
  maxRootSpansInFlight: 1000,
});
```

## 宽幅覆盖

每个代理SDK跨度类型被映射到 OpenInference 跨度类型:

| SDK 跨度 | `openinference.span.kind` | 抓取属性 |
| --- | --- | --- |
| `agent` | `AGENT` | `graph.node.id`, (中文(简体) ), `graph.node.parent_id` (在交割目的地) |
| `generation` | `LLM` | `llm.model_name`, (中文(简体) ), `llm.invocation_parameters`, (中文(简体) ), `llm.input_messages.*`, (中文(简体) ), `llm.output_messages.*`, (中文(简体) ), `llm.token_count.{prompt,completion,total}`, (中文(简体) ), `llm.token_count.prompt_details.cache_read`, (中文(简体) ), `llm.token_count.completion_details.reasoning` |
| `response` | `LLM` | 以上全部加起来 `llm.tools.*`,系统指令作为输入消息 0 |
| `function` | `TOOL` | `tool.name`, (中文(简体) ), `input.value`, (中文(简体) ), `output.value` |
| `handoff` | `TOOL` | 扩展名 `handoff to <to_agent>`;目的地代理人收到 `graph.node.parent_id` 连接回源 |
| `mcp_tools` | `TOOL` | `output.value` (JSON工具名列表) |
| `guardrail` | `GUARDRAIL` | `tool.name`, (中文(简体) ), `guardrail.triggered` |
| `custom` | `CHAIN` | `output.value` (JSON序列化用户数据) |

两者 **聊天 补全** 财务报告和审定财务报表 **答复** 运输得到支持。 在聊天 补全模式中, SDK 将原始响应对象存储在 `output[]`; 此仪器从 `choices[].message` 并累积所有回复的符号使用.

## 实例

```bash
cd js/packages/openinference-instrumentation-openai-agents
pnpm install
pnpm -r build

OPENAI_API_KEY=sk-... npx tsx examples/chat.ts     # single agent + tool call
OPENAI_API_KEY=sk-... npx tsx examples/handoff.ts  # multi-agent handoff
OPENAI_API_KEY=sk-... npx tsx examples/streaming.ts # streamed agent run
OPENAI_API_KEY=sk-... npx tsx examples/guardrail.ts # input guardrail
```

共享的 OTel 设置在 `examples/instrumentation.ts` 修改它,以便在OTLP出口商或任何其他处理器中互换.

## 许可证

阿帕奇 - 2.0

## 快速缓存令牌计数

OpenAI 缓存读取( O)`cached_tokens`写作(`cache_write_tokens`)记录为 `llm.token_count.prompt_details.cache_read` 财务报告和审定财务报表 `cache_write`见 [语义公约](https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md#token-count-details) 说明这些分项与及时总数的关系,以及 [缓存符号示例](https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-openai/examples/cache_tokens.md) 凤凰城的往返旅行.

## 常见问题

### @arizeai/openinference-instrumentation-openai-agents 是什么？

OpenAI 代理 SDK 的 OpenInformation 仪器

### 如何安装 @arizeai/openinference-instrumentation-openai-agents？

在项目目录运行 npm install @arizeai/openinference-instrumentation-openai-agents，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@openai/agents（\>=0\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @arizeai/openinference-instrumentation-openai-agents 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @arizeai/openinference-instrumentation-openai-agents 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @arizeai/openinference-instrumentation-openai-agents 可以商用吗？

@arizeai/openinference-instrumentation-openai-agents 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @arizeai/openinference-instrumentation-openai-agents 的下载量有多少？

根据 npm 官方下载统计，@arizeai/openinference-instrumentation-openai-agents 在 2026/10/07 – 2026/11/05 这 30 天内被下载 7,190 次，日均约 240 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arizeai/openinference-instrumentation-openai-agents 还在维护吗？

最新版本 0\.3\.3 发布于 2026/10/24（14 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/06/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。