Scenarios
When executing tasks, AgentScope Agent generates operational data such as multiple rounds of reasoning, model calls, tool calls, and Embedding calls. You can install the Tencent Cloud AgentScope Agent observability SDK tencentcloud-agentobs-sdk-agentscope, complete instrumentation automatically with a single line of init() initialization code, and report Trace data to CLS.
After completing the integration, you can view the following information in Tencent Cloud Agent Observability:
The complete execution relationships among Agents, reasoning steps, models, tools, and Embedding calls.
The execution duration of each step, time to first token (TTFT) of the model, token usage, and completion reason.
Model request parameters, input and output messages, tool definitions, tool parameters, and tool results.
The retry process after tool call failures, as well as key lifecycle events such as permission gating, context compression, and human intervention.
Trace correlation under the same Session, Turn, and Step.
This document provides the following two integration methods. Choose one based on your actual needs:
|
| Use an AI tool that supports Skill to have AI create or reuse log topics, and complete SDK installation, configuration, and verification. | Prefer to minimize manual configuration and analyze Trace data using natural language after integration. |
| Install the SDK, configure the CLS Endpoint, log topic, and access credentials, and call init() in the code. | Require fine-grained control over access parameters, or the tool in use does not support Skill. |
Prerequisites
Before you start, make sure you have completed the following preparations:
You have prepared access credentials with CLS write permissions, such as a CAM sub-account, CAM Role, or temporary key. To obtain TencentCloud API key information, go to API Key Management. You have obtained the region endpoint required for integration, which is the CLS endpoint domain of the region where the Agent application resides. See Regions and Access Domains. For example, in the Guangzhou region, enter the Region (such as ap-guangzhou) in method 1. In method 2, enter the domain name instead. The private network domain is ap-guangzhou.cls.tencentyun.com, and the public network domain is ap-guangzhou.cls.tencentcs.com. AgentScope is installed, and the application is running properly.
Python 3.10 or later is installed, and an isolated Python virtual environment has been created for the application.
Method 1: Quickly Integrating and Analyzing via Skills
If you use an AI tool that supports Skills, you can use the Tencent Cloud Agent Observability Assistant to automatically complete integration and analysis. This Skill can create or reuse log topics, identify AgentScope projects, and complete SDK installation, configuration, and verification. Enter the following content in your AI tool:
Use the Tencent Cloud Agent Observability Assistant Skill:
https://skillhub.cn/skills/tencentcloud-cls-agent-obs
Help me integrate the Agent currently developed based on AgentScope into Tencent Cloud Agent Observability.
After the integration is complete, you can also directly describe your analysis requirements. For example:
Analyze the Agent's performance over the past hour to identify the model or tool calls with the highest latency, the highest Token consumption, and the most failures.
Method 2: Manually Configuring Access
If you need fine-grained control over parameters such as the SDK, log topic, or access credentials, or if the tool you are using does not support Skills, complete the integration manually by following the steps below.
Step 1: Creating an Agent Observability Application
2. Click Application Integration and create an application by following the on-screen instructions.
3. Click Edit on the right side of the newly created application and copy the Trace log topic ID. This ID is used for CLS_TOPIC_ID in the subsequent configuration.
Step 2: Installing the SDK
Enter the Python virtual environment where the AgentScope application resides, and run the following command:
pip install tencentcloud-agentobs-sdk-agentscope
py -m pip install tencentcloud-agentobs-sdk-agentscope
Step 3: Verifying Instrumentation Locally
Import and initialize the SDK before creating any Agent:
from tencentcloud_agentobs_sdk_agentscope import init
init()
agent = Agent(
name="assistant",
system_prompt="...",
model=model,
toolkit=toolkit,
)
reply = await agent.reply(
UserMsg(name="user", content="What's the weather like in Beijing?"),
)
If CLS access credentials are not configured, the SDK prints Spans to standard output without interrupting Agent execution. Run an Agent request once and confirm that Spans such as Agent, Step, Chat, or Tool appear in standard output.
Note:
init() automatically detects the AgentScope version and instruments Agents created after initialization.
AgentScope v1 and v2 use the same init() integration method.
Call init() before creating Agents, models, and tools. Otherwise, created objects may not be automatically instrumented.
Step 4: Configuring CLS Connection Information
Configure the CLS Endpoint, Trace log topic ID, and Tencent Cloud access credentials:
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<Trace log topic ID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
$env:CLS_ENDPOINT = "ap-guangzhou.cls.tencentcs.com"
$env:CLS_TOPIC_ID = "<Trace log topic ID>"
$env:CLS_SECRET_ID = "<SecretId>"
$env:CLS_SECRET_KEY = "<SecretKey>"
|
CLS_ENDPOINT
| Yes | CLS API endpoint. See Regions and Access Domain Names. For example, in Guangzhou, the private network domain name is ap-guangzhou.cls.tencentyun.com, and the public network domain name is ap-guangzhou.cls.tencentcs.com. |
CLS_TOPIC_ID
| Yes | Trace log topic ID obtained in step 1. |
CLS_SECRET_ID
| Yes | |
CLS_SECRET_KEY
| Yes | |
Note:
Access credentials are sensitive information. Inject them through environment variables and use temporary credentials with least privilege and rotation enabled.
Step 5: Verifying CLS Connectivity
Run the following command to check the configuration and send a test Span:
python -m tencentcloud_agentobs_sdk_agentscope.cls_config verify
py -m tencentcloud_agentobs_sdk_agentscope.cls_config verify
The command checks the configuration, initializes the CLS SDK, constructs a test Span, and sends data in sequence. The following result, using Guangzhou as an example, indicates successful verification:
Configuration check passed.
CLS SDK initialized successfully
Test Span constructed.
Sent successfully
Verification passed! The Span has been reported to ap-guangzhou.cls.tencentcs.com
Step 6: Running the Agent and Verifying Results
Start the AgentScope application in the original way and initiate a test request that includes a model or tool call. After completing the request, wait for one refresh cycle, and then verify by following these steps:
2. Go to the application created in Step 1. 3. Open the Trace page and select a time range that includes the test request.
4. Open the latest Trace and check whether it contains spans such as Agent, Step, Chat, Tool, or Embedding.
5. Select a specific Span and check its duration, status, input and output, Token usage, and model request parameters.
FAQs
No Span Output Locally
Check the following in order:
1. Confirm that tencentcloud-agentobs-sdk-agentscope is installed.
2. Confirm that init() is executed before any Agent is created.
3. Confirm that the test request actually triggered an Agent, model, or tool call.
4. Confirm that the application uses an AgentScope version supported by the SDK.
Connectivity Verification Failures
Check the following in order:
1. Confirm that CLS_ENDPOINT does not contain a protocol prefix or path.
2. Make sure that CLS_ENDPOINT and the Trace log topic are in the same region.
3. Confirm that CLS_TOPIC_ID is the log topic ID, not the topic name or application ID.
4. Confirm that CLS_SECRET_ID and CLS_SECRET_KEY are valid.
5. Confirm that the access credential has permission to write data to the target log topic.
6. Confirm that the current environment can access the configured CLS Endpoint.
Missing Token or Some Model Attributes in Traces
Token and model attributes come from the results returned by the model client. When the model service does not return the corresponding fields, Agent Observability cannot calculate accurate values. First, confirm whether the model client in use provides information such as Usage, response ID, finish reason, and TTFT.
Missing Input, Output, or Tool Parameters in Traces
Check whether the application or SDK has disabled content collection. Disabling content collection does not affect the reporting of call trees, latency, status, and Token usage.
Duplicate Traces in a Single Request
Check whether the application has enabled Tencent Cloud AgentScope SDK, AgentScope official Tracing, or other OpenTelemetry automatic instrumentation at the same time and sends data to the same log topic. Except for comparison verification, it is recommended that the same Agent instance retain only one Trace reporting path.
Will SDK Exceptions Affect Agent Operation?
No. The SDK follows the design principle that observability components do not interrupt business operations. When configuration is missing or an SDK exception occurs, the SDK degrades gracefully and outputs alarms and remediation guidance.