tencent cloud

Cloud Log Service

DocumentaçãoCloud Log Service

Integrating AI Coding Agent Data (Onesuite-Pilot)

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-09-04 14:33:46
Traduzido por IA

Scenarios

Onesuite-Pilot is a data collection program that runs as a local resident service. It can automatically detect and connect to AI Coding Agents installed on the machine, collect and process session data generated during AI Coding, and report it to Cloud Log Service (CLS). This helps you search, analyze, and observe AI Coding activities in CLS.
This document describes how to install, configure, verify, and maintain Onesuite-Pilot. Onesuite-Pilot currently supports integration with Codebuddy and WorkBuddy, and support for more AI coding tools will be continuously expanded.
This document provides the following two integration methods. Choose one based on your actual needs:
Access Method
Description
Recommended Scenario
Use an AI tool that supports Skill to have AI automatically create or reuse log topics, identify environments, and complete access and analysis.
Use an AI tool that supports Skill to achieve one-click access and minimize manual configuration.
Execute installation commands step by step, and manually enter parameters such as region endpoint, log topic, and key to complete access.
Require fine-grained control over access parameters, or the tool in use does not support Skill.

Prerequisites

Before installation, make sure the following conditions are met:
CLS has been activated for CLS.
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.
The operating system must be macOS or Linux. For Windows, use the PowerShell installation script.
Node.js version ≥ 18 (the installation script automatically detects node, nvm, and common paths).
You have obtained the region endpoint required for integration, which is the CLS endpoint domain of the region where the Agent application resides. For details, 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 public network domain is ap-guangzhou.cls.tencentyun.com, and the private network domain is ap-guangzhou.cls.tencentcs.com.

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 Integration Assistant to automatically complete integration and analysis. This Skill has integrated integration and analysis capabilities and can automatically create or reuse log topics.
Use the Tencent Cloud Agent Observability Integration Skill:
https://skillhub.cn/skills/tencentcloud-cls-agent-obs

Help me integrate the current AI application into Tencent Cloud Agent Observability.

Integration method: CodeBuddy + WorkBuddy
Region:ap-guangzhou

Method 2: Manually Configuring Access

For manual integration, run the installation commands step by step, and enter the region endpoint, log topic ID, and key information obtained in the prerequisites into the commands.

Step 1: Running the Command

Run the following one-click installation command. Replace the parameter values with the actual information you obtained in the CLS console.
curl -fsSL https://onesuite-pilot-1254077820.cos.ap-shanghai.myqcloud.com/onesuite-pilot/installer.sh | bash -s -- install \\
  --cls-endpoint  "<your-cls-endpoint>" \\
  --cls-topic-id  "<your-topic-id>" \\
  --cls-secret-id "<your-secret-id>" \\
  --cls-secret-key "<your-secret-key>" \\

Installation Parameter Description:

Parameter
Required
Description
--cls-endpoint
Yes
CLS region endpoint domain name. See Regions and Access Domain Names.
For example, in the Guangzhou region, the public network domain name is ap-guangzhou.cls.tencentyun.com, and the private network domain name is ap-guangzhou.cls.tencentcs.com.
--cls-topic-id
Yes
Target log topic ID (TopicId).
--cls-secret-id
Yes
Access credential SecretId requires write permission on the target topic. For TencentCloud API key information, go to API key management to obtain it.
--cls-secret-key
Yes
Access credential SecretKey. For TencentCloud API key information, go to API key management to obtain it.
--user-id
No
User identifier for data ownership. It is written to the gen_ai.user.id field of reported data. If not specified, the hostname is used by default. It can also be written as --userId or --user.id.
--user-name
No
User display name, mapped to gen_ai.user.name. It is an independent field from userId.
--agents
No
Specify the list of Agents to access (comma-separated). If not specified, all detected Agents are automatically accessed.
--data-dir
No
Custom data directory, default ~/.onesuite-pilot.
--auto-update
No
Automatic upgrade, recommended to enable.
The installation script will perform the following steps in sequence: dependency check → download the installation package → detect the AI Agent → deploy the program → install the Hook script → write the configuration → register and start the service. If ✅ Installation complete! appears, the deployment is successful.
Note:
Regarding the priority of the userId value, the effective userId is resolved according to the following priority order:
Environment variable ONESUITE_PILOT_USER_ID → configuration file userId → configuration file user.id → hostname (fallback).

Step 2: Verifying the Installation

After the installation is complete, run the following command to view the service status and configuration information:
onesuite-pilot status   # View the service running status
onesuite-pilot info     # View the version, configuration file path, and complete configuration
Normal output should include ✅ onesuite-pilot v... is running (PID xxxxx) and autostart: enabled.
Note:
If onesuite-pilot: command not found is displayed when you run the command, restart the terminal or run source ~/.bashrc to make the environment variables take effect, and then try again. This message does not affect the running of the OneSuite-Pilot service.

Common Operations

After completing the integration, you can refer to this section to perform Ops operations on Onesuite-Pilot, such as upgrades, configuration changes, routine management, and uninstallation.

Common Commands

Command
Description
onesuite-pilot status
View the service running status, PID, and auto-start status.
onesuite-pilot info
View the version, configuration file path, data directory, and complete configuration.
onesuite-pilot restart
Restart the service. It must be executed after the configuration is modified, and buffer data will be forcibly flushed during the restart.
onesuite-pilot stop / start
Stop/start the service.

Modifying configuration

If the installation is already complete, you do not need to rerun the installation script. Directly edit the configuration file ~/.onesuite-pilot/config.json, and restart the service after making changes for them to take effect. The configuration file is in standard JSON format, with the following core structure:
{
  "enabled": true,
  "dataDir": "/Users/you/.onesuite-pilot",
  "userId": "122855467",
  "userName": "helloworld",
  "flushers": {
    "cls": {
      "endpoint":  "ap-guangzhou.cls.tencentyun.com",
      "topicId":  "<your-topic-id>",
      "secretId": "<your-secret-id>",
      "secretKey": "<your-secret-key>"
    }
  }
}
Make sure to back up the configuration file before making any changes. If a JSON format error occurs or a field is incorrectly modified when config.json is manually edited, the service may fail to start or report exceptions. Keeping a backup allows you to restore the configuration if problems occur.
cp ~/.onesuite-pilot/config.json ~/.onesuite-pilot/config.json.bak
Scenario 1: Adding or Modifying userId/userName
Scenario 2: Switching the CLS Reporting Destination (Region/Topic)
Add the userId and userName fields at the top level of the configuration file (at the same level as dataDir), and then restart the service.
1. Edit config.json and add the following fields:
"userId": "122855467",
"userName": "helloworld",
2. Restart the service for the configuration to take effect:
onesuite-pilot restart
Modify the endpoint (region endpoint) and topicId (target topic) under flushers.cls. The changes take effect after a restart. For example, to switch to a new topic in the ap-guangzhou-open region:
  "flushers": {
    "cls": {
-     "endpoint": "ap-guangzhou.cls.tencentyun.com",
+     "endpoint": "ap-guangzhou-open.cls.tencentyun.com",
-     "topicId":  "9263b751-9b29-4931-aeb9-4405cf69a2ea",
+     "topicId":  "3189f2f4-1f03-4f4a-b4c5-b139d037df61",
      ...
    }
  }
Note:
When switching topics, confirm that the current SecretId/SecretKey has write permission on the new topic. Log write permissions are controlled by CAM (corresponding to the cls:UploadLog operation, which can be scoped to a single log topic). For configuration methods, see CLS Permission Management and CLS Access Policy Templates. If the new topic belongs to a different account, update the key accordingly. Otherwise, data reporting will be rejected due to authentication failure.

Upgrade

Onesuite-Pilot is continuously iterated. An upgrade to the latest version is recommended in the following cases:
When a new version is released, upgrade if you need to use new features or obtain bug fixes.
If --auto-update was not enabled during installation, you need to manually update to the latest version.
Note:
For users who enabled --auto-update during installation, the program is upgraded automatically, so you usually do not need to run this command manually. The upgrade does not overwrite the existing ~/.onesuite-pilot/config.json configuration.
Run the following command directly to complete the upgrade:
curl -fsSL https://onesuite-pilot-1254077820.cos.ap-shanghai.myqcloud.com/onesuite-pilot/installer.sh | bash -s -- upgrade
After the upgrade is complete, run onesuite-pilot info to confirm that the version has been updated.

Uninstall

To uninstall, rerun the installation script with the --purge parameter (or follow the prompts of the service management script) to stop the service and remove the Hook and autostart entries. The data directory ~/.onesuite-pilot can be manually cleaned up as needed.
curl -fsSL https://onesuite-pilot-1254077820.cos.ap-shanghai.myqcloud.com/onesuite-pilot/installer.sh | bash -s -- uninstall --purge

FAQs

After Installation, userId Is Reported as the Hostname: How Do I Change It to a Custom Value?

Refer to Scenario 1 in Modifying Configuration. Add the userId field at the top level of config.json, and then restart. Reinstallation is not required.

Is a Reinstall Required After the Configuration Is Modified?

No. You can directly edit config.json and run onesuite-pilot restart. Reinstalling overwrites the existing configuration, so use it only when a fresh deployment is required.

Why Are the Old userId/Topic Still in the Log File?

Local log files (such as the metrics files under logs/) are refreshed only when data flows in. During idle periods, they retain historical residual values. Refer to the output of config.json and onesuite-pilot info, as these two represent the currently effective configuration.

How to Confirm That the Configuration Has Taken Effect?

Run onesuite-pilot info to view the configuration loaded by the service. After the next Agent activity generates data, check the gen_ai.user.id field in the latest record under ~/.onesuite-pilot/logs/<agent>/*.jsonl to confirm.

Why Are New Data Not Immediately Visible in the CLS Console After They Are Reported?

This is typically caused by the reporting cadence rather than a fault. Data collection occurs only when there is actual coding activity from an AI Agent. No new data is generated when the service is idle. Newly collected data is first buffered locally and then reported in batches after the trigger conditions are met. To reduce network overhead and improve throughput, Onesuite-Pilot uses a batch flush mechanism instead of sending each piece of data in real time. A report is triggered when any of the following conditions is met:
A certain number of records have been accumulated.
Time interval upon arrival
A certain number of bytes have been accumulated.
Próximo: Release Notes

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation