AgentLoop Data Query API Usage Guide

3.1 Prepare the CLI

aliyun version
aliyun plugin show --name agentloop
aliyun plugin show --name aliyun-cli-sls
aliyun configure list
jq --version

SLS log queries use get-logs-v2. Before you integrate formally, use Help to check the parameters that your current client supports:

aliyun agentloop <command> --help
aliyun sls get-logs-v2 --help

3.2 Identity and credentials

You can use an existing Aliyun CLI profile, STS, OAuth, or a RAM role. For production programs, prefer temporary credentials or an instance role. Do not write AK/SK pairs, SecurityToken values, ContextStore API keys, cookies, or signed URLs into code, documentation, logs, or Git.

The examples in this topic consistently use placeholders and separate variables:

AL_REGION='<region-id>'
AL_AGENT_SPACE='<agent-space-name>'
AL_PROFILE='<aliyun-cli-profile>'

If you use a named profile, carry the same profile through the entire query chain. Do not fall back to the default profile partway through.

3.3 Endpoints and API versions

Direct HTTP calls must be signed according to the Alibaba Cloud ROA/POP rules. Do not assemble an unsigned curl command. Prefer the official SDK or Aliyun CLI.

3.4 Least privilege

Grant RAM actions based on the object that you read, and avoid using agentloop:* directly:

4.1 Fix the query context before every query

Each query request must fix at least the following:

1. The region regionId.

2. The AgentSpace.

3. The data object.

4. The time range, preferably the half-open interval [from, to).

5. The pagination limit.

6. Whether reading sensitive content is allowed, such as prompts, outputs, tool parameters, and memory bodies.

4.2 Do not mix time units

Perform business time zone conversion on the caller side, and keep the original UTC and epoch values so that report boundaries are not off by one day.

4.3 Pagination has three forms

• nextToken + maxResults: most resource lists, such as AgentSpace, Dataset, ContextStore, Evaluator, Evaluation, and Pipeline;

• offset + limit or page + pageSize: some Experiment lists;

• offset + line or the SQL LIMIT: SLS queries.

  Do not interpret an empty first page as "no data". Check the time window, the filter conditions, nextToken, permissions, and data latency.

4.4 Project only the fields you need

Traces, Trajectories, Evaluations, and Memory can contain prompts, model outputs, tool parameters, user identifiers, business content, file paths, or external references. By default, return only:

• IDs and lineage fields;

• status, duration, tokens, and counts;

• the length, hash, and emptiness of content fields;

• authorized and redacted summaries.

  Read the full content only when troubleshooting genuinely requires it.

4.5 Record request evidence consistently

For every API query, record at least the following:

• The region, AgentSpace, and object type;

• The API action or the SLS Project and Logstore;

• A redacted version of the query window and filter conditions;

• requestId;

• The pagination position;

• The number of returned entries, whether the result is truncated, and whether it is complete;

• The client version and the query time.

5.1 List AgentSpaces

aliyun agentloop list-agent-spaces \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --max-results 100

If the response contains nextToken, pass it in the next request:

aliyun agentloop list-agent-spaces \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --max-results 100 \
  --next-token '<next-token>'

5.2 Get an AgentSpace

aliyun agentloop get-agent-space \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE"

Key fields to read:

{
  "agentSpace": "<agent-space>",
  "regionId": "<region-id>",
  "cmsWorkspace": "<cms-workspace>",
  "slsProject": "<agentloop-sls-project>",
  "requestId": "<request-id>"
}

Read and save the resource locators required by this query chain in one step:

AGENT_SPACE_JSON=$(aliyun agentloop get-agent-space \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE")

CMS_WORKSPACE=$(printf '%s\n' "$AGENT_SPACE_JSON" | jq -r '.cmsWorkspace // empty')
AGENTSPACE_SLS_PROJECT=$(printf '%s\n' "$AGENT_SPACE_JSON" | jq -r '.slsProject // empty')
RESOURCE_REGION=$(printf '%s\n' "$AGENT_SPACE_JSON" | jq -r '.regionId // empty')

Where:

• cmsWorkspace is used to further locate the XTrace Project and Logstore where the raw Traces are stored;

• slsProject is the AgentLoop data Project of the current AgentSpace. Query Trajectory, evaluation, and experiment details from this Project;

• regionId is the region used by default for subsequent CMS and SLS queries.

  Completion criteria: CMS_WORKSPACE, AGENTSPACE_SLS_PROJECT, and RESOURCE_REGION are all non-empty, and the returned agentSpace matches the target space. Do not guess the Project or Workspace from the AgentSpace name.

6.1 Locate the XTrace Store from AgentSpace

Do not infer the Project of the raw Traces from the AgentSpace name or slsProject. The complete lookup chain is:

AgentSpace
  └─ GetAgentSpace → cmsWorkspace
       └─ CMS GetEntityStoreData → XTrace project + logstore + region
            └─ SLS GetLogsV2 → Trace / Span

First, get a Unix-seconds time window for the last 24 hours:

LOOKUP_TO=$(date +%s)
LOOKUP_FROM=$((LOOKUP_TO - 86400))

Then query the SLS Logstore entities in the Workspace marked apm.trace_set.storage:

TRACE_STORE_JSON=$(aliyun cms get-entity-store-data \
  --api-version 2024-03-30 \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --workspace "$CMS_WORKSPACE" \
  --from "$LOOKUP_FROM" \
  --to "$LOOKUP_TO" \
  --query ".umodel
| where kind = 'sls_logstore'
  and json_extract_scalar(metadata, '$.domain') = 'apm'
  and json_extract_scalar(metadata, '$.name') = 'apm.trace_set.storage'
| extend project_name = json_extract_scalar(spec, '$.project'),
         logstore_name = json_extract_scalar(spec, '$.store'),
         region = json_extract_scalar(spec, '$.region')
| project project_name, logstore_name, region")

The response uses header to describe the column order and data to return two-dimensional data. For example:

{
  "header": ["project_name", "logstore_name", "region"],
  "data": [
    ["<xtrace-project>", "<trace-logstore>", "<trace-region>"]
  ],
  "requestId": "<request-id>"
}

Map the following fields by header:

• TRACE_PROJECT: the project_name column;

• TRACE_LOGSTORE: the logstore_name column;

• TRACE_REGION: the region column; if it is empty, use the AgentSpace regionId.

  The following approach reads values dynamically by column name and does not depend on a fixed column order:

TRACE_PROJECT=$(printf '%s\n' "$TRACE_STORE_JSON" | jq -r '
  (.header | index("project_name")) as $i
| if $i == null then empty else (.data[0][$i] // empty) end')

TRACE_LOGSTORE=$(printf '%s\n' "$TRACE_STORE_JSON" | jq -r '
  (.header | index("logstore_name")) as $i
| if $i == null then empty else (.data[0][$i] // empty) end')

TRACE_REGION=$(printf '%s\n' "$TRACE_STORE_JSON" | jq -r '
  (.header | index("region")) as $i
| if $i == null then empty else (.data[0][$i] // empty) end')

TRACE_REGION=${TRACE_REGION:-$RESOURCE_REGION}

Do not hardcode logstore-tracing as the only value for all environments. Use the logstore_name that EntityStore actually returns. If no entity is found in the last 24 hours, extend the lookup window to 7 days and confirm that the caller has the cms:GetEntityStoreData permission on the current Workspace.

Optionally, call GetServiceObservability to verify the APM observability instance status and entryPointInfo.project, but Trace queries must still use the Project and Logstore combination returned by EntityStore:

aliyun cms get-service-observability \
  --api-version 2024-03-30 \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --workspace "$CMS_WORKSPACE" \
  --type apm

Completion criteria: the values read back from the CMS response are a non-empty TRACE_PROJECT, TRACE_LOGSTORE, and an available region, rather than values guessed from naming conventions.

6.2 Verify the XTrace Store

Before you query, verify that the Project and Logstore resolved in the previous step exist and are readable:

aliyun sls get-log-store \
  --profile "$AL_PROFILE" \
  --region "$TRACE_REGION" \
  --project "$TRACE_PROJECT" \
  --logstore "$TRACE_LOGSTORE"

Completion criteria: the Project and Logstore returned by SLS match the CMS EntityStore lookup result.

6.3 Query all Spans by Trace ID

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$TRACE_REGION" \
  --project "$TRACE_PROJECT" \
  --logstore "$TRACE_LOGSTORE" \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query 'traceId:"<trace-id>"' \
  --line 100 \
  --offset 0 \
  --reverse false

If a Trace has more than 100 Spans, increase offset and continue paginating until no new records are returned. Do not judge a Trace to be complete after reading only the first page.

Common fields include:

• traceId, spanId, and parentSpanId.

• serviceName and operationName.

• startTime, duration, and statusCode.

• attributes.gen_ai.span.kind.

• attributes.gen_ai.session.id.

• attributes.gen_ai.agent.name.

• The gen_ai.* attributes for input, output, model, tokens, tools, and so on.

  Whether a field exists depends on the probe, the framework adaptation, and the redaction configuration. The presence of a Trace does not guarantee that the Tool, Skill, sub-Agent, or business result fields are complete.

6.4 Query Traces by Session

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$TRACE_REGION" \
  --project "$TRACE_PROJECT" \
  --logstore "$TRACE_LOGSTORE" \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query 'attributes.gen_ai.session.id:"<session-id>"' \
  --line 100 \
  --offset 0

If the integration does not report attributes.gen_ai.session.id, the platform cannot reliably reconstruct a Session from time proximity alone. Do not force two Traces that are close in time into the same business task.

6.5 Verify Trace completeness

Verify at least the following:

• The number of Span IDs after deduplication;

• Whether parent-child references are closed;

• Whether a root Span exists;

• Whether the input and output fields are collected according to policy;

• Whether the Tool, LLM, and Agent Spans match the actual calls;

• Whether the query window covers Spans that arrive late;

• Whether all pages have been read.

  Completion criteria: you can read back all visible Spans from an explicit traceId and can distinguish between "a certain type of call genuinely did not occur" and "missing instrumentation or fields".

7.1 Data location

The Trajectory Project comes directly from the GetAgentSpace response field slsProject, and the Logstore is agent-trajectory:

AgentSpace
  └─ GetAgentSpace → slsProject
       └─ SLS Project / agent-trajectory

After you obtain AGENTSPACE_SLS_PROJECT as described in section 5.2, verify that the Logstore is readable:

aliyun sls get-log-store \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore 'agent-trajectory'

The slsProject here and the XTrace Project of the raw Traces are two separate sets of locators and cannot replace each other:

Completion criteria: GetAgentSpace.slsProject is not empty, and GetLogStore successfully returns information about agent-trajectory.

If slsProject is empty, or GetLogStore returns that the resource does not exist, first confirm that the current AgentSpace has produced Agent trajectories and that the caller has read permissions. Do not substitute the XTrace Project.

7.2 Query a list

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore 'agent-trajectory' \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query '*' \
  --line 100 \
  --offset 0 \
  --reverse true

7.3 Query by different identifiers

# By Trajectory ID
--query 'trajectory_id:"<trajectory-id>"'

# Follow a raw Trace to Trajectory
--query 'trace_id:"<trace-id>"'

# Query trajectories for one Session
--query 'session_id:"<session-id>"'

# Query an Agent application
--query 'service_names:"<service-name>"'

# Query trajectories that include a tool
--query 'tool_names:"<tool-name>"'

# Restrict step count and duration
--query 'step_count >= 10 AND duration_ms >= 5000'

Common query fields for a Trajectory include:

• Lineage: trajectory_id, previous_trajectory_ref, trace_id, terminal_span_id, session_id, and turn_id.

• Time and scale: start_time, end_time, duration_ms, and step_count.

• Model and tokens: models, model_call_count, total_tokens, input_tokens, output_tokens, and cached_tokens.

• Tools and Skills: tool_names, tool_call_count, tool_errors, skill_ids, skill_names, and skill_call_count.

• Agent: agent_name, agent_version, subagent_trajectory_ids, and sub_agent_count.

• Content: input, output, atif_content, model_calls, tool_calls, and skills.

• Data quality: degraded, degraded_reason, input_empty_reason, and version.

  Fields can change with the cleaning version. Consumers should allow new fields and handle compatibility based on version or cleaning_version, instead of assuming a fixed column order.

7.4 Content and ATIF

atif_content can be very large. A list page should not read or display the complete ATIF. Pull the full content only in a detail query, by trajectory_id. For an exceptionally large input/output, return only the first few characters and explicitly mark truncated=true. Do not truncate silently.

Completion criteria: you can read ordered behavior data by trajectory_id or trace_id, and you can determine whether the data is degraded, whether the content is truncated, and what the cleaning version is.

8.1 List Datasets

aliyun agentloop list-datasets \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --max-results 100

You can use --dataset-name to filter precisely. If nextToken is returned, continue paginating.

8.2 Query a Dataset schema

aliyun agentloop get-dataset \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>'

Read the schema first, and then generate the query. Common field types include text, long, double, and json. System fields are commonly id, __time__, and internal sequence fields. Clients must not depend on internal sequence fields.

8.3 SQL SELECT

aliyun agentloop execute-query \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>' \
  --type SQL \
  --query 'SELECT id, __time__, question, answer, trace_id FROM <dataset-name> ORDER BY __time__ DESC LIMIT 100'

Query rules:

• Use only single-Dataset SELECT.

• Do not use JOIN, UNION, INTERSECT, EXCEPT, or subqueries.

• Explicitly list the fields and LIMIT.

• Do not concatenate user input directly into SQL.

• SELECT without LIMIT returns at most 1,000 rows by default. The per-query limit is subject to the API reference of the target region and the actual response.

8.4 Time windows, pagination, and truncation

aliyun agentloop execute-query \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>' \
  --type SQL \
  --query 'SELECT id, question, answer FROM <dataset-name> ORDER BY __time__ DESC' \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --offset 0 \
  --length 100 \
  --max-output-length 4096

maxOutputLength: when truncation occurs, check the response field meta.truncation. Do not treat truncated text as a complete sample.

8.5 SearchExpr

# Keywords, numeric conditions, and Boolean conditions
aliyun agentloop execute-query \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>' \
  --type SQL \
  --query 'question:"timeout" AND score >= 0.8'

SearchExpr supports comparison, AND/OR/NOT, parentheses, field:value, field:*, and prefix matching. Do not use IN, BETWEEN, LIKE, IS NULL, arbitrary functions, or JSON Filter DSL on the SearchExpr side.

8.6 Semantic search

The target field must have embedding enabled in the Dataset schema.

# Distance threshold. A smaller value usually indicates greater similarity
aliyun agentloop execute-query \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>' \
  --type SQL \
  --query 'similarity(question, "<semantic-query>") < 0.3'

# Top-K
aliyun agentloop execute-query \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>' \
  --type SQL \
  --query 'topk(question, "<semantic-query>") <= 10'

# SQL distance ordering
aliyun agentloop execute-query \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --dataset-name '<dataset-name>' \
  --type SQL \
  --query 'SELECT id, question, semantic_distance(question, "<semantic-query>", "l2") AS distance FROM <dataset-name> ORDER BY distance ASC LIMIT 10'

8.7 The response is not an object array

ExecuteQuery returns columns and two-dimensional rows separately:

{
  "columns": ["id", "question", "score"],
  "columnTypes": ["text", "text", "double"],
  "rows": [
    ["<id-1>", "<question-1>", 0.95],
    ["<id-2>", "<question-2>", 0.91]
  ],
  "meta": {
    "progress": "Complete",
    "count": 2,
    "truncation": {"truncated": false}
  },
  "requestId": "<request-id>"
}

The caller must use columns[j] to interpret rows[i][j].

Completion criteria: the schema matches the query fields, meta.progress indicates completion, all pages are read, the truncation state is handled, and the key lineage fields are not empty.

9.1 Unified object: ContextStore

The current AgentLoop API uses ContextStore to represent context stores in a unified way:

• contextType=memory: a memory store;

• contextType=experience: an experience store.

  Both can use the same set of List, Get, and Search APIs, but they differ in business meaning, identity isolation, and content source.

9.2 List context stores

# All ContextStore
aliyun agentloop list-context-stores \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --max-results 100

# Memory stores only
aliyun agentloop list-context-stores \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --context-type memory \
  --max-results 100

# Experience stores only
aliyun agentloop list-context-stores \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --context-type experience \
  --max-results 100

In the response, focus on contextStoreName, contextType, status, serviceNames, createTime, updateTime, and nextToken.

9.3 Get a context store configuration

aliyun agentloop get-context-store \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --context-store-name '<context-store-name>'

Common configuration items for an experience store include source.agentSpace, source.startTime, serviceNames, metadataField, and miningInterval. A status of Active or Running only reflects the state of the resource or the mining task. It does not prove that recallable content already exists.

For contextType=memory, if the response contains config.innerSource, it directly gives the event source location of that memory store:

{
  "contextType": "memory",
  "config": {
    "innerSource": {
      "project": "<agent-space-sls-project>",
      "logstore": "memory_events_<32-character-hash>"
    }
  }
}

This Logstore stores short-term events that were written through the Context API and are waiting to be extracted. Long-term memory results are still queried through SearchContext or the corresponding Dataset. The event Project matches the AgentSpace slsProject, and the naming rule is memory_events_ plus MD5(agentSpace + "|" + contextStoreName) as a 32-character lowercase hexadecimal value. Prefer the innerSource returned by the API. If the current SDK parses only general configurations, compute the value by the same rule and verify it with GetLogStore:

AL_CONTEXT_STORE='<context-store-name>'
MEMORY_EVENT_HASH=$(printf '%s' "$AL_AGENT_SPACE|$AL_CONTEXT_STORE" \
| openssl dgst -md5 -r \
| awk '{print $1}')
MEMORY_EVENT_LOGSTORE="memory_events_${MEMORY_EVENT_HASH}"

contextType=experience sources are described by config.source.agentSpace and serviceNames. Experience mining reads the Trajectories of that AgentSpace and does not use the identically named memory_events_* Logstore.

9.4 Search memory or experience

aliyun agentloop search-context \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --context-store-name '<context-store-name>' \
  --query '<natural-language-query>' \
  --filter '{"userId":"<user-id>","agentId":"<agent-id>"}' \
  --formatted true \
  --limit 10 \
  --threshold 0.6

The field names used for identity filtering depend on the metadata mapping of the ContextStore. Before you call, confirm the fields through GetContextStore and the product agreement. Do not assume that every store uses userId.

Security requirements:

• A memory query must carry sufficient tenant, user, Agent, application, and Run isolation conditions;

• An experience query should carry the service, scenario, or other applicable boundaries;

• threshold and limit must be calibrated with a real test set;

• HTTP 200 with an empty results means that the request reached the service but no content matched. It does not indicate a service failure;

• A successful Search does not mean that the recalled content has been injected into the Agent, and it does not mean that quality has improved.

9.5 Query by ID, full export, and audit history

The common read paths for a ContextStore are List, Get, and Search. If your business requires a deterministic full export, traversal by ID, or audit history, prefer one of the following:

1. Use the officially available Dataset materialization or export solution;

2. Use a dedicated ContextStore API that is explicitly available in your region;

3. For an existing legacy MemoryStore, use the CMS-compatible interface described in the next section.

10.1 Query order

First query the configuration and status of the Evaluator, Evaluation Task, and Evaluation Run, and then query the per-sample details in the SLS Project of the AgentSpace. Verify the control-plane status and the result details separately.

10.2 Query evaluators

aliyun agentloop list-evaluators \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --max-results 100

aliyun agentloop get-evaluator \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --name '<evaluator-name>' \
  --biz-version '<optional-version>'

Retain the evaluator version in the query results. A configuration snapshot is usually frozen when the task is created, so the latest evaluator is not necessarily the version that a historical Run actually used.

10.3 Query evaluation tasks and runs

aliyun agentloop list-evaluation-tasks \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --task-mode batch \
  --max-results 100

aliyun agentloop get-evaluation-task \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --task-id '<task-id>'

aliyun agentloop list-evaluation-runs \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --task-id '<task-id>' \
  --max-results 100

aliyun agentloop get-evaluation-run \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --task-id '<task-id>' \
  --run-id '<run-id>'

The Task and Run control plane answers what the configuration is and how far the execution has progressed. It does not necessarily return complete per-sample scoring details.

10.4 Query evaluation details

Evaluation details are located in the AgentSpace slsProject, in the Logstore evaluation_detail:

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore 'evaluation_detail' \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query 'task_id:"<task-id>" AND run_id:"<run-id>"' \
  --line 100 \
  --offset 0

Common fields:

• task_id, run_id, and eval_id.

• evaluator_name and evaluator_display_name.

• status.

• score_name, score_value, score_range, and normalized_score_value.

• explanation and evaluation_process.

• eval_info.

• data_link.

• eval_metrics, custom_outputs, and eval_latency.

  Example query for low scores:

task_id:"<task-id>" AND run_id:"<run-id>" AND status:success
| SELECT eval_id, evaluator_name, normalized_score_value, explanation
  FROM log
  WHERE normalized_score_value < 0.5
  ORDER BY normalized_score_value ASC
  LIMIT 50

By default, do not export eval_info, the complete evaluation_process, or the custom_outputs content. Read it only after you obtain data authorization and genuinely need to investigate a single case.

Completion criteria: the Task and Run statuses are readable; the number of evaluation detail entries can be explained by the expected sample and evaluator combinations; failed, non-evaluable, and successfully scored entries are counted separately; and a low-scoring case can be traced back to data_link or the Dataset Item that it points to.

10.5 Query Playground run details

A single Playground run and its evaluation results are written to the AgentSpace slsProject, in the Logstore playground_detail. It is separate from the evaluation_detail of formal evaluation tasks, and is suitable for reviewing interactive debugging records:

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore 'playground_detail' \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query '*' \
  --line 100 \
  --offset 0

Playground records can contain sensitive content such as inputs, outputs, model parameters, and scores. A list query should first read the ID, status, model, and time fields. Read the full content only when you investigate a single run.

11.1 Query experiment plans

aliyun agentloop list-experiment-plans \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --offset 0 \
  --limit 20

aliyun agentloop get-experiment-plan \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --plan-id '<plan-id>'

11.2 Query experiment records

In the CLI, run represents one experiment record:

aliyun agentloop list-experiment-runs \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --page 0 \
  --page-size 20

aliyun agentloop get-experiment-run \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --record-id '<record-id>'

Common fields of an experiment record include recordId, planId, status, the total, completed, and failed task counts, progress, executedAt, completedAt, datasetId, experimentConfig, evaluationTaskId, and error messages.

11.3 Query per-sample experiment output

Per-sample experiment output is stored in experiment_detail:

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore 'experiment_detail' \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query 'experiment_id:"<experiment-id>"' \
  --line 100 \
  --offset 0

Common fields:

• experiment_id;

• experiment_metadata.experiment_group_name;

• data_config.dataset_id;

• data_config.dataset_item_id;

• experiment_output;

• experiment_metrics;

• status.

  Experiment scores are still in evaluation_detail, and are linked through the following fields:

• data_link.experiment_id;

• data_link.experiment_group_name;

• data_link.dataset_id;

• data_link.dataset_item_id.

  Completion criteria: the Baseline and the Candidate use the same set of Dataset Items, the same evaluator version, and the same environment baseline, and both the per-sample output and the per-sample scores are traceable. Comparing only aggregate means is not enough to prove that a change is effective.

12.1 List and get definitions

aliyun agentloop list-pipelines \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --max-results 100

aliyun agentloop get-pipeline \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --pipeline-name '<pipeline-name>'

GetPipeline Focus on the source, the ordered nodes, the sink, the execution policy, and the last run information. The core shape of the current public contract is "one data source → ordered processing nodes → Dataset Sink". Do not describe it as an arbitrary DAG, a multi-source join, or a multi-sink platform.

12.2 Query runs

aliyun agentloop list-pipeline-runs \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --pipeline-name '<pipeline-name>' \
  --start-time '<inclusive-unix-seconds>' \
  --end-time '<inclusive-upper-bound-used-by-current-cli>' \
  --max-results 200

aliyun agentloop get-pipeline-run \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --pipeline-name '<pipeline-name>' \
  --run-id '<run-id>'

In the Run details, focus on the following:

• status;

• The data window;

• triggerType;

• attempt/maxAttempts;

• startTime/finishTime;

• stats;

• errorCode/errorMessage;

• Optional inline results.

12.3 Query statistics

aliyun agentloop get-pipeline-stats \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --pipeline-name '<pipeline-name>' \
  --start-time '<unix-seconds>' \
  --end-time '<unix-seconds>' \
  --granularity Day

12.4 You must query the Dataset again

After a Run reaches Succeeded, you must still query the target Dataset and verify at least the following:

• The source selection scope and the target row count;

• trace_id/trajectory_id/session_id, and other lineage fields;

• The proportion of required fields that are empty;

• Duplicate IDs;

• Converted fields;

• Truncation;

• Whether the filtered-out data can be explained.

  Completion criteria: the actual rows of the target Dataset have been read back and satisfy the field contract, rather than only showing a successful Pipeline status.

13.1 Dataset annotations

execute-query supports --annotation-filter, which lets you filter Dataset data by annotation conditions. The fields, operators, and values of the annotation conditions must match the annotation configuration of the Dataset.

Automatic scores and manual annotations must be stored in separate fields. Do not overwrite them and then treat a machine conclusion as a human gold standard.

13.2 Prompts and runtime Skills

Prompts and runtime Skills belong to the Agent asset domain, while Evaluator Skills belong to the evaluation domain. They are not the same type of resource. When you query a Prompt or a runtime Skill, use the version, release status, and Label conditions from the Agent asset API reference. An Evaluator Skill query is not a substitute.

13.3 Token, cost, and quality metrics

Tokens, model latency, and tool calls can be aggregated from Trace or Trajectory fields. Evaluation quality is aggregated from evaluation_detail. The two come from different evidence planes, so specify the time window, the deduplication unit, and the denominator when you aggregate:

• Trace metrics are usually deduplicated by traceId;

• Session metrics are deduplicated by Session ID;

• Trajectory metrics are deduplicated by trajectory_id;

• Dataset metrics are deduplicated by the Dataset Item id;

• Evaluation metrics are deduplicated by eval_id, and are also split by evaluator;

• Experiment metrics are deduplicated by experiment_id + group + dataset_item_id.

14.1 Find the Trajectory and Dataset sample from a Trace

1. In the TRACE_PROJECT/TRACE_LOGSTORE located through CMS EntityStore, read the complete Spans by traceId.

2. In agent-trajectory, query the Trajectory by trace_id.

3. Record trajectory_id, session_id, and the cleaning version.

4. In the target Dataset, query the explicitly stored trace_id or trajectory_id.

5. If the Dataset schema has no lineage fields, you cannot make a deterministic association based on time proximity.

   Dataset example:

SELECT id, trace_id, trajectory_id, session_id, question, answer
FROM <dataset-name>
WHERE trace_id = '<trace-id>'
LIMIT 100

14.2 Find evaluation results from a Dataset Item

1. Get the Item id from the Dataset.

2. In evaluation_detail, query data_link.dataset_item_id.

3. Also restrict task_id or run_id to avoid matching historical reruns.

4. Interpret the scores separately by evaluator. Do not average different metrics directly into an overall quality score.

14.3 Verify the Baseline and Candidate from experiment records

1. Use GetExperimentRun to get the recordId, the Dataset, the configuration group, and the associated evaluation task.

2. In experiment_detail, get the output of each Dataset Item by experiment_id.

3. In evaluation_detail, get the scores by data_link.experiment_id.

4. Use dataset_item_id + experiment_group_name to align the results.

5. Check for missing output, duplicate samples, and failed or non-evaluable records.

14.4 Trace an experience recall result back to its source trajectory

An experience result can be traced back deterministically only when its metadata retains sourceTraceId, trace_id, trajectory_id, or an equivalent field. The field names depend on the ContextStore configuration.

If there is no source identifier, you can only say that an experience was recalled. Do not claim that it came from a specific Trace.

18.1 AgentLoop query operations

18.2 Trace and Trajectory data location operations

18.3 Evaluation and experiment query commands

Before you call, confirm that the target account has the corresponding RAM read permissions, and use an AgentLoop API version that the target region supports.

19.1 First enumerate the Logstores that actually exist in the AgentSpace

A fixed name means that the data contract is fixed. It does not mean that every AgentSpace has all Logstores immediately after creation. Many Logstores are created after you enable the corresponding integration, auditing, evaluation, experiment, memory, or efficiency analysis capability. First use GetAgentSpace.slsProject to enumerate the actual resources:

aliyun sls list-log-stores \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --offset 0 \
  --size 500

If the number of returned entries reaches 500, keep increasing offset until you have read everything. For each Logstore that you plan to query, verify the resource and the index:

AL_LOGSTORE='<logstore-name>'

aliyun sls get-log-store \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore "$AL_LOGSTORE"

aliyun sls get-index \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project "$AGENTSPACE_SLS_PROJECT" \
  --logstore "$AL_LOGSTORE"

ListLogStores proves that the resource exists, and GetIndex proves which fields support keyword, range, or SQL queries. Neither proves that data already exists within the target time window.

19.2 Trajectory and trajectory feature Logstores

The Project for these Logstores always comes from GetAgentSpace.slsProject:

When you query trajectory features, preferentially correlate the four views by trajectory_id or feature_id. trajectory-feature-event is derived from a Trajectory; it is not the same as an application-reported agent-event.

19.3 Raw Agent event and audit Logstores

These Logstores are also in the AgentSpace slsProject. Ingestion writes raw events. Derived audit data appears after the applicable audit capability is enabled and produces results.

When you query across agent-event and agent-event-webtracking, you should explicitly project the same fields and add a source column, and then use UNION ALL; do not assume that both Logstores contain data in every time window. ebpf-event falls within the runtime data scope and should not be joined directly to AI application events without a correlation key.

19.4 Evaluation, experiment, and Playground Logstores

experiment_detail stores experiment output, while experiment scoring remains in evaluation_detail. playground_detail is used for interactive debugging and should not be treated as the result source of formal Evaluation Task/Run results.

19.5 Token, cost, and efficiency Logstores

After Token/cost efficiency analysis is enabled, the AgentSpace Project can contain the following Logstores:

When you read efficiency data, first use mining-catalog to confirm the published Runs and windows, and then read the Feature, Fragment, or Serving data. Do not conclude that a window has been published only because a Logstore has rows.

19.6 Logstores with dynamic names or names determined by resource configuration

An Experience ContextStore does not have an Event Logstore that must share the store name. It selects the source through config.source.agentSpace and serviceNames, and reads trajectories mainly from the agent-trajectory of that AgentSpace. Recall results are queried through the ContextStore API.

19.7 Do not confuse the different types of Event

Also distinguish agent-trajectory from the agentloop-trajectory in the service operational logs. The former is the business Trajectory inside the customer AgentSpace; the latter is the operational log of the Trajectory service itself. The names are similar, but the Project, schema, permissions, and purposes are all different.

19.8 Process control, metering, and service operation Logstores

AgentLoop task execution also uses process control or service observation Logstores. Common categories include:

The names, Projects, and retention periods of process control or service operation Logstores can vary by region and deployment environment. They can explain why a task is waiting or has failed, but they cannot replace the Trace, Trajectory, Dataset, Evaluation, Experiment, or Context query results of the customer data plane.

19.9 General Logstore query template

After you confirm the Project, Logstore, index, and time range, run a bounded query:

aliyun sls get-logs-v2 \
  --profile "$AL_PROFILE" \
  --region "$RESOURCE_REGION" \
  --project '<resolved-project>' \
  --logstore '<resolved-logstore>' \
  --from '<inclusive-unix-seconds>' \
  --to '<exclusive-unix-seconds>' \
  --query '<indexed-filter-or-*>' \
  --line 100 \
  --offset 0 \
  --reverse true

When you query an unknown schema for the first time, read a small number of records first and use GetIndex to confirm the fields before you write the formal filters and SQL. When a query is complete, you must record the Project, Logstore, time window, filter conditions, pagination, completeness flag, and requestId.