帮你快速理解、总结文档立即下载
文档中心>日志服务>Agent 可观测>接入指南>接入 Agent 框架和自研应用>接入 OpenAI Agent SDK 数据

接入 OpenAI Agent SDK 数据

最近更新时间：2026-09-07 18:32:02
我的收藏

本页目录：

操作场景

OpenAI Agent SDK 是用于构建 Agent 应用的 Python 框架。Agent 在运行时可能产生多轮模型推理、工具调用和子 Agent 调用。您可以安装腾讯云 Agent 可观测 SDK tencentcloud-agentobs-sdk-openai-agent，自动采集 OpenAI Agent SDK 的 Trace 数据并上报到日志服务（Cloud Log Service，CLS）。
完成接入后，您可以在腾讯云 Agent 可观测中查看以下信息：
单次 Runner.run() 或 Runner.run_sync() 的完整调用链路，以及 Agent、推理轮次、模型调用和工具调用之间的父子关系。
模型调用的输入 Token、输出 Token、首 Token 延迟（TTFT）、结束原因、输入消息和输出消息。
工具名称、调用参数、返回结果、错误类型和错误信息。
子 Agent 的嵌套关系，以及各层 Agent 的模型调用次数、工具调用次数和 Token 用量。
同一会话下多轮请求的关联关系。
本文提供以下两种接入方式，您可根据实际情况选择：
接入方式
说明
推荐场景
使用支持 Skill 的 AI 工具，由 AI 创建或复用日志主题，并完成 SDK 安装、配置和验证。
希望减少手动配置，并在接入后通过自然语言分析 Trace 数据。
安装 SDK，配置 CLS Endpoint、日志主题和访问凭证，并在代码中调用 setup()。
需要精细控制接入参数，或所用工具不支持 Skill。

前提条件

接入前，请确认已完成以下准备工作：
已开通 日志服务 CLS。
已准备具备 CLS 写入权限的访问凭证，例如 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息请前往 API 密钥管理 获取。
已获取接入所需的地域接入点（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 / Linux
Windows（PowerShell）
pip install tencentcloud-agentobs-sdk-openai-agent
py -m pip install tencentcloud-agentobs-sdk-openai-agent

步骤3：配置环境变量

设置 CLS Endpoint、日志主题 ID、腾讯云访问密钥和 OpenAI API Key。以下示例以广州地域内网为例：
macOS / Linux
Windows（PowerShell）
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=your-topic-id
export CLS_SECRET_ID=your-secret-id
export CLS_SECRET_KEY=your-secret-key
export 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"
环境变量
是否必填
说明
CLS_ENDPOINT
是
CLS 地域 Endpoint。Endpoint 与 Trace 日志主题必须位于同一地域。请参见 地域和访问域名，以广州地域为例，内网域名为 ap-guangzhou.cls.tencentyun.com，外网域名为 ap-guangzhou.cls.tencentcs.com。
CLS_TOPIC_ID
是
Agent 可观测应用对应的 Trace 日志主题 ID。请勿填写应用 ID。
CLS_SECRET_ID
是
腾讯云访问密钥 ID。访问密钥需要具备目标日志主题的写入权限。
CLS_SECRET_KEY
是
腾讯云访问密钥 Key。
OPENAI_API_KEY
是
OpenAI 模型服务的 API Key。
说明：
访问凭证属于敏感信息。建议通过环境变量注入，并使用最小权限和可轮换的临时凭证。

步骤4：初始化采集

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

from tencentcloud_agentobs_sdk_openai_agent import CLSConfig, setup

setup(
    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, Runner

agent = 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 setup

setup()
注意：
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 会缓冲并重试上报。
中国站