SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdms-data-agent

dms-data-agent

Agents & models

View repository

Updated 10-15 16:47

About this skill

metadata: author: DataAgent R&D version: "1.7.1"

Changelog
  • v1.7.1: Fixed CLI ls command API response parsing issue (supports case-insensitive field names), optimized SKILL document structure, standalone document for ANALYSIS mode specifications
  • v1.7.0: API_KEY authentication support, native asynchronous execution mode, session isolation, enhanced attach mode, optimized log output
Installation

Configure credentials and region (copy the example file and fill in the real values)

OpenClaw Configuration Method

  • Check whether the following variables exist in ~/.openclaw/openclaw.json . If they do not exist, they need to be configured first:
{
  "env": {
    "ALIBABA_CLOUD_ACCESS_KEY_ID": "your-access-key-id",
    "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "your-access-key-secret"
  }
}
  • Or use API_KEY for authentication (only applicable to file analysis scenarios):
{
  "env": {
    "DATA_AGENT_API_KEY": "your-api-key"
  }
}

Other configurations (QoderWork, Claude Code, etc.)

  • Copy and create the .env file in the Skill directory

  • Or use environment variables

  • Note: If both AK/SK and API_KEY are configured, the system will prioritize AK/SK authentication

  • DATA_AGENT_REGION (such as cn-hangzhou, cn-beijing, etc.)

  • Permission requirements: Ensure the RAM user has DMS management permissions (AliyunDMSFullAccess or AliyunDMSDataAgentFullAccess)

Debugging Features

  • API request debugging: By setting the environment variable DATA_AGENT_DEBUG_API , detailed API request and response logs can be enabled
    • Available values: 'true', '1', 'yes' (case-insensitive)
    • Once enabled, detailed information for all API calls will be output, including request parameters and response content
    • Example: DATA_AGENT_DEBUG_API=1 python3 data_agent_cli.py file ...

💡 Usage Suggestions

Prompt the user to use the built-in dataset assets/example_game_data.csv to complete an analysis experience.

Data Agent CLI — Unified Command-Line Data Analysis Tool

Overview

data_agent_cli.py helps users complete the entire process fromdiscovering data → initiating analysis → tracking progress → obtaining results.

Core Concepts

⚠️ Key Prerequisite: Data Agent can only analyzedatabases already imported into the Data Agent Data Center .

  • Data Center: The data center of Data Agent; only databases here can be analyzed
  • DMS: Alibaba Cloud Data Management Service, which stores the metadata of all databases
  • Relationship: Databases registered in DMS ≠ databases in the Data Center

Usage Process：

  1. First use ls to check whether the target database exists in the Data Center
  2. Ifnot, first use the dms subcommand to search for database information, then use the import subcommand to import
  3. After successful import, you can use the db subcommand for analysis

Analysis Mode Description

db and file commands use the --session-mode The parameter specifies the analysis mode:

Mode Parameter Value Characteristics Recommended Execution Method
Ask Data Mode(Default) ASK_DATA Instant Q&A, sub-second response, returns SQL query results Synchronous execution(Default)
Analysis Mode ANALYSIS In-depth analysis, generates a multi-dimensional insights report, takes 5-40 minutes Recommended to spawn a sub-Agent for asynchronous processing

ASK_DATA Mode (Default, Synchronous)

db and file commandsUses ASK_DATA mode by default, executed synchronously, directly returns query results without waiting for background tasks:

# 数据库问数（同步，直接返回结果）
python3 dms-data-agent/data_agent_cli.py db \
    --dms-instance-id <ID> --dms-db-id <ID> \
    --instance-name <NAME> --db-name <DB> \
    --tables "t1,t2" -q "谁的销售额最高"

# 文件问数（同步，直接返回结果）
python3 dms-data-agent/data_agent_cli.py file example.csv -q "数据概览"

ANALYSIS Mode (spawn sub-Agent)

ANALYSIS mode takes a long time (5-40 minutes),must spawn a sub-Agent for background execution, to avoid blocking the main conversation.

python3 dms-data-agent/data_agent_cli.py db \
    --dms-instance-id <ID> --dms-db-id <ID> \
    --instance-name <NAME> --db-name <DB> \
    --tables "t1,t2" --session-mode ANALYSIS \
    -q "深度分析销售趋势"
# 输出：Session ID: abc123xyz

Key monitoring points:

Status Action
waiting_input Display the execution plan, wait for user confirmation then attach -q '确认执行'
completed Download the report or guide to the console for viewing
failed Prompt error message

For detailed sub-Agent specifications, see ANALYSIS_MODE.md

⚠️ Important: Session Reuse Principle

✅ Correct Approach

# 首次分析（ASK_DATA 默认同步，直接返回结果）
python3 dms-data-agent/data_agent_cli.py db ... -q "问题 1"

# 追问 - 使用 attach 复用会话（ASK_DATA 同步执行）
python3 dms-data-agent/data_agent_cli.py attach --session-id abc123xyz -q "按月分解"

❌ Incorrect Approach

# 每次都创建新会话（浪费资源，丢失上下文）
python3 dms-data-agent/data_agent_cli.py db ... -q "问题 1"  # 创建会话 A
python3 dms-data-agent/data_agent_cli.py db ... -q "问题 2"  # 又创建会话 B（错误！）

When to Use Which Command?

Scenario Command Description
First data query db / file Create a new session, ASK_DATA synchronous execution by default
Continue asking in the same session attach --session-id <ID> Reuse session
Modify/confirm the execution plan attach --session-id <ID> Reuse session, send new instructions or confirm
Get the final report reports --session-id <ID> Download the generated file locally

Session Directory Structure

Each session maintains independent state under sessions/{session_id}/ :

File Content Purpose
status.txt running / waiting_input / completed / failed Quickly determine task status
progress.log Execution log, including plan content and phase conclusions Sub-Agent reads progress and results
checkpoint.txt SSE stream position value Basis for resumable transfer
result.json Structured state Programmatic check
input.json Input parameters Input parameter record
worker.pid Worker process PID Concurrency protection 
# 子 Agent 轮询示例
cat sessions/{session_id}/status.txt      # 检查状态
cat sessions/{session_id}/progress.log    # 读取进度与结论

⚠️ Session Validity: Session validity period is 6 hours, after timeout you need to use db to initiate a new session.

Quick Start

# 1. 查看可用数据库
python3 dms-data-agent/data_agent_cli.py ls

# 2. 问数分析（ASK_DATA，同步，直接返回结果）
python3 dms-data-agent/data_agent_cli.py db \
    --dms-instance-id <ID> --dms-db-id <ID> \
    --instance-name <NAME> --db-name <DB> \
    --tables "t1,t2" -q "谁的销售额最高"

# 3. 追问（复用会话）
python3 dms-data-agent/data_agent_cli.py attach --session-id <ID> -q "按月分解"

# 4. 深度分析（ANALYSIS，spawn 子 Agent 执行）
python3 dms-data-agent/data_agent_cli.py db \
    --dms-instance-id <ID> --dms-db-id <ID> \
    --instance-name <NAME> --db-name <DB> \
    --tables "t1,t2" --session-mode ANALYSIS \
    -q "深度分析销售趋势"

📖 For the complete workflow, please refer to Workflow Example

Subcommand Overview

Subcommand Purpose Default Mode
ls List databases and tables in the Data Center -
db Connect to the database, initiate an analysis session ASK_DATA, synchronous
file Upload local files or analyze existing files in the Data Center ASK_DATA, synchronous
attach Connect to an existing session and continue the conversation Sync
dms DMS tool integration (data discovery) -
import Import DMS databases into Data Center -
reports View or download report and chart files generated by the session -

For details, see:Command Reference

Analyze from Data Center files

Using the file subcommand together with the --file-id parameter, you can directly analyze files in the Data Center:

# 默认 ASK_DATA 同步问数
python3 dms-data-agent/data_agent_cli.py file --file-id f-8941bx83xy9513xvpewrha01m -q "数据概览"

# ANALYSIS 深度分析（spawn 子 Agent 执行）
python3 dms-data-agent/data_agent_cli.py file --file-id f-8941bx83xy9513xvpewrha01m --session-mode ANALYSIS -q "深度分析"

FAQ and Best Practices

Issue/Scenario Solution
Session reuse Use attach --session-id <旧ID> to continue
Session timeout/network interruption Use attach --checkpoint <N> to resume from a breakpoint
Want to modify the analysis plan Use attach -q "修改为..." instead of re- db
View historical sessions View the sessions/<session_id>/ directory
The ANALYSIS task takes too long Spawn a sub-Agent for background processing so the main flow is not blocked
Repeated execution reports "worker already running" Wait for the current task to complete, or view progress.log to confirm progress

For complete workflow examples (such as importing from DMS, background execution, etc.), see:Workflow Examples

Project Structure

dms-data-agent/           # Skill 目录
├── SKILL.md              # 本文档
├── data_agent/           # SDK 模块
├── cli/                  # CLI 模块
├── sessions/             # 会话数据（分析结果、报告、图片）
└── references/           # 参考文档