/alibabacloud-apsaradb-agent

name: alibabacloud-apsaradb-agent
description: Readonly Alibaba Cloud ApsaraDB consultation, resource queries, and diagnostics. Use for database product questions, instance configuration and cross-region inventories, performance and slow SQL analysis, backup and security checks, and evidence-based optimization recommendations.

Alibaba Cloud ApsaraDB Agent

Scenario Description

Use Alibaba Cloud ApsaraDB Agent as a readonly cross-product database expert. Consultation, instance queries, and diagnosis go to the agent in readonly mode. Supported products include PolarDB, Tair/Redis, MongoDB, Lindorm, PolarDB-X, DBS, RDS, AnalyticDB, ClickHouse, SelectDB, DTS, DMS, and DAS. This public release supports analysis and recommendations only; resource creation, deletion, updates, order placement, confirmation execution, and local resource-changing CLI workflows are outside its scope.

**Architecture**: `Agent Skill -> call_apsaradb_agent.sh -> aliyun das get-yao-chi-agent (ExtraInfo.mode=readonly) -> ApsaraDB service -> product Planner and product Skill`

Supported readonly capabilities include instance, cluster, node, endpoint, and configuration queries; CPU, memory, storage, connection, QPS, latency, capacity, slow SQL, execution plan, lock, session, and log analysis; parameter guidance; and backup, recovery, availability, and security checks.

| Capability | Path | Resource-change boundary | |---|---|---| | Product consultation | Agent, readonly | No change | | Instance queries and diagnosis | Agent, readonly | No change | | Optimization recommendations | Agent, readonly | Explain options and risks; no execution commands or changes |

The script always sends `mode: readonly` and rejects any other mode. The service filters write tools in readonly mode, but treat readonly as a request contract rather than a universal guarantee: if the service ever asks for a write confirmation, the script reports `[ReadonlyViolation]`, never approves it, and exits nonzero.

Passwords, tokens, AccessKeys, credentials, and private keys never go into the query, metadata, or local command arguments. For password resets, account credentials, or connection tests, direct the user to the Alibaba Cloud console or another secure secret-entry channel.

Installation

Complete the Authentication gate below before running CLI commands. The CLI, `jq`, and the **official DAS plugin (`aliyun-cli-das`)** are required local dependencies; the DAS service alone is not sufficient.

**Pre-check: Aliyun CLI >= 3.3.3 required** > [MUST] Verify: `aliyun version` — must be >= 3.3.3. > - **First install or major upgrade:** `/bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"` > - **Routine update (CLI >= 3.3.5):** `aliyun upgrade` — prefer this built-in self-update over re-running the install script. > - See `references/cli-installation-guide.md` for the official installation reference.

**Pre-check: Aliyun CLI plugin update required** > [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.

**Prepare DAS before the first agent query.** When local dependency preparation is authorized, run:

bash scripts/prepare_apsaradb_agent.sh

The helper verifies the current credential profile without printing it, checks CLI >= 3.3.3 and `jq`, applies the official plugin prerequisites above, explicitly installs `aliyun-cli-das` if the command is still unavailable, and verifies `aliyun das get-yao-chi-agent --help`. It makes no cloud API calls, never sets credentials, and never upgrades the CLI silently. An exit other than 0 means setup is incomplete; report the actual failing step instead of starting the query.

If the execution platform already ran this setup, use `bash scripts/prepare_apsaradb_agent.sh --check-only` to verify readiness. Do not ask to install a plugin that is already ready. In an unattended evaluation, dependency preparation must be authorized and completed in the task pre-execution step; do not suspend each case for the same installation approval. If local software changes are prohibited, run only `--check-only` and report the missing dependency as an environment failure.

Readonly agent queries need **only the DAS plugin**, not an RDS, PolarDB, or Tair product plugin: product queries happen inside the remote agent. Product-operation plugins and cloud write permissions are not prerequisites of this readonly release.

The copied installation guide is general official reference material. Credential setup examples are for users outside the agent conversation; do not execute credential-setting examples or unrelated product verification as part of this Skill.

Environment Variables

| Variable | Required/Optional | Description | Default Value | |---|---|---|---| | `SKILL_SESSION_ID` | Required | Fresh random 32-character lowercase hexadecimal observability ID for this Skill and conversation | None | | `SKILL_VERSION` | Required | Exact version read from this Skill's `references/manifest.json` | None | | `APSARADB_AGENT_ENDPOINT` | Optional | DAS endpoint override | `das.cn-shanghai.aliyuncs.com` | | `APSARADB_AGENT_READ_TIMEOUT` | Optional | Read timeout in seconds | `180` | | `APSARADB_AGENT_CONNECT_TIMEOUT` | Optional | Connection timeout in seconds | `30` | | `APSARADB_AGENT_THROTTLE_RETRIES` | Optional | Sequential retries for a request rejected by the per-account/source concurrent limit; integer 0–10 | `6` |

Never store credentials in these variables or pass credentials through the query, metadata, command arguments, logs, or files.

Authentication

> **Pre-check: Alibaba Cloud Credentials Required** > > **Security Rules:** > - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN) > - **NEVER** ask the user to input AK/SK directly in the conversation or command li