/alibabacloud-agentloop-dataset

name: alibabacloud-agentloop-dataset
description: Operate Alibaba Cloud AgentLoop Dataset resources with aliyun CLI and the AgentLoop API version 2026-05-20. Use when requests concern AgentLoop datasets, data rows, Dataset schemas, embedding fields, semantic search, ExecuteQuery, AgentSpace data, 数据集, 数据写入, 数据查询, 语义检索, or ask to create/list/get/update AgentLoop datasets, append structured rows, run read-only SQL or SearchExpr queries, inspect query results, or debug aliyun agentloop Dataset commands.

AgentLoop Dataset Skill

Scenario

Operate the public AgentLoop Dataset surface through `aliyun agentloop`:

• Manage Dataset resources and schemas.
• Append typed structured rows without constructing INSERT SQL.
• Query data with read-only `execute-query`.
• Run full-text, semantic, SQL, or search-pipe-SQL retrieval.

Do not expose or operate service deployment, database, cache, or other internal implementation details. Do not manage AgentSpaces unless the user separately requests that scope.

Treat commands and parameters exposed by the installed public AgentLoop CLI plugin as the external capability boundary. Do not expose a capability found only in backend development code until it appears in the published CLI help or public API contract.

CLI Prerequisites

**Require Aliyun CLI 3.3.3 or later.**

aliyun version

**Require the AgentLoop plugin 0.7.1 or later.** This version exposes all Dataset commands used by this skill, including `add-dataset-data` and the extended `execute-query` parameters.

aliyun plugin show --name agentloop

If the AgentLoop plugin is missing or older than 0.7.1, install it through the configured Aliyun CLI plugin source, then verify it before continuing:

aliyun plugin install --names agentloop
aliyun plugin show --name agentloop

Use the plugin ID `agentloop` for installation; successful output identifies the installed package as `aliyun-cli-agentloop`. If the Aliyun CLI itself is missing or below 3.3.3, stop and ask the user to upgrade the CLI through their organization-approved process outside this session. Do not download or install CLI binaries from this Skill.

Authentication

Use an existing Aliyun CLI profile, Alibaba Cloud environment credentials, STS, OAuth, or an instance RAM role.

Security rules:

• Never read, echo, print, or paste AccessKey IDs, AccessKey secrets, security tokens, or other credentials.
• Never ask the user to pass literal credentials in a command or conversation.
• Never run `aliyun configure set` with literal credential values.
• Use only `aliyun configure list` to check whether a usable identity and region are configured.

aliyun configure list

If no valid identity is available, stop and ask the user to configure credentials outside this session. Do not continue to a Dataset request.

RAM Permissions

Dataset operations use the six concrete RAM actions listed in `references/ram-policies.md` and support Dataset resource ARNs. Do not use a wildcard action pattern in a policy.

On any permission failure:

1. Capture the API action, denied RAM action, and request ID without exposing credentials. 2. Read `references/ram-policies.md`. 3. If `ram-permission-diagnose` is installed, invoke it. Otherwise show the missing action and the least-privilege policy template. 4. Pause until the user confirms that permission was granted before retrying.

Parameter Confirmation

Confirm user-customizable values before executing a cloud request. Reuse explicit values already supplied by the user; do not ask again.

| Parameter | Required for | Rule | | --- | --- | --- | | `--region` | All operations when the configured region is not explicitly accepted | Dataset and AgentSpace must be in this region. | | `--agent-space` | All commands | Confirm the exact AgentSpace name. | | `--dataset-name` | All Dataset commands in this skill | Use 4-63 ASCII characters matching `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`; do not use uppercase letters, hyphens, spaces, or leading, trailing, or consecutive underscores. | | `--description` | Optional create/update description | Keep the UTF-8 encoded value at 255 bytes or fewer. | | `--schema` | Create; optional update | Confirm field names, types, Chinese tokenization, JSON keys, and embedding use. The only supported public embedding model value is `agentloop-embedding-v4`. | | `--data-array` | Structured writes | Confirm the rows or the source from which they are constructed. | | `--query` | `execute-query` | This Skill permits only read-only SELECT or SearchExpr query text. The public API accepts one raw query string and exposes no bind-parameter option; the default query-text cap is 10 MiB. | | `--from`, `--to` | Optional SELECT time window | Use non-negative Unix seconds over `__time__`; `to` is exclusive and, when both are non-zero, `from` must be less than `to`. | | `--offset`, `--length` | Optional SELECT result window | Use non-negative integers only for SELECT; `length` cannot exceed the configured SELECT maximum, which defaults to 100,000. | | `--max-output-length` | Optional SELECT truncation | `0` or omitted returns full values. | | `--biz-version` | Optional SELECT against an existing snapshot | This CLI flag serializes to the request-body field `version`; confirm the exact version and omit it for current data. | | `--client-token` | Optional create/update/write idempotency | Generate one non-secret UUID and reuse it for retries of the same logical request. |

Observability

Generate one session ID before the first AgentLoop API request in a skill session. Generate it once, require exactly 32 lowercase hexadecimal characters, and reuse it for the entire session:

SESSION_ID="$(openssl rand -hex 16)"
USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-agentloop-dataset/${SESSION_ID}"

The canonical CLI template is:

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agentloop-dataset/{session-id}"

Observability