日志服务 接入 OpenAI Agent SDK 数据

一、操作场景

接入完成后，你可以在 Agent 可观测控制台查看以下信息：

·单次 Runner.run() 或 Runner.run_sync() 的完整调用链路，以及 Agent、推理轮次、模型调用和工具调用之间的父子关系。

·模型调用的输入 Token、输出 Token、首 Token 延迟（TTFT）、结束原因、输入消息和输出消息。

·工具名称、调用参数、返回结果、错误类型和错误信息。

·子 Agent 的嵌套关系，以及各层 Agent 的模型调用次数、工具调用次数和 Token 用量。

·同一会话下多轮请求的关联关系。

这篇提供以下两种接入方式，你可根据实际情况选择：

二、前提条件

接入前，请确认已完成以下准备工作：

·已开通 日志服务 CLS。

·已准备具备 CLS 写入权限的访问凭证，例如 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息请前往 API 密钥管理 获取，密钥需对目标主题有写入权限，权限模板参见 采集 Agent 可观测数据。

·已获取接入所需的地域接入点（endpoint）：即 Agent 应用所在地域的 CLS 接入点域名，请参见 地域和访问域名。以广州地域为例，方式一中对应填写 Region（如 ap-guangzhou）；方式二中对应填写域名，内网域名为 ap-guangzhou.cls.tencentyun.com，外网域名为 ap-guangzhou.cls.tencentcs.com。

三、方式一：通过 Skill 快速接入与分析

如果你使用支持 Skill 的 AI 工具，可使用 腾讯云 Agent 可观测助手 自动完成接入与分析。该 Skill 可创建或复用日志主题，识别 OpenAI Agent 项目并完成 SDK 安装、配置和验证。

在 AI 工具中输入以下内容：

请使用腾讯云 Agent 可观测助手 Skill：https://skillhub.cn/skills/tencentcloud-cls-agent-obs帮我把当前 OpenAI Agent 接入腾讯云 Agent 可观测。

接入完成后，你还可以直接描述分析需求。例如：

分析这个 Agent 最近 1 小时的运行情况，定位耗时最高、Token 消耗最多和失败最多的模型或工具调用。

四、方式二：手动配置接入

如果你需要精细控制 SDK、日志主题或访问凭证等参数，或者所用工具不支持 Skill，请按以下步骤手动完成接入。

五、步骤1：创建 Agent 可观测应用

1. 进入 日志服务控制台 > Agent 可观测 页面。

2. 单击应用接入，根据页面提示创建应用。

3. 在新创建的应用右侧单击编辑，复制 Trace 日志主题 ID。该 ID 用于后续配置中的 CLS_TOPIC_ID。

六、步骤2：安装 SDK

在 OpenAI Agents SDK 项目的 Python 虚拟环境中执行以下命令：

macOS / LinuxWindows（PowerShell）pip install tencentcloud-agentobs-sdk-openai-agentpy -m pip install tencentcloud-agentobs-sdk-openai-agent

七、步骤3：配置环境变量

设置 CLS Endpoint、日志主题 ID、腾讯云访问密钥和 OpenAI API Key。以下示例以广州地域外网为例：

macOS / LinuxWindows（PowerShell）export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.comexport CLS_TOPIC_ID=your-topic-idexport CLS_SECRET_ID=your-secret-idexport CLS_SECRET_KEY=your-secret-keyexport OPENAI_API_KEY=sk-xxx$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"$env:CLS_TOPIC_ID = "your-topic-id"$env:CLS_SECRET_ID = "your-secret-id"$env:CLS_SECRET_KEY = "your-secret-key"$env:OPENAI_API_KEY = "sk-xxx"

注意：说明：

注意：访问凭证属于敏感信息。建议通过环境变量注入，并使用最小权限和可轮换的临时凭证。

八、步骤4：初始化采集

在首次调用 Runner.run() 或 Runner.run_sync() 前执行 setup()。原有 Agent 代码无需修改。

import osfrom tencentcloud_agentobs_sdk_openai_agent import CLSConfig, setupsetup( CLSConfig( endpoint=os.environ["CLS_ENDPOINT"], topic_id=os.environ["CLS_TOPIC_ID"], secret_id=os.environ["CLS_SECRET_ID"], secret_key=os.environ["CLS_SECRET_KEY"], ))# 以下为原有 OpenAI Agents SDK 代码。from agents import Agent, Runneragent = Agent( name="assistant", instructions="You are a helpful assistant.", model="gpt-4o",)result = Runner.run_sync(agent, "北京天气怎么样？")print(result.final_output)

如果已通过环境变量配置 CLS 参数，可以直接执行：

from tencentcloud_agentobs_sdk_openai_agent import setupsetup()

注意：setup() 必须在首次运行 Agent 前调用。建议在应用启动入口中调用一次，避免重复注册处理器并产生重复 Trace。

九、步骤5：运行 Agent 并验证结果

1. 运行一次包含模型调用的 Agent 任务。建议同时触发一个工具调用，以便检查完整调用树。

2. 进入 日志服务控制台 > Agent 可观测 页面。

3. 进入 步骤1 创建的应用。

4. 打开调用链页面，选择包含测试请求的时间范围。

5. 打开最新 Trace，检查是否包含 Agent、Step、Chat、Tool 或 Embedding 等 Span。

6. 选择具体 Span，检查其耗时、状态、输入输出、Token 用量和模型请求参数等数据。

十、CLS 中没有 Trace 数据

请按以下顺序检查：

1. 确认已在首次调用 Runner.run() 或 Runner.run_sync() 前执行 setup()。

2. 确认 CLS_ENDPOINT 与 Trace 日志主题位于同一地域。

3. 确认 CLS_TOPIC_ID 为日志主题 ID，而不是 Agent 可观测应用 ID。

4. 确认访问密钥具备目标日志主题的写入权限。

5. 确认运行环境能够访问所配置的 CLS Endpoint。

6. 完成测试任务后，等待至少一个刷新周期再查询数据。

7. 开启本地落盘后，检查 JSONL 文件中是否已生成 Span，以区分采集问题和上报问题。

十一、Trace 中没有消息或工具内容

检查内容采集策略是否设置为 off，以及环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 是否关闭了消息内容采集。关闭内容采集不会影响调用树、Token、耗时和状态等数据的上报。

十二、同一次运行出现重复 Trace

检查应用是否重复调用 setup()，或是否通过多个采集组件将同一份数据发送到相同日志主题。除对照验证外，建议同一进程只初始化一次本 SDK。

十三、子 Agent 没有显示在调用树中

确认子 Agent 通过 OpenAI Agents SDK 的标准调用方式执行，并检查子 Agent 是否在 Runner 对应的 Trace 生命周期内运行。SDK 会根据 span.parent_id 还原父子关系。

十四、Agent 运行是否会受上报异常影响

SDK 的观测链路不会中断 Agent 业务。配置缺失或初始化异常时，SDK 会降级输出诊断信息；网络或服务端异常时，SDK 会缓冲并重试上报。

十五、相关文档

·选择接入方式

·Agent 可观测应用详情

·Agent Trace 字段定义说明