Alibabacloud Agentloop Dataset

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.

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 rules:

• Append --user-agent "${USER_AGENT}" to every aliyun agentloop invocation, including dry runs, retries, mutations, and verification calls. Command examples omit this repeated global flag for readability; add it before execution.
• Never generate a new session ID for an individual command or retry.
• If one workflow also uses an Alibaba Cloud SDK or Terraform, propagate the same session ID through that client's custom user-agent mechanism. Keep one session ID across CLI, SDK, and Terraform calls in the same session.
• Treat the session ID as non-secret correlation metadata. Do not substitute a request ID, account ID, AccessKey ID, or client token.
• Do not mutate global Aliyun CLI configuration to set the user agent; pass the session-scoped user agent explicitly on each request.

Core Workflow

Execute the workflow:

1. Classify the intent: Dataset management, schema change, structured write, read-only SQL/search, or verification.
2. Confirm the target region, AgentSpace, Dataset, and operation-specific inputs.
3. Run CLI, plugin, and credential checks. Stop if any prerequisite fails.
4. Read the relevant reference:
   • Dataset CRUD and schemas: references/dataset-management.md
   • Structured writes and data mutations: references/data-operations.md
   • Search and SELECT syntax: references/query-syntax.md
5. For complex JSON, run the same command with --cli-dry-run first and inspect the serialized URL, query parameters, and body.
6. Execute the approved command.
7. Verify the result using references/verification-method.md.
8. Report the request ID and verification evidence without exposing credentials or secret values.

Dataset and Schema Rules

• Treat Dataset names as unique within the target AgentSpace. A duplicate create is rejected.
• Respect the AgentSpace Dataset quota. The service fallback is 100 Datasets per AgentSpace, but the AgentSpace may supply a different quota.
• Keep create/update request bodies at 1 MiB or less.
• Require a non-empty schema.
• Use only text, long, double, and json field types.
• Use chn for text tokenization. It has no useful effect on non-text fields.
• Use embedding only on text or json fields. When present, its value must be exactly agentloop-embedding-v4; do not use an internal backend model name or invent another alias.
• Use jsonKeys only under a top-level json field. Each indexed child uses type and optional chn; do not add child embedding or another jsonKeys level unless current CLI help explicitly exposes those fields.
• Keep each top-level field name non-empty and at 50 UTF-8 bytes or fewer. The backend does not impose the Dataset-name pattern on fields, but prefer lower_snake_case to simplify SQL and case-insensitive structured writes.
• Never define reserved fields: id, __time__, __dataset_seq, __effective_seq, or __expired_seq.
• Keep the effective column budget within 300: three service columns plus one per top-level field plus one per generated embedding column.
• Treat schema updates as add-only. Omitted existing fields remain; changing or removing an existing definition is rejected. Fetch the current schema before constructing an update.

Structured Write Rules

Prefer add-dataset-data for row appends. It avoids SQL quoting errors and validates values against the Dataset schema.

• dataArray must be non-empty and every entry must be an object.
• Field matching is case-insensitive, but do not send duplicate case variants.
• Unknown fields fail the request; omitted schema fields become null.
• text values must be strings, long values integers, double values finite numbers, and json values valid JSON.
• Omit id to generate one. If supplied, it must be a UUID string.
• Omit __time__ to use the current time. If supplied, it must be a non-null, non-negative Unix timestamp in seconds.
• Never send __dataset_seq.
• One request is atomic: either all rows commit or none do. The request-body limit is 100 MiB; there is no separate fixed row-count limit for add-dataset-data.

Query Safety

• Always pass --type SQL; it is the only supported statement type.
• This Skill uses execute-query only for read-only SELECT or SearchExpr queries. Never send INSERT, UPDATE, DELETE, DDL, or multiple statements through this command.
• The public execute-query contract carries raw query text and has no bind-parameter field. Do not compose SQL from untrusted text; use add-dataset-data for user-provided values whenever it can express the write.
• The agentloop:ExecuteQuery RAM action is not statement-level read-only. This Skill's SELECT-only boundary is an instruction, not a service-side control.
• Keep the execute-query body within the default 100 MiB cap and the query text within the default 10 MiB cap.
• Use single-dataset statements. Do not assume cross-Dataset queries or joins are supported.
• Prefer explicit columns and explicit result limits. A SELECT without a limit defaults to 1,000 rows; the configured maximum defaults to 100,000 for SQL LIMIT and --length.
• Use columns with each rows entry by position; the response is row-based, not an array of objects.
• Use semantic_distance(field, 'query', 'l2') with an explicit distance type. The field must have embedding enabled.
• Keep SearchExpr similarity() thresholds in [0, 1] and topk() values as integers from 1 through 100,000.
• Do not insert user-provided values into SQL. Use add-dataset-data for writes.

Command Index

All public Dataset CLI commands, parameters, and help checks are in references/related-commands.md.

Common Mistakes

References