tencent cloud

Cloud Log Service

DocumentationCloud Log ServiceAgent ObservabilityIntegration GuideIntegrating the Agent Framework with Self-Developed ApplicationsIntegrating OpenAI Agent Data

Integrating OpenAI Agent Data

Download
Focus Mode
Font Size
Last updated: 2026-09-11 18:28:16
AI-Translated

Scenarios

OpenAI Agent SDK is a Python framework for building Agent applications. At runtime, an Agent may generate multiple rounds of model inference, tool calls, and sub-Agent calls. You can install the Tencent Cloud Agent Observability SDK tencentcloud-agentobs-sdk-openai-agent to automatically collect Trace data from OpenAI Agents and report it to CLS (Cloud Log Service).
After completing the integration, you can view the following information in Tencent Cloud Agent Observability:
The complete call chain of a single Runner.run() or Runner.run_sync() invocation, as well as the parent-child relationships among Agents, inference turns, model calls, and tool calls.
The input tokens, output tokens, time to first Token (TTFT), finish reason, input messages, and output messages of a model call.
The tool name, call parameters, return result, error type, and error message.
The nesting relationships of sub-Agents, as well as the number of model calls, tool calls, and Token usage of Agents at each level.
The correlation between multiple rounds of requests within the same session.
This document provides the following two integration methods. You can choose one based on your actual needs:
Access Method
Description
Recommended Scenario
Use an AI tool that supports Skill to have AI create or reuse a log topic and complete SDK installation, configuration, and verification.
Prefer to minimize manual configuration and analyze Trace data through natural language after access.
Install the SDK, configure the CLS Endpoint, log topic, and access credentials, and call setup() in the code.
Requires fine-grained control over access parameters, or the tool in use does not support Skill.

Prerequisites

Before integration, make sure you have completed the following preparations:
CLS has been activated.
Prepare an access credential with CLS write permission, 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 required region endpoint, which is the CLS endpoint domain name in the region where the Agent application resides. For details, see Regions and Access Domain Names. For example, in the Guangzhou region, enter the Region (such as ap-guangzhou) for method 1. For method 2, enter the domain name. The private network domain name is ap-guangzhou.cls.tencentyun.com, and the public network domain name is ap-guangzhou.cls.tencentcs.com.

Method 1: Quickly Integrating and Analyzing via Skill

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 OpenAI Agent 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 current OpenAI Agent into Tencent Cloud Agent Observability.
After integration is complete, you can also directly describe your analysis requirements. For example:
Analyze the running status of this Agent over the last hour, and 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 your tool does not support Skills, complete the integration manually by following the steps below.

Step 1: Creating an Observable Application for Agent

1. Go to the CLS console > Agent Observability page.
2. Click Application Integration and create an application by following the on-page 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 subsequent configurations.

Step 2: Installing the SDK

Run the following command in the Python virtual environment of your OpenAI Agents SDK project:
macOS / Linux
Windows(PowerShell)
pip install tencentcloud-agentobs-sdk-openai-agent
py -m pip install tencentcloud-agentobs-sdk-openai-agent

Step 3: Configuring Environment Variables

Set the CLS Endpoint, log topic ID, Tencent Cloud access credentials, and OpenAI API Key. The following example uses the private network in the Guangzhou region:
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"
Environment Variable
Required
Description
CLS_ENDPOINT
Yes
CLS region Endpoint. The Endpoint and the Trace log topic must be in the same region. See Regions and Access Domain Names. For example, in the Guangzhou region, 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 corresponding to the Agent observable application. Do not enter the application ID.
CLS_SECRET_ID
Yes
Tencent Cloud access key ID. The access key must have write permission on the target log topic.
CLS_SECRET_KEY
Yes
Tencent Cloud access Key.
OPENAI_API_KEY
Yes
API Key for the OpenAI model service.
Note:
Access credentials are sensitive information. It is recommended to inject them through environment variables and use temporary credentials with least privilege and rotation enabled.

Step 4: Initializing Collection

Call setup() before the first invocation of Runner.run() or Runner.run_sync(). No changes are required to your existing Agent code.
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"],
    )
)

# The following is the existing OpenAI Agents SDK code.
from agents import Agent, Runner

agent = Agent(
    name="assistant",
    instructions="You are a helpful assistant.",
    model="gpt-4o",
)

result = Runner.run_sync(agent, "What's the weather like in Beijing?")
print(result.final_output)
If CLS parameters have been configured through environment variables, you can run the following directly:
from tencentcloud_agentobs_sdk_openai_agent import setup

setup()
Note:
setup() must be called before the Agent is run for the first time. It is recommended to call it once at the application entry point to avoid duplicate handler registration and duplicate traces.

Step 5: Running the Agent and Verifying Results

1. Run an Agent task that includes a model call. It is recommended to also trigger a tool call so that you can inspect the complete call tree.
2. Go to the CLS console > Agent Observability page.
3. Go to the application created in Step 1.
4. Open the Trace page and select a time range that includes the test request.
5. Open the latest Trace and check whether it contains spans such as Agent, Step, Chat, Tool, or Embedding.
6. Select a specific Span and inspect its data, including duration, status, input and output, Token usage, and model request parameters.

FAQs

No Trace Data in CLS

Check the following in order:
1. Make sure that setup() has been called before the first invocation of Runner.run() or Runner.run_sync().
2. Make sure that CLS_ENDPOINT is in the same region as the Trace log topic.
3. Make sure that CLS_TOPIC_ID is the log topic ID, not the Agent Observability application ID.
4. Make sure that the access key has write permission on the target log topic.
5. Make sure that the runtime environment can access the configured CLS Endpoint.
6. After completing the test task, wait for at least one refresh cycle before querying the data.
7. After enabling local disk storage, check whether spans have been generated in the JSONL file to distinguish between collection issues and reporting issues.

No Message or Tool Content in Trace

Check whether the content collection policy is set to off and whether the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT environment variable has disabled message content collection. Disabling content collection does not affect the reporting of data such as call trees, tokens, duration, and status.

Duplicate Traces in a Single Run

Check whether the application calls setup() repeatedly, or whether the same data is sent to the same log topic through multiple collection components. Except for comparison verification, it is recommended to initialize this SDK only once in the same process.

Sub-Agent Not Displayed in the Call Tree

Make sure that sub-Agents are executed through the standard invocation method of OpenAI Agents SDK, and check whether sub-Agents run within the Trace lifecycle corresponding to Runner. The SDK restores the parent-child relationship based on span.parent_id.

Will Agent Runs Be Affected by Reporting Exceptions?

The SDK's observability pipeline does not interrupt Agent business. When configuration is missing or initialization fails, the SDK degrades to output diagnostic information. When a network or server exception occurs, the SDK buffers and retries reporting.
Previous Topic: Onesuite-Pilot Release NotesNext Topic: Integrating AgentScope Data

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation