Alibabacloud Data Agent MCP Skill

metadata: author: DataAgent Team version: "3.1.0"

Changelog

• v3.1.0 — File upload moved out of the server's data path: data_agent_upload_file (server-side local path read) is replaced by data_agent_get_upload_signature + data_agent_upload_callback, so the caller (e.g. Feishu Aily, the host agent) POSTs the file bytes to OSS itself. The upload.allowed_dirs / DATA_AGENT_UPLOAD_DIRS allowlist is removed — the server no longer reads caller-chosen local files on any transport. Tool surface: 19 data_agent_* tools.
• v3.0.0 — Session mode tiers aligned with the platform: auto / lite / pro / ultra (defaults: auto for database, pro for file); legacy ASK_DATA/ANALYSIS/INSIGHT values are auto-mapped to lite/pro/ultra for backward compatibility. New plan_mode parameter on data_agent_create_session (force = always generate an execution plan, disable = skip planning), injected as SessionConfig.PlanMode. Generic multi-tenant identity mode: identity config section (legacy aily: alias still parsed) with configurable identity headers (defaults x-aily-*, Feishu Aily compatible) and two mapping styles — identity.default (global sharing: one RAM role + workspace/agent/mode session defaults for every identified user) and identity.groups.<name> (per-group role + session defaults + member list; group wins over default). Per-user tenants (isolated client, session store sessions_dir/identity/<user>/, RoleSessionName = <prefix>-<user_id> for ActionTrail attribution) via STS AssumeRole with auto-refresh. Follow-up questions on finished sessions: data_agent_send revives completed sessions from persisted state. YAML (config.yaml) + .env configuration replaces JSON-only config. Fixed SSE parsing without event: prefix lines and watcher lifetime on HTTP transports. Repackaged as a standalone skill; binaries are built from source by scripts/select-binary.sh (Go 1.23+).
• v2.x — Tool surface grew to 18 data_agent_* tools (discovery/import, workspaces, custom agents, file upload, session lifecycle). Event-driven waiting: data_agent_wait_result blocks until the session needs LLM attention; data_agent_status gained server-side wait_timeout; CRITICAL ANTI-LOOP rules against repetitive polling. data_agent_result returns chart images as MCP ImageContent. Clear split between workspace Data Center metadata (data_agent_list_workspace_databases, authoritative for create_session) and DMS discovery (data_agent_search_dms_databases, import only). API Key auth mode and file analysis flows.
• v2.0.0 — Initial Go MCP Server architecture: Session Daemon with background SSE monitoring, auto-confirm for ANALYSIS mode, core session tools.

Runtime Contract

This skill requires the data-agent MCP server to be registered in the host runtime. Installing the skill only gives the agent instructions; it does not automatically make data_agent_* tools available in every client.

For any Data Agent task, call the exposed MCP tools such as data_agent_list_workspace_databases, data_agent_create_session, data_agent_status, and data_agent_result. Do not answer from cached knowledge, do not run scripts/select-binary.sh as a one-off CLI workflow, do not start the bundled server during task execution, and do not call Alibaba Cloud APIs or the MCP HTTP endpoint directly with curl.

If no data_agent_* MCP tools are visible, stop immediately and report: "Data Agent MCP server is not registered in this agent runtime. Task aborted." In OpenClaw, AgentHub, or other hosted runtimes, MCP registration must be completed during the runtime setup/install phase; a task-running agent must not self-register, edit runtime config, launch select-binary.sh, probe localhost ports, or curl /mcp as a workaround.

Trigger Checklist

Use this skill for any prompt that mentions one of these intents or names:

• Intents (any language, including Chinese): data analysis, database query, SQL analysis, report generation, data insight, file analysis, upload file for analysis, workspace, custom Agent, session creation, session query, stop session, delete session
• Names: Data Agent, data-agent, DMS, Data Center, database analysis, SQL analysis, generate report, data insight, file analysis, workspace, custom agent, session status, stop session
• Tool names or resources: any data_agent_* tool, DMS database/table/import metadata, Data Agent workspace/session/file/report resources

Mandatory Tool-Use Rules

When this skill is active:

1. Use data_agent_* MCP tools as the only execution path.
2. Do not fall back to aliyun CLI, Python SDK, direct HTTP/curl, locally cached metadata, or hardcoded database IDs.
3. If data_agent_* tools are not available in the runtime, report: "Data Agent MCP server is not registered in this agent runtime. Task aborted." Then stop the task. Do not start the bundled server, do not edit runtime settings, do not probe localhost ports, do not call /mcp with curl, and do not attempt CLI/SDK/API fallbacks.
4. For database analysis, always call data_agent_list_workspace_databases() in the same conversation turn immediately before data_agent_create_session, and use only the returned row for database_id, db_name, instance_id, instance_name, and engine. This applies in ALL auth modes (AK/SK and API Key). Never guess, infer, or reuse database/instance parameters from memory, prior conversations, user-provided IDs, or DMS search results — workspace contents change over time and stale values cause Specified parameter InstanceId is not valid or wrong-database analysis.
5. For file analysis, the caller uploads the file itself: call data_agent_get_upload_signature(), POST the file bytes to the returned OSS host, then call data_agent_upload_callback() to get the file_id for data_agent_create_session(file_id=...). The MCP server never reads local files.
6. For session query/status/stop/delete-style requests, use data_agent_list_sessions(), data_agent_status(), and data_agent_stop_session(). If the user asks for hard deletion, explain that the current MCP surface supports stopping monitoring and cleanup via data_agent_stop_session, not permanent remote deletion.
7. Do not invent deprecated tool names or legacy command patterns such as data_agent_search_databases, data_agent_list_databases, file subcommands, attach --session-id, reports --session-id, --db-id, or wildcard table imports.
8. Workspace names are display names, not IDs. If the user gives a workspace name such as dev-workspace, call data_agent_list_workspaces(type="ALL"), exact-match name, and use the matched workspace_id for workspace-scoped tools. Do not pass the name itself as workspace_id and do not guess an ID.

Installation & Setup

Setup is an install-time responsibility, not part of task execution. This skill assumes the data-agent MCP server (19 data_agent_* tools) is already registered in the host runtime.

• Full setup reference (transports & runtime registration for Claude Code / OpenClaw / hosted runtimes, credentials, YAML + .env configuration, multi-tenant identity mode, observability): references/INSTALLATION.md
• Human deployment walkthrough (systemd, dacli verification client): README.md
• RAM permissions: references/ram-policies.md

Facts the agent may need when the user asks setup questions (do not perform setup during analysis tasks):

• The skill ships no server source or binaries. The operator builds data-agent-mcp-server from the repository's server/ project (Go 1.23+) or deploys a release binary; scripts/select-binary.sh locates it ($DATA_AGENT_SERVER_BIN > skill assets/bin/ > monorepo server/bin/). Transports: stdio (default), Streamable HTTP (MCP_TRANSPORT=streamable-http + MCP_PORT, endpoint /mcp), SSE.
• Credentials come from the Alibaba Cloud default chain (AK/SK env vars, ~/.aliyun/config.json, ECS role) or DATA_AGENT_API_KEY. API Key mode disables data_agent_list_tables, data_agent_search_dms_databases, data_agent_search_instances, and data_agent_import_database; data_agent_list_workspace_databases and data_agent_list_imported_tables still work and remain the mandatory metadata source.
• Optional multi-tenant identity mode maps per-user identity headers (defaults x-aily-*) to RAM roles via STS AssumeRole; group config can inject workspace_id / custom_agent_id / mode as data_agent_create_session defaults — explicit tool arguments always win.

MCP Tools (19)

Core Analysis

data_agent_list_workspace_databases

List databases imported into a workspace's Data Agent Data Center. This is the authoritative source for database analysis sessions.

data_agent_list_workspace_databases(workspace_id?)
→ [{db_id, db_name, db_type, instance_id, instance_resource_id, catalog_name}, ...]

• workspace_id (optional): target workspace. Defaults to the configured workspace. Resolve names to IDs via data_agent_list_workspaces; never pass a workspace name.

Use this tool before data_agent_create_session for database analysis. Pass its db_id, db_name, instance_id, instance_resource_id, and db_type into the session options.

data_agent_create_session

Create an analysis session with automatic SSE monitoring. Supports database analysis (database_id) or file analysis (file_id from data_agent_upload_callback). For pro/ultra mode with auto_confirm=true, all plan/SQL/report confirmations are handled automatically.

data_agent_create_session(
  query,                                          # Required
  database_id?, db_name?, tables?,                # For database analysis (database_id required)
  file_id?, file_name?,                           # For file analysis (file_id required, from data_agent_upload_callback)
  mode="auto|lite|pro|ultra",                     # Default: auto for database, pro for file
                                                  # (legacy ASK_DATA/ANALYSIS/INSIGHT auto-map to lite/pro/ultra)
  plan_mode="force|disable",                      # pro/ultra only: force = always generate an execution plan,
                                                  # disable = skip planning and execute directly; empty = server default
  auto_confirm=true,                              # Auto-confirm plans/SQL/reports
  instance_id, instance_name, engine="mysql",     # Optional (database only)
  workspace_id, custom_agent_id                   # Optional
)
→ {session_id, status, mode, auto_confirm}

Note: database_id and file_id are mutually exclusive — use one or the other. For file analysis, pass the file_id returned by data_agent_upload_callback and the original filename.

Database session gotcha: data_agent_search_dms_databases is only for DMS discovery/import. Its returned instance_id may be 0 or otherwise unusable for create_session, which can cause Specified parameter InstanceId is not valid or a database_None_<db_name> data source. Before creating a database session, always call data_agent_list_workspace_databases() in the target workspace and use the imported database row from Data Center:

• database_id = db_id
• db_name = db_name
• instance_id = instance_id
• instance_name = instance_resource_id
• engine = db_type

If the database is not returned by data_agent_list_workspace_databases(), use data_agent_search_dms_databases → data_agent_list_tables → data_agent_import_database, then call data_agent_list_workspace_databases() again and use that row for create_session.

data_agent_wait_result

Block until the session needs LLM attention: completed, error, canceled, or waiting for manual input. For auto_confirm=true sessions this fires only on completion/error, collapsing all intermediate polling into a single blocking call. Preferred over looping data_agent_status where this tool is exposed.

May be unavailable. Non-blocking deployments (e.g. DataBuddy IM) disable this tool via tools.exclude because a long internal block can exceed the outer MCP call timeout. If data_agent_wait_result is not in your tool schema, do not call or invent it — fall back to the one-shot status snapshot protocol (create session, take at most one data_agent_status snapshot per user turn, end the turn if still running). See the Progress Tracking Protocol below.

data_agent_wait_result(session_id, timeout=55)
→ {session_id, status, reason, mode, current_step, total_steps, step_name,
   waiting_for, waiting_detail, checkpoint, conclusions, artifacts, error_message, updated_at}

• timeout (default and ceiling: server wait cap, 55s unless DATA_AGENT_WAIT_CAP overrides it): max seconds to block. The server clamps larger values so the response always beats common MCP client transport timeouts (~120s) — never rely on a longer block.
• reason: "completed" | "error" | "canceled" | "waiting_input" | "timeout" | "client_canceled" | "duplicate_wait"
• On reason="timeout" the session is still running and the response carries checkpoint_delta, new_conclusions, and next_action: briefly report that progress to the user, then call data_agent_wait_result again with the same session_id. Loop until a terminal reason (cap the loop, e.g. 20 rounds for pro/ultra).
• Never call in parallel for the same session: a duplicate concurrent call returns immediately with reason="duplicate_wait" and a warning instead of blocking.
• Returns immediately when the SSE watcher fires any terminal or input event — no polling.

data_agent_status

Get current status snapshot. Use wait_timeout when you want incremental step-level progress during a long run.

data_agent_status(session_id, wait_timeout=30, poll_hint="check-N")
→ {session_id, status, mode, current_step, total_steps, step_name, waiting_for, conclusions, artifacts, poll_seq, changed, ...}

• wait_timeout (recommended: 30): seconds the MCP server blocks waiting for the next status change (capped server-side at the wait cap, 55s by default). Returns changed=true when checkpoint advances; changed=false on timeout. Long-poll calls do not count toward the anti-loop poll_seq warning; bare snapshots (wait_timeout omitted) do. Never call in parallel for the same session.
• poll_hint (optional): incrementing tag ("check-1", "check-2", …) to distinguish consecutive calls in history.

data_agent_watch_session

Attach the MCP Server to an existing remote Data Agent session (e.g. one created by the Console/Web UI or a previous process) and start background SSE monitoring. Returns immediately after the server-side watcher is registered; then use data_agent_status / data_agent_wait_result / data_agent_send as usual.

data_agent_watch_session(session_id, agent_id?, workspace_id?, mode?, auto_confirm=true)
→ {ok, session_id, status}

data_agent_send

Send a message to an active session (confirmations, follow-up questions, human input).

data_agent_send(session_id, message)
→ {ok, status}

Follow-up questions on finished sessions are supported. If the session has already completed (or the server restarted), data_agent_send transparently revives it from persisted state and resumes SSE monitoring from the saved checkpoint — the remote Data Agent session keeps the full conversation context, so pronouns like "那最低的呢？" resolve against earlier turns. After sending, use data_agent_wait_result / data_agent_result as usual; each turn appends a new entry to conclusions.

data_agent_result

Get the analysis result of a Data Agent session. Returns structured JSON metadata as text, plus any chart images as ImageContent (base64).

data_agent_result(session_id)
→ Content[0]: TextContent — {status, conclusions, artifacts, images, confirmations, recommended_questions, error_message}
→ Content[1..N]: ImageContent — chart images (base64, image/png)

The images field in JSON lists persisted filenames (e.g. ["img_0.png", "img_1.png"]). Chart images extracted from SSE output_conclusion events are automatically decoded and persisted locally, then returned as MCP ImageContent objects that LLMs with vision can directly interpret.

data_agent_list_sessions

List sessions managed by the MCP Server. By default returns only active (in-memory) sessions; set include_history=true to also include completed/errored sessions from disk.

data_agent_list_sessions(include_history=false)
→ [{session_id, status, mode, current_step, total_steps, step_name, waiting_for, updated_at}, ...]

Active sessions appear first. When include_history=true, historical sessions are sorted by updated_at descending.

data_agent_stop_session

Stop the server-side monitoring (SSE watcher) of a session and release local resources. Does not cancel the remote Data Agent session — follow-ups via data_agent_send still work later. Only needed when abandoning a session early; completed sessions are cleaned up automatically.

data_agent_stop_session(session_id)
→ {ok}

File & Report

data_agent_list_files

List files and reports generated by a session. Returns download URLs.

data_agent_list_files(session_id, category?)
→ [{file_id, filename, file_type, file_size, download_url}, ...]

File artifacts are not guaranteed. A plain pro/ultra run may produce only text conclusions and zero files. To reliably get file outputs, state it explicitly in the session query (e.g. "导出明细数据为 Excel 并生成分析报告" / "export the details as an Excel file and generate a report"). A file-producing run typically yields a Markdown report (.md), an HTML report (.html), and data exports (.xlsx) with OSS pre-signed download_urls.

Prefer omitting category. category="WebReport" only matches interactive web-rendered reports (produced by the report-render confirmation flow) and often returns empty even when .md/.html/.xlsx artifacts exist. Call without category to get the full list, then filter by file_type yourself.

data_agent_get_upload_signature

Step 1/2 of file upload: get a pre-signed OSS POST policy so the caller uploads the file itself — the MCP server never touches the file bytes or the local filesystem. Supported types: CSV, XLSX, XLS, JSON, TXT.

data_agent_get_upload_signature(file_name, file_size)
→ {upload_host, oss_key, form_fields, file_content_type, instructions}

• file_name: bare filename with extension (e.g. sales.csv); path components are stripped.
• file_size: size in bytes; must match the content actually uploaded.

Then perform the upload: POST multipart/form-data to upload_host, adding every form_fields entry as a form field and the file bytes as the final part named file with Content-Type: <file_content_type>. HTTP 200 means the upload succeeded.

data_agent_upload_callback

Step 2/2 of file upload: register the completed OSS upload with the Data Center. Call only after the multipart POST returned HTTP 200.

data_agent_upload_callback(file_name, oss_key, file_size)
→ {file_id, file_name, size}

• oss_key: the oss_key returned by data_agent_get_upload_signature.
• Returns file_id (Data Center ID, e.g. f-xxx) for use with create_session.

Resource Discovery

Database Tool Naming: DMS Search vs Workspace Data Center

If the user asks to analyze a database, first try data_agent_list_workspace_databases(). Use data_agent_search_dms_databases() only when the database is missing from the workspace list and must be imported.

data_agent_list_tables

List all tables in a DMS database. Queries DMS directly — not workspace-scoped. Use for discovering tables before import.

data_agent_list_tables(database_id)
→ [{table_name, table_id, engine}, ...]

data_agent_list_imported_tables

List tables already imported into a workspace. Only shows tables tagged for that workspace.

data_agent_list_imported_tables(database_id?, workspace_id?)
→ [{table_name, table_id, engine, db_id, db_name}, ...]

• database_id (optional): DMS database ID. Omit to list imported tables across all databases in the workspace; each row carries db_id/db_name for attribution.
• workspace_id (optional): target workspace. Defaults to the configured workspace.

data_agent_search_instances

Search DMS-managed database instances.

data_agent_search_instances(search_key?, db_type?)
→ [{instance_id, instance_alias, host, port, db_type, env_type, instance_resource_id}, ...]

data_agent_search_dms_databases

Search databases in DMS by schema name.

data_agent_search_dms_databases(search_key)
→ [{database_id, schema_name, host, port, instance_id, db_type, env_type}, ...]

Use this tool to discover databases and obtain a DMS database_id for table listing/import. Do not treat its instance_id as authoritative for create_session; it may be 0. For database analysis sessions, use data_agent_list_workspace_databases() after import and pass that workspace Data Center row's instance_id and instance_resource_id.

data_agent_import_database

Import database tables into a Data Agent workspace. Uses DMS TagMetaAsset to tag tables into the target workspace's data center.

Important: You must pass specific table names — wildcard * is NOT supported. Use data_agent_list_tables first to get the exact table names, then pass them to this tool.

data_agent_import_database(
  database_id,                             # Required: DMS database ID
  tables,                                  # Required: comma-separated table names (NO wildcard *)
  workspace_id?                            # Optional: target workspace (default: configured workspace)
)
→ {ok, database_id, tables}

Typical flow:

1. data_agent_search_dms_databases(search_key="employees") # Get DMS database_id
2. data_agent_list_tables(database_id="68897585")         # Get exact table names
3. data_agent_import_database(
     database_id="68897585",
     tables="employees,departments,salaries")             # Import specific tables

Workspace & Agent

data_agent_list_workspaces

List Data Agent workspaces (collaborative spaces). Use this tool to resolve a workspace display name to the required workspace_id.

data_agent_list_workspaces(type?)    # MY (default) | ALL
→ [{workspace_id, name, type}, ...]

When the user names a workspace, call data_agent_list_workspaces(type="ALL") and exact-match the returned name. Values like dev-workspace are names, not valid workspace_id values.

data_agent_list_agents

List custom Data Agent agents. Agents belong to a specific workspace — to find agents in a shared workspace, pass that workspace's ID.

data_agent_list_agents(
  status?,                           # RELEASED (default)
  workspace_id?                      # Default: personal workspace; must be an ID returned by data_agent_list_workspaces, not a name
)
→ [{agent_id, name, description, status}, ...]

Note: Custom Agents are scoped to workspaces. Use data_agent_list_workspaces first to find workspace IDs, then pass the desired workspace_id to data_agent_list_agents. If omitted, only agents in the user's personal workspace are returned. Never pass a workspace display name such as dev-workspace as workspace_id.

Workflows

Quick Q&A (lite)

1. data_agent_list_workspace_databases()          # Discover imported databases in current workspace
2. data_agent_create_session(
     database_id, db_name, tables, query,
     instance_id, instance_name, engine,
     mode="lite", auto_confirm=true)              # or omit mode for "auto" (backend decides)
3. data_agent_wait_result(session_id, timeout=55) # Block until completed/error/waiting_input
                                                    # (if excluded: one-shot data_agent_status snapshot, then end turn if still running)
4. data_agent_result(session_id)                  # Get conclusion (when completed)
5. data_agent_list_files(session_id)              # Get reports/charts; embed images as ![](download_url)

Follow-up in lite mode: lite sessions support multi-turn conversation. When the user asks a follow-up question about the same database (e.g. "what about last month?" or "break it down by region"), use data_agent_send(session_id, message) on the existing session instead of creating a new one. The session retains prior SQL context, making follow-ups faster and more accurate. Only create a new session when the user switches to a different database or starts an unrelated analysis topic.

For database sessions, prefer data_agent_list_workspace_databases() over data_agent_search_dms_databases() as the source of database_id, instance_id, instance_name, and engine. DMS search can return instance_id=0; passing that to create_session may fail with Specified parameter InstanceId is not valid.

Deep Analysis (pro/ultra, auto-confirm)

1. data_agent_create_session(
     ..., mode="pro", auto_confirm=true)          # All confirmations automatic ("ultra" for the most thorough tier)
2. LOOP data_agent_wait_result(session_id, timeout=55)  # Server-capped block; pro/ultra runs need several rounds
     reason=="timeout" → report checkpoint_delta/new_conclusions to user, loop again (max ~20 rounds)
     reason terminal   → exit loop
                                                    # (if excluded: one-shot data_agent_status snapshot, then end turn if still running)
3. data_agent_result(session_id)                  # Get multi-step conclusions
4. data_agent_list_files(session_id)              # Get artifacts

When to use data_agent_status instead: use it when you want to push intermediate step progress to the user (plan text, per-step conclusions, chart images) during a long run. Call data_agent_status(session_id, wait_timeout=30, poll_hint="check-N") in a loop until status != running; see Status Check Protocol below.

Database Discovery & Import

1. data_agent_search_dms_databases(search_key="sales")   # Find in DMS → get database_id
2. data_agent_list_tables(database_id="15553454")        # Discover all tables in DMS (before import)
3. data_agent_import_database(
     database_id="15553454",
     tables="orders,customers,products")                 # Import specific tables (NO wildcard *)
4. data_agent_list_imported_tables(database_id="15553454")  # Verify tables imported to workspace
5. data_agent_list_workspace_databases()                  # Get workspace row with valid instance_id/instance_resource_id
6. data_agent_create_session(
     database_id="<db_id from list_workspace_databases>",
     db_name="<db_name from list_workspace_databases>",
     tables="orders,customers,products",
     instance_id="<instance_id from list_workspace_databases>",
     instance_name="<instance_resource_id from list_workspace_databases>",
     engine="<db_type from list_workspace_databases>",
     query="...")                                        # Use workspace row, not raw search result

Note: list_tables queries DMS directly (all tables). list_imported_tables shows only tables tagged in the active workspace. Important: When creating a session after import, re-read data_agent_list_workspace_databases() and use that returned row. Do not create the session directly from data_agent_search_dms_databases output if instance_id is 0 or missing.

File Analysis (Upload + Analyze)

1. data_agent_get_upload_signature(file_name="sales.csv", file_size=1024)
   → {upload_host, oss_key, form_fields, file_content_type, instructions}
2. POST multipart/form-data to upload_host                # Performed by the caller (e.g. the host agent),
   → form_fields as form fields + file bytes as final     # not by the MCP server
     part named "file" (Content-Type: file_content_type)
3. data_agent_upload_callback(file_name="sales.csv", oss_key="<oss_key>", file_size=1024)
   → {file_id: "f-xxx", file_name: "sales.csv", size: 1024}
4. data_agent_create_session(
     file_id="f-xxx", file_name="sales.csv",
     query="analyze sales trends",
     mode="pro", auto_confirm=true)              # File defaults to pro mode
5. LOOP data_agent_wait_result(session_id, timeout=55)  # Loop on reason=timeout, reporting progress each round
                                                    # (if excluded: one-shot data_agent_status snapshot, then end turn if still running)
6. data_agent_result(session_id)                  # Get conclusions
7. data_agent_list_files(session_id)              # Get generated reports

Supported file types: CSV, XLSX, XLS, JSON, TXT. File-based sessions default to pro mode. Use file_id instead of database_id — they are mutually exclusive.

Custom Agent Analysis

1. data_agent_list_workspaces(type="ALL")            # Find workspaces
2. Exact-match the returned workspace name, e.g. name == "dev-workspace"
3. data_agent_list_agents(workspace_id="<matched workspace_id>") # Use ID, never the name
4. data_agent_create_session(
     ..., custom_agent_id="ca-xxx",
     workspace_id="<matched workspace_id>")           # Use custom agent in its workspace

If no returned workspace has the requested name, stop and say the workspace was not found; include the visible workspace names as candidates. Do not call data_agent_list_agents with the unresolved name.

Workspace Name Resolution

1. data_agent_list_workspaces(type="ALL")
2. Find the row where name exactly equals the user-provided workspace name
3. Reuse that row's workspace_id for data_agent_list_agents, data_agent_create_session, or imports
4. Report both name and workspace_id in the final answer when the user asked for a named workspace

Example:

User: list the custom Agents in the "dev-workspace" workspace
1. data_agent_list_workspaces(type="ALL")
2. match row.name == "dev-workspace"
3. data_agent_list_agents(workspace_id=row.workspace_id)
4. answer with row.workspace_id, row.name, row.type, and agent names

Never put a workspace display name into workspace_id or DATA_AGENT_WORKSPACE_ID; both must use a real workspace ID.

Custom Agent Session

1. Resolve the workspace name to workspace_id if the user supplied a name
2. data_agent_list_agents(workspace_id="<matched workspace_id>") # Find custom agent
3. data_agent_create_session(
     ..., custom_agent_id="ca-xxx",
     workspace_id="<matched workspace_id>")

Session Management (List / Status / Stop)

1. data_agent_list_sessions(include_history=true)      # Find active and historical sessions
2. data_agent_status(session_id="...")                 # Inspect current progress/state
3. data_agent_stop_session(session_id="...")           # Stop monitoring and clean local resources

Use this workflow when the user asks to query sessions, check progress, stop/cancel a running session, or delete/clean up a session. The current MCP surface does not expose permanent remote session deletion; for delete-style requests, call data_agent_stop_session for active monitoring cleanup and clearly state that hard deletion is not supported by the current tools.

Analysis Modes

Legacy mode names are auto-mapped by the server: ASK_DATA → lite, ANALYSIS → pro, INSIGHT → ultra.

Mode selection rules — do NOT switch modes on your own:

• auto: when the user has no explicit preference — let the backend pick.
• lite: simple questions, single SQL. Supports follow-up via data_agent_send.
• pro: user asks for a report, deep analysis, or trend summary. This is the standard choice for structured output. Takes 2-40 min — that is normal.
• ultra: broader and slower than pro (up to 60 min). It explores more dimensions autonomously. Only use when the user explicitly asks for the most thorough analysis ("insight", "exploration", "全面洞察"). ultra is NOT a lighter alternative to pro — it is heavier.

NEVER switch from pro to ultra (or vice versa) to "speed things up" or because the current mode "seems slow." Both tiers are slow by design. The user chose the mode (or you chose it based on their intent) — stick with it. Only change modes if the user explicitly requests a different mode.

Plan Mode (pro/ultra only)

plan_mode controls whether a pro/ultra session generates an execution plan before running:

plan_mode has no effect on lite sessions (they never plan). Do not use plan_mode=disable as a way to "speed up" a run the user asked to be thorough — skipping the plan changes the analysis structure, not just the latency.

Session Lifecycle

Created → RUNNING (SSE monitoring active)
  ├── lite: RUNNING → COMPLETED (auto)
  ├── pro/ultra (auto_confirm=true):
  │     RUNNING → ask_plan (auto-confirm) → step execution → ask_sql (auto-confirm) → COMPLETED
  ├── pro/ultra (auto_confirm=false):
  │     RUNNING → WAIT_INPUT (ask_plan) → user confirms → RUNNING → ... → COMPLETED
  └── ERROR / CANCELED (on failure)

The MCP Server's Session Daemon automatically:

• Monitors SSE streams for all active sessions
• Handles auto-confirmation (plan, SQL, report render)
• Tracks step progress and extracts conclusions
• Cleans up stale sessions (IDLE > 30 min)
• Reconnects on SSE disconnection (exponential backoff, up to 10 retries)
• Restores active sessions on server restart

Progress Tracking Protocol

CRITICAL ANTI-LOOP RULES (MANDATORY)

1. NEVER call data_agent_status consecutively with the same arguments
2. NEVER call data_agent_status more than 2 times total in one conversation
3. Only use data_agent_status for ONE-SHOT status checks (e.g., user explicitly asks "what's the progress?") or as the per-turn snapshot when data_agent_wait_result is unavailable
4. Never call or invent data_agent_wait_result when it is not in your tool schema
5. Violating these rules triggers upstream "Repetitive tool calls detected" errors that abort the entire conversation
6. NEVER abandon a running pro/ultra session and create a new one with the same or similar query — this wastes compute and restarts from zero. Stick with the existing session until it completes, errors, or is explicitly canceled by the user
7. NEVER issue parallel/duplicate calls to data_agent_wait_result or data_agent_status for the same session — issue ONE call and wait for its response. The server degrades duplicates to an immediate snapshot with reason="duplicate_wait"; a duplicate response means you must stop and wait for the original call

Choosing a waiting strategy

Two supported paths, depending on whether data_agent_wait_result is exposed in your tool schema:

• data_agent_wait_result available (default deployment) — use it. The server blocks internally and wakes up instantly via SSE. Follow the Standard Workflow below.
• data_agent_wait_result excluded (non-blocking deployments) — do NOT block. Use the one-shot status snapshot: create the session, take at most one data_agent_status snapshot per user turn, and if it is still running, tell the user the session id and that analysis is in progress, then END THE TURN. The next user message drives the next check. See One-Shot Status Check below.

Standard Workflow (when data_agent_wait_result is available)

Use data_agent_wait_result — the server blocks internally and wakes up instantly via SSE when the session reaches a terminal state or needs input. The block is capped server-side (55s by default) so each call returns before reverse-proxy read timeouts (nginx default 60s) and the MCP transport timeout; long pro/ultra runs simply take several rounds of the loop, each producing a progress update for the user.

1. data_agent_create_session(..., auto_confirm=true) → session_id
2. data_agent_wait_result(session_id, timeout=55)
   → {status, reason, ...}
   IF reason == "completed":
     → data_agent_result(session_id)        → conclusions + artifacts + chart ImageContent
     → data_agent_list_files(session_id)   # embed images as ![](url)
     → DONE
   IF reason == "error":    → report error_message → DONE
   IF reason == "canceled": → report to user → DONE
   IF reason == "waiting_input":
     → waiting_for == "ask_plan": show plan, ask user → data_agent_send → loop back to wait_result
     → else: show detail, ask user → data_agent_send → loop back to wait_result
   IF reason == "timeout" (or "client_canceled"):
     → session is still running; the response carries checkpoint_delta, new_conclusions, next_action
     → briefly report that progress to the user, then call data_agent_wait_result again
     → keep looping (up to ~20 rounds for pro/ultra); if the cap is reached, report the
       progress snapshot and session_id to the user → DONE
   IF reason == "duplicate_wait":
     → a wait is already in flight — you issued a parallel call by mistake; do NOT retry,
       wait for the original call's response

The default workflow is always:

create_session → wait_result → (if timeout: report progress) → wait_result → ... → result

NEVER use this pattern:

create_session → status → status → status → ... → result   ← FORBIDDEN

One-Shot Status Check

Use data_agent_status in two cases: (a) the user explicitly asks "what's the progress?" or similar, or (b) data_agent_wait_result is excluded from your tool schema, in which case this is the default waiting path. Either way it is a ONE-SHOT check, not a polling mechanism.

Strict constraints:

• MUST include a UNIQUE poll_hint for EVERY call (e.g., "user-asked-1", "user-asked-2")
• MUST NOT call data_agent_status more than 2 times in one conversation
• MUST stop immediately when changed=false
• If data_agent_wait_result is available and you need to wait for completion, switch to it instead of polling status. If it is excluded, do NOT wait in-turn — report progress and end the turn; the next user message drives

…(truncated)