操作场景
AgentScope Agent 在执行任务时，会产生多轮推理、模型调用、工具调用和 Embedding 调用等运行数据。您可以安装腾讯云 AgentScope Agent 可观测 SDK
tencentcloud-agentobs-sdk-agentscope，通过一行 init() 初始化代码自动完成插桩，并将 Trace 数据上报到日志服务（Cloud Log Service，CLS）。完成接入后，您可以在腾讯云 Agent 可观测中查看以下信息：
Agent、推理步骤、模型、工具和 Embedding 调用之间的完整执行关系。
各步骤的执行耗时、模型首字延迟（TTFT）、Token 用量和结束原因。
模型请求参数、输入输出消息、工具定义、工具参数和工具结果。
工具调用失败后的重试过程，以及权限门禁、上下文压缩和人工介入等关键生命周期事件。
同一 Session、Turn 和 Step 下的 Trace 关联关系。
本文提供以下两种接入方式，您可根据实际情况选择：
接入方式 | 说明 | 推荐场景 |
使用支持 Skill 的 AI 工具，由 AI 创建或复用日志主题，并完成 SDK 安装、配置和验证。 | 希望减少手动配置，并在接入后通过自然语言分析 Trace 数据。 | |
安装 SDK，配置 CLS Endpoint、日志主题和访问凭证，并在代码中调用 init()。 | 需要精细控制接入参数，或所用工具不支持 Skill。 |
前提条件
开始接入前，请确保已完成以下准备工作：
已开通 日志服务 CLS。
已准备具备 CLS 写入权限的访问凭证，例如 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息请前往 API 密钥管理 获取。
已获取接入所需的地域接入点（endpoint）：即 Agent 应用所在地域的 CLS 接入点域名，请参见 地域和访问域名。以广州地域为例，方式一中对应填写
Region（如 ap-guangzhou）；方式二中对应填写域名，内网域名为 ap-guangzhou.cls.tencentyun.com，外网域名为 ap-guangzhou.cls.tencentcs.com。已安装 AgentScope，并确保应用可以正常运行。
已安装 Python 3.10或更高版本，并为应用创建独立的 Python 虚拟环境。
方式一：通过 Skill 快速接入与分析
如果您使用支持 Skill 的 AI 工具，可使用 腾讯云 Agent 可观测助手 自动完成接入与分析。该 Skill 可创建或复用日志主题，识别 AgentScope 项目并完成 SDK 安装、配置和验证。
在 AI 工具中输入以下内容：
请使用腾讯云 Agent 可观测助手 Skill：https://skillhub.cn/skills/tencentcloud-cls-agent-obs帮我把当前基于 AgentScope 开发的 Agent 接入腾讯云 Agent 可观测。
接入完成后，您还可以直接描述分析需求。例如：
分析这个 Agent 最近 1 小时的运行情况，定位耗时最高、Token 消耗最多和失败最多的模型或工具调用。
方式二：手动配置接入
如果您需要精细控制 SDK、日志主题或访问凭证等参数，或者所用工具不支持 Skill，请按以下步骤手动完成接入。
步骤1：创建 Agent 可观测应用
1. 进入 日志服务控制台 > Agent 可观测 页面。
2. 单击应用接入，根据页面提示创建应用。
3. 在新创建的应用右侧单击编辑，复制 Trace 日志主题 ID。该 ID 用于后续配置中的
CLS_TOPIC_ID。步骤2：安装 SDK
进入 AgentScope 应用所在的 Python 虚拟环境，执行以下命令：
pip install tencentcloud-agentobs-sdk-agentscope
py -m pip install tencentcloud-agentobs-sdk-agentscope
步骤3：在本地验证插桩
在创建任何 Agent 前导入并初始化 SDK：
from tencentcloud_agentobs_sdk_agentscope import initinit()# 以下为原有 AgentScope 业务代码，无需修改。agent = Agent(name="assistant",system_prompt="...",model=model,toolkit=toolkit,)reply = await agent.reply(UserMsg(name="user", content="北京天气怎么样？"),)
未配置 CLS 访问凭证时，SDK 会将 Span 打印到标准输出，不会中断 Agent 运行。请运行一次 Agent 请求，确认标准输出中出现 Agent、Step、Chat 或 Tool 等 Span。
说明：
init() 会自动检测 AgentScope 版本，并对初始化之后创建的 Agent 进行插桩。AgentScope v1 和 v2 使用相同的
init() 接入方式。请在创建 Agent、模型和工具前调用
init()，否则已创建的对象可能无法被自动插桩。步骤4：配置 CLS 连接信息
配置 CLS Endpoint、Trace 日志主题 ID 和腾讯云访问凭证：
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.comexport CLS_TOPIC_ID=<Trace日志主题ID>export CLS_SECRET_ID=<SecretId>export CLS_SECRET_KEY=<SecretKey>
$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"$env:CLS_TOPIC_ID = "<Trace日志主题ID>"$env:CLS_SECRET_ID = "<SecretId>"$env:CLS_SECRET_KEY = "<SecretKey>"
说明：
访问凭证属于敏感信息。建议通过环境变量注入，并使用最小权限和可轮换的临时凭证。
步骤5：验证 CLS 连通性
执行以下命令，检查配置并发送测试 Span：
python -m tencentcloud_agentobs_sdk_agentscope.cls_config verify
py -m tencentcloud_agentobs_sdk_agentscope.cls_config verify
命令会依次检查配置、初始化 CLS SDK、构造测试 Span 并发送数据。以广州为例，出现以下结果表示验证通过：
配置检查通过CLS SDK 初始化成功测试 Span 已构造发送成功验证通过！Span 已上报到 ap-guangzhou.cls.tencentcs.com
步骤6：运行 Agent 并验证结果
按原方式启动 AgentScope 应用，并发起一次包含模型或工具调用的测试请求。完成请求后，等待一个刷新周期，再按以下步骤验证：
1. 进入 日志服务控制台 > Agent 可观测 页面。
2. 进入 步骤1 创建的应用。
3. 打开调用链页面，选择包含测试请求的时间范围。
4. 打开最新 Trace，检查是否包含 Agent、Step、Chat、Tool 或 Embedding 等 Span。
5. 选择具体 Span，检查其耗时、状态、输入输出、Token 用量和模型请求参数等数据。
常见问题
本地没有输出 Span
请按以下顺序检查：
1. 确认已安装
tencentcloud-agentobs-sdk-agentscope。2. 确认
init() 在任何 Agent 创建前执行。3. 确认测试请求实际触发了 Agent、模型或工具调用。
4. 确认应用使用受 SDK 支持的 AgentScope 版本。
连通性验证失败
请按以下顺序检查：
1. 确认
CLS_ENDPOINT 不包含协议前缀或路径。2. 确认
CLS_ENDPOINT 与 Trace 日志主题位于同一地域。3. 确认
CLS_TOPIC_ID 为日志主题 ID，而不是主题名称或应用 ID。4. 确认
CLS_SECRET_ID 和 CLS_SECRET_KEY 有效。5. 确认访问凭证具备向目标日志主题写入数据的权限。
6. 确认当前环境能够访问所配置的 CLS Endpoint。
Trace 中缺少 Token 或部分模型属性
Token 和模型属性来自模型客户端返回结果。模型服务未返回对应字段时，Agent 可观测无法推算准确值。请先确认所使用的模型客户端是否提供 Usage、响应 ID、结束原因和 TTFT 等信息。
Trace 中缺少输入输出或工具参数
请检查应用或 SDK 是否关闭了内容采集。关闭内容采集不会影响调用树、耗时、状态和 Token 用量的上报。
同一个请求出现重复 Trace
请检查应用是否同时启用了腾讯云 AgentScope SDK、AgentScope 官方 Tracing 或其他 OpenTelemetry 自动插桩，并将数据发送到同一日志主题。除对照验证外，建议同一个 Agent 实例只保留一条 Trace 上报路径。
SDK 异常是否会影响 Agent 运行
不会。SDK 遵循观测组件不阻断业务的设计原则，配置缺失或 SDK 异常时会降级，并输出告警和修复指引。
