日志服务接入 AgentScope 数据

操作场景
AgentScope Agent 在执行任务时，会产生多轮推理、模型调用、工具调用和 Embedding 调用等运行数据。腾讯云提供 Python 和 Java 两种 AgentScope Agent 可观测 SDK，可自动完成插桩，并将 Trace 数据上报。产品能力介绍请参见 Agent 可观测产品页，如需对比其他接入方式，请参见选择接入方式。
SDK
适用框架
接入方式
Python SDK tencentcloud-agentobs-sdk-agentscope
AgentScope（Python）v1、v2
调用一行 init() 自动插桩
Java SDK tencentcloud-agentobs-sdk-agentscope-java
AgentScope Java 2.x
调用 ClsObservability.install()，并为 Agent 挂载 Tracing 中间件
完成接入后，您可以在腾讯云 Agent 可观测中查看以下信息：
Agent、推理步骤、模型、工具和 Embedding 调用之间的完整执行关系。
各步骤的执行耗时、模型首字延迟（TTFT）、Token 用量和结束原因。
模型请求参数、输入输出消息、工具定义、工具参数和工具结果。
工具调用失败后的重试过程，以及权限门禁、上下文压缩和人工介入等关键生命周期事件。
同一 Session、Turn 和 Step 下的 Trace 关联关系。
本文提供以下两种接入方式，您可根据实际情况选择：
接入方式
说明
推荐场景
﻿方式一：通过 Skill 快速接入与分析﻿
使用支持 Skill 的 AI 工具，由 AI 创建或复用日志主题，并完成 SDK 安装、配置和验证。
希望减少手动配置，并在接入后通过自然语言分析 Trace 数据。
﻿方式二：手动配置接入﻿
安装 SDK，配置 Endpoint、日志主题和访问凭证，并在代码中完成初始化（Python 调用 init()，Java 调用 ClsObservability.install()）。
需要精细控制接入参数，或所用工具不支持 Skill。
前提条件
开始接入前，请确保已完成以下准备工作：
已开通 日志服务 CLS。
已准备具备 CLS 写入权限的访问凭证，例如 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息请前往 API 密钥管理 获取，密钥需对目标主题有写入权限，权限模板参见 采集 Agent 可观测数据。
已获取接入所需的地域接入点（endpoint）：即 Agent 应用所在地域的 CLS 接入点域名，请参见 地域和访问域名。以广州地域为例，方式一中对应填写 Region（如 ap-guangzhou）；方式二中对应填写域名，内网域名为 ap-guangzhou.cls.tencentyun.com，外网域名为 ap-guangzhou.cls.tencentcs.com。
已安装 AgentScope，并确保应用可以正常运行。
已准备对应语言的运行环境：
Python：已安装 Python 3.10或更高版本，并为应用创建独立的 Python 虚拟环境。
Java：已安装 JDK 17或更高版本，使用 Maven 或 Gradle 构建项目，且项目已引入 AgentScope Java 2.x（io.agentscope:agentscope-core）。
方式一：通过 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
根据应用的开发语言安装 SDK：Python 应用请进入 AgentScope 应用所在的 Python 虚拟环境执行安装命令；Java 应用请在项目构建文件中添加 SDK 依赖。
Python（macOS / Linux）
Python（Windows PowerShell）
Java（Maven）
Java（Gradle）
pip install tencentcloud-agentobs-sdk-agentscope
py -m pip install tencentcloud-agentobs-sdk-agentscope
在 pom.xml 中添加以下依赖：
<dependency>
    <groupId>com.tencentcloudapi.observability</groupId>
    <artifactId>tencentcloud-agentobs-sdk-agentscope-java</artifactId>
    <version>0.0.4</version>
</dependency>
在 build.gradle 中添加以下依赖：
dependencies {
    implementation 'com.tencentcloudapi.observability:tencentcloud-agentobs-sdk-agentscope-java:0.0.4'
}
说明：
Java SDK 已发布到 Maven Central，最新版本请参见 GitHub 仓库。
Java SDK 不会传递引入 AgentScope（agentscope-core）和 reactor-core，这两个依赖由应用自身提供。
Java SDK 已内置并隔离 OpenTelemetry 运行时，不会与应用中已有的 OpenTelemetry 依赖或 OpenTelemetry Java Agent（-javaagent）产生冲突。
步骤3：初始化 SDK
在创建任何 Agent 前导入并初始化 SDK：
Python
Java
from tencentcloud_agentobs_sdk_agentscope import init
﻿
init()
﻿
# 以下为原有 AgentScope 业务代码，无需修改。
agent = Agent(
    name="assistant",
    system_prompt="...",
    model=model,
    toolkit=toolkit,
)
reply = await agent.reply(
    UserMsg(name="user", content="北京天气怎么样？"),
)
未配置访问凭证时，SDK 会将 Span 打印到标准输出，不会中断 Agent 运行。请运行一次 Agent 请求，确认标准输出中出现 Agent、Step、Chat 或 Tool 等 Span。
说明：
init() 会自动检测 AgentScope 版本，并对初始化之后创建的 Agent 进行插桩。
AgentScope v1和 v2使用相同的 init() 接入方式。
请在创建 Agent、模型和工具前调用 init()，否则已创建的对象可能无法被自动插桩。
在应用启动时调用一次 ClsObservability.install()，并在构建 ReActAgent 时挂载 CLS Tracing 中间件，其他业务代码无需修改：
import com.tencentcloudapi.observability.agentscope.ClsObservability;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.Msg;
import io.agentscope.core.middleware.MiddlewareBase;
﻿
// 应用启动时初始化一次，从环境变量或 .env 文件读取 CLS 配置
ClsObservability obs = ClsObservability.install();
﻿
// 构建 Agent 时挂载 CLS Tracing 中间件
ReActAgent agent = ReActAgent.builder()
        .name("assistant")
        .sysPrompt("You are a helpful assistant.")
        .model(model)
        .toolkit(toolkit)
        .middleware((MiddlewareBase) obs.newTracingMiddleware())
        .build();
﻿
// 可选：传入会话 ID 和用户 ID，用于跨轮次关联 Trace
RuntimeContext ctx = RuntimeContext.builder()
        .sessionId("session-1234")
        .userId("user-5678")
        .build();
﻿
Msg reply = agent.call("北京天气怎么样？", ctx).block();
如需在代码中显式指定参数，请参见 步骤4 中的 ClsConfig.builder() 配置方式。
说明：
Java SDK 需要完成 步骤4 的配置后才能运行。必填参数缺失时，install() 会抛出 IllegalStateException 并列出缺失的参数。
中间件为无状态设计，同一个实例可在并发请求和人工介入（HITL）挂起/恢复场景下安全复用。
RuntimeContext 中的 sessionId 和 userId 会分别写入 gen_ai.session.id 和 gen_ai.user.id 字段。
步骤4：配置连接信息
配置 Endpoint、Trace 日志主题 ID 和腾讯云访问凭证，参数说明如下：
参数
是否必填
说明
CLS_ENDPOINT
是
CLS API 接入点，请参见 地域和访问域名，以广州为例，内网域名为 ap-guangzhou.cls.tencentyun.com，外网域名为 ap-guangzhou.cls.tencentcs.com。
CLS_TOPIC_ID
是
﻿步骤1中获取的 Trace 日志主题 ID。
CLS_SECRET_ID
是
腾讯云访问凭证 SecretId，请前往 API 密钥管理 获取。
CLS_SECRET_KEY
是
腾讯云访问凭证 SecretKey，请前往 API 密钥管理 获取。
使用访问密钥（SecretId / SecretKey）上报时，密钥需对目标主题有写入权限，权限模板参见 采集 Agent 可观测数据。
说明：
访问凭证属于敏感信息。建议通过环境变量注入，并使用最小权限和可轮换的临时凭证。
SDK 支持以下配置方式，请根据 SDK 语言和运行场景选择：
配置方式
支持的 SDK
适用场景
环境变量
Python、Java
通用方式。适用于命令行启动、容器部署等场景。
.env 文件
Java
在 IDE 中调试，或不便设置系统环境变量的场景。
ClsConfig.builder()
Java
需要在代码中显式指定参数，或从自有配置中心读取配置的场景。
Java SDK 同时使用多种方式时，优先级为：ClsConfig.builder() 显式设置的值 > 环境变量 > .env 文件。未显式设置的参数，会按优先级从其他方式中读取。
方式1：环境变量
方式2：.env 文件（Java）
方式3：ClsConfig.builder()（Java）
macOS / Linux：
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<Trace日志主题ID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
Windows（PowerShell）：
$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"
$env:CLS_TOPIC_ID = "<Trace日志主题ID>"
$env:CLS_SECRET_ID = "<SecretId>"
$env:CLS_SECRET_KEY = "<SecretKey>"
说明：
以上命令仅对当前终端生效。Java SDK 读取的是 Java 进程自身的环境变量，请在执行上述命令的同一终端中启动应用（如 mvn exec:java 或 java -jar）。
在 IntelliJ IDEA 等 IDE 中运行时，需在运行配置（Run Configuration）的 Environment variables 中设置，或改用 .env 文件方式。
容器部署时，建议通过 Kubernetes Secret 以环境变量方式注入。
在应用的工作目录下创建 .env 文件（或创建 ~/.agentobs-agentscope/config.env），写入以下内容：
CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
CLS_TOPIC_ID=<Trace日志主题ID>
CLS_SECRET_ID=<SecretId>
CLS_SECRET_KEY=<SecretKey>
注意：
文件中每行使用 KEY=value 格式，不要添加 export 前缀，否则无法识别。以 # 开头的行视为注释。
SDK 优先读取工作目录下的 ./.env；该文件不存在时，才读取 ~/.agentobs-agentscope/config.env。两个文件不会合并。
已设置的环境变量优先于 .env 文件中的同名配置。
请将 .env 加入 .gitignore，避免密钥提交到代码仓库。
在代码中通过 ClsConfig.builder() 构建配置，并传入 ClsObservability.install()。显式设置的值优先，未设置的字段仍从环境变量或 .env 文件读取：
import com.tencentcloudapi.observability.agentscope.ClsConfig;
﻿
ClsConfig config = ClsConfig.builder()
        .endpoint("ap-guangzhou.cls.tencentcs.com")
        .topicId("<Trace日志主题ID>")
        .secretId(System.getenv("CLS_SECRET_ID"))   // 请勿在代码中硬编码密钥
        .secretKey(System.getenv("CLS_SECRET_KEY"))
        .serviceName("my-agent-app")                // 可选
        .build();
ClsObservability obs = ClsObservability.install(config);
Java SDK 还支持以下可选参数，可通过环境变量、.env 文件或 Builder 方法设置：
环境变量
Builder 方法
默认值
说明
CLS_SERVICE_NAME
.serviceName(String)
agentscope-app
服务或应用名称。
CLS_SOURCE
.source(String)
本机 IP
Span 的来源标识，自动探测失败时使用127.0.0.1。
CLS_BATCH_SIZE
.batchSize(Integer)
32
每批上报的 Span 数量上限，取值范围为1 - 1000。
CLS_DEBUG
.debug(Boolean)
false
是否输出详细日志。环境变量取值为1、true 或 yes 时开启。
步骤5：验证连通性
Python SDK 可执行以下命令，检查配置并发送测试 Span。Java SDK 暂不提供连通性验证命令，可设置 CLS_DEBUG=true 后直接执行步骤6，通过 SDK 日志确认上报结果。
macOS / Linux
Windows (PowerShell)
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 用量和模型请求参数等数据。
说明：
Java SDK 采用批量异步上报，并在 JVM 退出时通过关闭钩子自动上报剩余数据。对于运行后立即退出的短任务或测试程序，建议在退出前调用 obs.flush() 立即上报，再调用 obs.shutdown() 关闭 SDK。
常见问题
本地没有输出 Span
请按以下顺序检查：
1. 确认已安装 SDK：Python 应用已安装 tencentcloud-agentobs-sdk-agentscope，Java 应用已添加 tencentcloud-agentobs-sdk-agentscope-java 依赖。
2. Python 应用确认 init() 在任何 Agent 创建前执行；Java 应用确认已调用 ClsObservability.install()，并在构建 ReActAgent 时通过 .middleware() 挂载了 obs.newTracingMiddleware()。
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 异常时会降级，并输出告警和修复指引。
Java SDK 在初始化阶段校验必填参数：缺少 CLS_ENDPOINT、CLS_TOPIC_ID、CLS_SECRET_ID 或 CLS_SECRET_KEY 时，ClsObservability.install() 会抛出 IllegalStateException 并列出缺失的参数，建议在应用启动阶段完成配置检查。
Java 应用使用 OpenTelemetry Java Agent 时调用树断裂
如果应用通过 -javaagent 方式加载了 OpenTelemetry Java Agent 或其他 APM 探针，使用 Java SDK 0.0.3及更早版本时，探针可能接管 SDK 的 Tracer，导致 CLS 中的 Span 失去父子关系，每个 Span 都成为独立的 Trace。请将 SDK 升级到0.0.4及以上版本，并删除之前为规避该问题添加的启动参数 -Dotel.instrumentation.opentelemetry-api.enabled=false。0.0.4及以上版本已内置并隔离 OpenTelemetry 运行时，可以与探针以及 AgentScope 自带的 OtelTracingMiddleware 同时使用，互不影响。
﻿

SDK	适用框架	接入方式
Python SDK `tencentcloud-agentobs-sdk-agentscope`	AgentScope（Python）v1、v2	调用一行 `init()` 自动插桩
Java SDK `tencentcloud-agentobs-sdk-agentscope-java`	AgentScope Java 2.x	调用 `ClsObservability.install()`，并为 Agent 挂载 Tracing 中间件

接入方式	说明	推荐场景
方式一：通过 Skill 快速接入与分析	使用支持 Skill 的 AI 工具，由 AI 创建或复用日志主题，并完成 SDK 安装、配置和验证。	希望减少手动配置，并在接入后通过自然语言分析 Trace 数据。
方式二：手动配置接入	安装 SDK，配置 Endpoint、日志主题和访问凭证，并在代码中完成初始化（Python 调用 `init()`，Java 调用 `ClsObservability.install()`）。	需要精细控制接入参数，或所用工具不支持 Skill。

参数	是否必填	说明
`CLS_ENDPOINT`	是	CLS API 接入点，请参见地域和访问域名，以广州为例，内网域名为 `ap-guangzhou.cls.tencentyun.com`，外网域名为 `ap-guangzhou.cls.tencentcs.com`。
`CLS_TOPIC_ID`	是	步骤1中获取的 Trace 日志主题 ID。
`CLS_SECRET_ID`	是	腾讯云访问凭证 SecretId，请前往 API 密钥管理获取。
`CLS_SECRET_KEY`	是	腾讯云访问凭证 SecretKey，请前往 API 密钥管理获取。

配置方式	支持的 SDK	适用场景
环境变量	Python、Java	通用方式。适用于命令行启动、容器部署等场景。
`.env` 文件	Java	在 IDE 中调试，或不便设置系统环境变量的场景。
`ClsConfig.builder()`	Java	需要在代码中显式指定参数，或从自有配置中心读取配置的场景。

环境变量	Builder 方法	默认值	说明
`CLS_SERVICE_NAME`	`.serviceName(String)`	agentscope-app	服务或应用名称。
`CLS_SOURCE`	`.source(String)`	本机 IP	Span 的来源标识，自动探测失败时使用`127.0.0.1`。
`CLS_BATCH_SIZE`	`.batchSize(Integer)`	32	每批上报的 Span 数量上限，取值范围为1 - 1000。
`CLS_DEBUG`	`.debug(Boolean)`	false	是否输出详细日志。环境变量取值为`1`、`true` 或 `yes` 时开启。

接入 AgentScope 数据

本页目录：

操作场景

前提条件

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

方式二：手动配置接入

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

步骤2：安装 SDK

步骤3：初始化 SDK

步骤4：配置连接信息

步骤5：验证连通性

步骤6：运行 Agent 并验证结果

常见问题

本地没有输出 Span

连通性验证失败

Trace 中缺少 Token 或部分模型属性

Trace 中缺少输入输出或工具参数

同一个请求出现重复 Trace

SDK 异常是否会影响 Agent 运行

Java 应用使用 OpenTelemetry Java Agent 时调用树断裂