Alibaba Cloud AgentLoop Dataset

intent

manage alibaba cloud agentloop datasets, schemas, and structured data through the public aliyun CLI. use this skill when the user requests dataset crud operations, schema management, row appends via structured writes, read-only sql or searchexpr queries, semantic retrieval, or troubleshooting of agentloop dataset commands. do not expose internal implementation details, service deployments, or database infrastructure. operate only through the public agentloop CLI plugin boundary; do not use backend development code or undocumented apis.

inputs

aliyun CLI and AgentLoop plugin

• aliyun CLI version 3.3.3 or later (verify with aliyun version)
• AgentLoop plugin version 0.7.1 or later (verify with aliyun plugin show --name agentloop)
• if either is missing or outdated, stop and ask the user to upgrade through their organization-approved process before continuing

authentication

• existing aliyun CLI profile with valid credentials (aliyun access key, sts token, oauth, or instance ram role)
• verify with aliyun configure list; if no valid identity is available, stop and ask the user to configure credentials outside this session
• never read, echo, print, or paste access key ids, secrets, security tokens, or credentials
• never ask the user to pass literal credentials in a command

operation context

• target region (e.g., us-west-1, cn-beijing); confirm when not explicitly configured
• target agentspace name (required for all commands; confirm exact spelling)
• target dataset name (required for dataset operations; pattern is ^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$, 4-63 chars, lowercase, no hyphens or uppercase)

operation-specific parameters

• schema: field definitions with name, type (text, long, double, json), optional tokenization (chn), optional embedding (agentloop-embedding-v4), optional jsonKeys for json fields
• data-array: non-empty array of objects for structured writes; each object maps to dataset fields (case-insensitive matching); omit id and time to auto-generate
• query: read-only select or searchexpr statement (raw text, no bind parameters, max 10 mib); never insert user-provided values directly into sql
• query windows: optional --from and --to (unix seconds over time), optional --offset and --length (non-negative integers)
• client-token: optional uuid for idempotency on create/update/write operations; reuse for retries of the same logical request

external connections

• alibaba cloud agentloop api version 2026-05-20 (via aliyun agentloop cli commands)
• no oauth scope required; use existing aliyun cli credentials
• session tracking via user-agent header with generated session id (one per skill session, 32 lowercase hex chars)

procedure

1. classify the intent

   • input: user request text
   • determine whether the request is dataset management (create/list/get/update), schema change, structured write (append rows), read-only query (sql or searchexpr), or verification
   • output: intent classification

2. confirm target parameters

   • input: user request, configured aliyun cli state
   • confirm target region, agentspace name, dataset name (if applicable), and operation-specific inputs
   • reuse explicit values already supplied by the user; do not ask again
   • output: confirmed region, agentspace, dataset name, and operation parameters

3. run prerequisite checks

   • input: none
   • execute aliyun version and capture output to verify cli 3.3.3 or later
   • execute aliyun plugin show --name agentloop and capture output to verify plugin 0.7.1 or later
   • execute aliyun configure list and capture output to verify valid identity and region
   • if any check fails, stop and report the failure without attempting the operation
   • output: pass/fail status for each check; if any fails, halt workflow

4. generate session id and user-agent

   • input: none
   • execute openssl rand -hex 16 once per skill session to generate 32 lowercase hex characters
   • construct user-agent string: AlibabaCloud-Agent-Skills/alibabacloud-agentloop-dataset/{session-id}
   • output: session id (stored for reuse), user-agent string (append to every subsequent aliyun agentloop command)

5. read relevant reference documentation

   • input: intent classification from step 1
   • if dataset crud or schema: read references/dataset-management.md
   • if structured write: read references/data-operations.md
   • if search or select query: read references/query-syntax.md
   • if permission failure: read references/ram-policies.md
   • if verification needed: read references/verification-method.md
   • output: relevant reference material loaded

6. dry-run for complex operations

   • input: operation classification, command parameters
   • for complex json or query logic, run the command with --cli-dry-run flag appended
   • capture and inspect the serialized url, query parameters, and request body
   • output: dry-run result (url, params, body) or indication that operation is simple enough to skip dry-run

7. execute the approved command

   • input: confirmed parameters, user-agent string, dry-run results (if applicable)
   • construct the full aliyun agentloop command with --user-agent "${USER_AGENT}" appended
   • execute the command
   • capture stdout, stderr, and exit code
   • output: command exit code, response body (json), request id (from response headers or body)

8. verify the result

   • input: command exit code, response body, operation type
   • if exit code is non-zero, capture api action, denied ram action, and request id without exposing credentials; if ram permission failure, follow ram diagnosis steps in references/ram-policies.md
   • if exit code is zero and operation is a mutation (create, update, write), re-run a read operation (get or list) to confirm the change persisted
   • if exit code is zero and operation is a read query, inspect columns and rows in response; zip columns with each row entry
   • output: verification evidence (get/list result, query result structure, or error diagnosis)

9. report results

   • input: verification evidence, request id, operation classification
   • report request id, operation outcome (success or failure reason), and relevant verification evidence
   • do not expose credentials, secret values, access key ids, or security tokens
   • output: human-readable summary for the user

decision points

if aliyun cli or agentloop plugin is missing or outdated

• stop and ask the user to upgrade through their organization-approved process
• do not download, install, or link to cli binaries; do not attempt workarounds

if no valid aliyun cli identity is configured

• stop and ask the user to configure credentials (access key, sts token, oauth, or instance role) outside this session
• do not continue to any dataset request

if the user supplies a dataset name that violates the pattern (not lowercase, contains hyphens, uppercase, spaces, or invalid leading/trailing/consecutive underscores, or is fewer than 4 or more than 63 chars)

• reject the name and show the correct pattern: ^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$
• ask the user to provide a valid name before continuing

if the user requests a schema update that changes or removes an existing field

• reject the request; schema evolution is add-only
• fetch the current schema with aliyun agentloop get-dataset and show the user which fields already exist
• ask the user to supply only new top-level fields or a description update

if the user requests a schema with an unsupported field type (not text, long, double, or json)

• reject the schema
• show the user the supported types: text, long, double, json

if the user supplies an embedding value that is not exactly agentloop-embedding-v4

• reject the schema; do not use backend model names or invented aliases
• require the exact value: agentloop-embedding-v4

if the user supplies embedding on a non-text or non-json field

• reject the schema
• embedding is only supported on text or json fields

if the user requests a schema with reserved field names (id, time, __dataset_seq, __effective_seq, __expired_seq)

• reject the schema
• explain that these are reserved and cannot be used in top-level fields

if the user requests a structured write with an empty dataArray

• reject the write; dataArray must be non-empty
• ask the user to supply at least one row object

if the user requests a structured write with non-object entries in dataArray

• reject the write; every entry must be an object
• show the user an example: [{"field1": "value1", "field2": 123}, ...]

if the user requests a structured write with duplicate field names (case-insensitive)

• reject the write
• show the user which field appears multiple times with different casing

if the user requests a structured write with unknown field names (fields not in the dataset schema)

• reject the write
• show the user the schema fields and ask them to correct the row objects

if the user requests an execute-query with a mutation statement (insert, update, delete, ddl, multiple statements)

• reject the query; this skill permits only read-only select or searchexpr statements
• ask the user to use add-dataset-data for row appends or clarify the read-only query intent

if the user requests an execute-query that composes sql from untrusted text (e.g., user input directly in where clause)

• reject the query; do not compose sql from untrusted text
• explain that add-dataset-data is the safe mechanism for user-provided values and offer to use it instead

if the user requests an execute-query without an explicit limit on select

• warn that the query will default to 1,000 rows; recommend adding a limit clause or --length parameter
• proceed only if the user confirms or the dataset is known to be small

if the user requests a semantic_distance query without an explicit distance type

• reject the query; distance type (e.g., l2) is required
• show the user the correct syntax: semantic_distance(field, 'query', 'l2')

if the user requests a searchexpr similarity threshold outside [0, 1]

• reject the query; thresholds must be in the range [0, 1]
• ask the user to provide a valid threshold

if the user requests a searchexpr topk value outside [1, 100000]

• reject the query; topk must be an integer between 1 and 100,000
• ask the user to provide a valid topk value

if the api returns a permission error (denied ram action)

• capture the api action, denied ram action, and request id without exposing credentials
• read references/ram-policies.md to identify the missing permission
• if ram-permission-diagnose skill is available, invoke it; otherwise show the missing action and least-privilege policy template
• ask the user to confirm that permission has been granted before retrying

if the api returns a network timeout or transient failure

• retry the operation once with the same client-token (if applicable) to test for transience
• if retry succeeds, report success with the request id
• if retry fails, report the error and ask the user to verify network connectivity and retry later

if the api returns a rate-limit error

• back off and retry after a brief delay (e.g., 5 seconds)
• do not retry more than twice
• if rate limit persists, ask the user to throttle their request rate and try again

if the api returns a credential or authentication error

• stop and ask the user to refresh or reconfigure their credentials outside this session
• do not retry with the same credentials

output contract

success case (dataset crud, schema management, or structured write)

• http status: 2xx
• response body: json object with requestId field
• for create operations: response contains the new dataset metadata (name, schema, createdAt, etc.)
• for list operations: response contains an array of dataset objects, each with name, schema, and metadata
• for get operations: response contains the single dataset object with full schema and metadata
• for update operations: response contains the updated dataset metadata
• for write operations: response contains requestId and a rowCount or status indicating rows accepted
• all timestamps in unix seconds (non-negative integers)
• all ids are uuid strings or generated by service

success case (read-only query)

• http status: 2xx
• response body: json object with requestId, columns (array of field names), rows (array of arrays, each inner array aligns with columns)
• columns array preserves order: custom fields first, then time, then service metadata fields
• each row is an array of values; zip with columns to reconstruct objects
• if query returns zero rows, columns is non-empty but rows is an empty array
• all timestamps in unix seconds

failure case

• http status: 4xx or 5xx
• response body: json object with errorCode, errorMessage, and requestId
• requestId is always present
• capture errorCode and errorMessage for user reporting without exposing credentials

file locations

• no local files created; all operations are remote via aliyun agentloop api
• reference documentation stored in references/ subdirectory relative to this skill (paths: dataset-management.md, data-operations.md, query-syntax.md, related-commands.md, verification-method.md, ram-policies.md)

data format

• request and response bodies: json only
• query text: raw utf-8 string (no escaping required by this skill; aliyun cli handles escaping)
• schema: json object with fields array, each field an object with name, type, optional chn, optional embedding, optional jsonKeys
• structured writes: json object with dataArray field containing non-empty array of objects
• client-token and session-id: uuid and 32 lowercase hex chars respectively (no hyphens in session-id)

outcome signal

the user knows the skill worked when

• for dataset management (create, list, get, update): the response contains the expected dataset name, region, agentspace, schema, or metadata, and the user can verify via aliyun agentloop get-dataset --agent-space <space> --dataset-name <name> or aliyun agentloop list-datasets --agent-space <space>

• for schema updates: the schema now contains the new fields without removing existing fields, and the user can verify via aliyun agentloop get-dataset showing the combined schema

• for structured writes (add-dataset-data): the response contains requestId and a row count matching the rows submitted, and the user can verify by running a read query aliyun agentloop execute-query --agent-space <space> --dataset-name <name> --query "select count(*) as cnt from <name>" to confirm row count increased

• for read-only queries (execute-query): the response contains columns and rows (possibly empty if no matches), the row count matches the query intent (e.g., limit clause), and the data values match the schema field types (text, long, double, or valid json)

• for semantic or full-text search: the response contains ranked results in the expected order with distance or similarity scores, and the user can inspect the top result to confirm relevance

• for verification failures or permission errors: the skill reports the specific api action, denied ram action, request id, and remediation steps, and the user can take action (grant permission, upgrade credentials, etc.) and retry without re-running the entire workflow

credits: original skill by clawhub; enriched to implexa standards with explicit decision points, edge cases, session tracking, and safety guardrails.