> ## Documentation Index > Fetch the complete documentation index at: https://docs.coze.cn/llms.txt > Use this file to discover all available pages before exploring further. 本文介绍如何基于 OpenTelemetry 协议将 [OpenAI Agent](https://openai.github.io/openai-agents-python/) 运行过程的 Trace 数据自动上报到扣子罗盘。 ## 功能介绍 {#8f666e13} [OpenAI Agent](https://openai.github.io/openai-agents-python/) 是一个轻量级的开源框架，用于构建 AI Agent。该框架通过与 OpenTelemetry 集成，能够自动捕获 OpenAI Agent 运行过程中的关键操作和性能指标，并将这些信息作为 Trace 数据上报到扣子罗盘，完成可视化分析。本集成方案适用于监控基于 OpenAI Agent 构建的 AI 应用程序运行状态、分析其性能瓶颈及排查故障的场景。 本文以 Python SDK 为例，介绍如何通过 OpenTelemetry SDK 将应用程序的 Trace 数据上报至扣子罗盘平台，从而实现对应用程序性能和行为的高效监控与分析。 ## 准备工作 {#4c964c7c} 使用 OpenTelemetry Python SDK 前，需要先安装 Python SDK 以及相关的依赖库。 1. 安装 Python SDK。 Opentelemetry Python SDK 要求 Python 3.9 或以上版本。你可以通过如下方法查看 Python 版本 。 ```Python # 查看 Python 版本 python --version # 回显信息显示已安装 3.9.2 版本 Python 3.9.2 ``` 2. 安装依赖库。 安装 Python 依赖库，分别用于调用 AI 模型、对调用过程进行可观测性管理以及将 Trace 数据导出到后端系统。 ```Python pip install openai pip install opentelemetry-sdk pip install opentelemetry-exporter-otlp pip install openinference-instrumentation-openai_agents pip install openai-agents ``` ## 配置环境变量 {#289fe307} 在上报 Trace 数据前，你需要正确配置 OpenTelemetry 的环境变量，以确保 OpenAI Agent 能够正常调用 OpenAI 模型，并能正确发送 Trace 数据到指定的扣子罗盘空间中。环境变量配置格式及说明如下： ```Python OTEL_EXPORTER_OTLP_HEADERS=cozeloop-workspace-id={CozeLoop空间ID},Authorization=Bearer {个人访问令牌或服务访问令牌} OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.coze.cn/v1/loop/opentelemetry/v1/traces OPENAI_BASE_URL=*** OPENAI_API_KEY=*** ``` | | | \ |**环境变量** |**说明** | |---|---| | | | \ |OTEL_EXPORTER_OTLP_HEADERS |设置上报数据时所需的扣子罗盘认证信息和工作空间标识。包括如下参数： |\ | | |\ | |* cozeloop-workspace-id：配置为扣子罗盘工作空间 ID。获取步骤，请参考[获取扣子罗盘工作空间 ID](/cozeloop/get_workspace_id_and_token#01dede13)。 |\ | |* Authorization：配置为扣子罗盘的个人访问令牌或服务访问令牌。获取步骤，请参考[配置个人访问令牌](/cozeloop/authentication-for-sdk#05d27a86)、[配置服务访问令牌](/cozeloop/authentication-for-sdk#83f924a1)。 | | | | \ |OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |用于指定 OpenTelemetry 数据的上报地址，固定为 `https://api.coze.cn/v1/loop/opentelemetry/v1/traces`。 | | | | \ |OPENAI_BASE_URL |配置 OpenAI 模型的服务地址。 |\ | | |\ | |* 推荐使用方舟模型，其 BASE_URL 固定为 `https://ark.cn-beijing.volces.com/api/v3`。 |\ | |* 使用其他 OpenAI 模型时，配置为其对应的 BASE_URL 即可。 | | | | \ |OPENAI_API_KEY |配置 OpenAI 模型的 API Key。 |\ | | |\ | |* 推荐使用方舟模型，其 API Key 获取步骤，请参考 [API Key 管理](https://www.volcengine.com/docs/82379/1361424)。 |\ | |* 使用其他 OpenAI 模型时，配置为其对应的 API Key 即可。 | ## 上报 Trace {#98a1e1e3} 完成上述配置后，你可以调用 OpenAI 模型开展 AI 对话，并通过 OpenTelemetry Python SDK 上报 Trace 数据到扣子罗盘。以下示例将分别展示自动上报 Trace 数据与上报自定义 Span 节点数据的具体实现方式。 ### 自动上报 {#60c4b4a2} 在本示例中，基于 OpenAI Agent 框架构建了一个多智能体协作系统，并调用火山方舟的 doubao-1-5-vision-pro-32k-250115 模型实现多语言天气查询功能。同时，通过 OpenTelemetry SDK 自动收集和上报 OpenAI 模型执行过程中的 Trace 数据到扣子罗盘，包括 LLM 调用、Agent 执行过程、任务生命周期等数据，从而实现对 AI 模型调用过程的全面监控和分析。 ```Python import os # 全局设置 OpenAI 环境变量 os.environ['OPENAI_BASE_URL'] = 'https://ark.cn-beijing.volces.com/api/v3' os.environ['OPENAI_API_KEY'] = '***' import asyncio import time from agents._config import set_default_openai_api from agents import Agent, Runner, function_tool from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor set_default_openai_api("chat_completions") endpoint = "https://api.coze.cn/v1/loop/opentelemetry/v1/traces" tracer_provider = TracerProvider() tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter( endpoint=endpoint, headers={ "cozeloop-workspace-id": "***", # cozeloop workspace id "Authorization": "Bearer ***", # cozeloop pat or sat token } ))) tracer = tracer_provider.get_tracer(__name__) OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer_provider) @function_tool def get_weather(city: str) -> str: return f"The weather in {city} is sunny." async def task(): english_agent = Agent( name="English agent", instructions="You only speak English", model="doubao-1-5-vision-pro-32k-250115", tools=[get_weather], ) chinese_agent = Agent( name="Chinese agent", instructions="You only speak Chinese", model="doubao-1-5-vision-pro-32k-250115", ) spanish_agent = Agent( name="Spanish agent", instructions="You only speak Spanish.", model="doubao-1-5-vision-pro-32k-250115", ) triage_agent = Agent( name="Triage agent", instructions="Handoff to the appropriate agent based on the language of the request.", handoffs=[english_agent, chinese_agent, spanish_agent], model="doubao-1-5-vision-pro-32k-250115", ) # 设置自定义Span节点 root_span with tracer.start_as_current_span("root_span") as span: span.set_attribute("cozeloop.span_type", "custom") # 启动 openai agent runner result = await Runner.run(triage_agent, input="What's the weather in Shanghai?") print(result.final_output) async def main(): loop = asyncio.get_running_loop() await loop.create_task(task()) time.sleep(2) asyncio.run(main()) ``` ### 上报自定义节点 {#226e5b26} 如果你需要上报自定义的 Span 节点数据，可以使用 OpenTelemetry SDK 手动创建 Span 并上报。OpenTelemetry SDK 手动上报的节点数据支持和自动上报的节点数据串联，形成完整的 Trace 调用树。 自定义的 OpenTelemetry Span，attribute 和 event 规范需遵循 [OpenTelemetry 字段映射](https://loop.coze.cn/open/docs/cozeloop/opentelemetry_field_mapping)。 ```Python # 设置自定义Span节点 root_span with tracer.start_as_current_span("root_span") as span: span.set_attribute("cozeloop.span_type", "custom") # 启动 openai agent runner result = await Runner.run(triage_agent, input="What's the weather in Shanghai?") print(result.final_output) ``` ## 查看 Trace 数据 {#5ba25852} 上报 Trace 数据后，你可以在[扣子罗盘](https://loop.coze.cn/)的 **Trace** 页面，找到并单击目标 Span，查看上报的 Trace 数据。 ![Image=723x392](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/3146ba0c2976491fabfd847ad460ca41~tplv-goo7wpa0wc-image.image) ## 更多示例 {#732d57e5} 关于上报 OpenAI Agent Trace 数据的更多示例，请参考 [OpenAI Agent](https://github.com/coze-dev/cozeloop-examples/tree/main/python/integration/framework/openai_agent)。