AgentLoop 数据查询 API 使用指南

3.1 CLI 准备

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

SLS 日志查询使用 get-logs-v2。正式集成前，可通过 Help 核对当前客户端支持的参数：

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

3.2 身份与密钥

可使用已有的 Aliyun CLI Profile、STS、OAuth 或 RAM Role。生产程序优先使用临时凭证或实例角色，不要在代码、文档、日志或 Git 中写入 AK/SK、SecurityToken、ContextStore API Key、Cookie 或带签名 URL。

本文示例统一使用占位符和独立变量：

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

如果使用命名 Profile，在同一次查询链路中始终携带同一个 Profile，不要中途退回默认 Profile。

3.3 Endpoint 与 API 版本

直接调用 HTTP 时需要按阿里云 ROA/POP 规则签名。不要自行拼一个没有签名的 curl；优先使用官方 SDK 或 Aliyun CLI。

3.4 最小权限

按读取对象授予 RAM Action，避免直接使用 agentloop:*：

4.1 每次先固定查询上下文

一次查询请求至少固定：

1. 地域 regionId；

2. AgentSpace；

3. 数据对象；

4. 时间范围，建议使用左闭右开 [from, to)；

5. 分页上限；

6. 是否允许读取 Prompt、Output、工具参数、记忆正文等敏感内容。

4.2 时间单位不要混用

业务时区转换应在调用方完成，并把原始 UTC/epoch 值一并保留，避免报表边界错一天。

4.3 分页有三种形态

• nextToken + maxResults：AgentSpace、Dataset、ContextStore、Evaluator、Evaluation、Pipeline 等大多数资源列表；

• offset + limit 或 page + pageSize：部分 Experiment 列表；

• offset + line 或 SQL LIMIT：SLS 查询。

  不要把第一页为空直接解释成“没有数据”。应检查时间窗口、过滤条件、nextToken、权限和数据延迟。

4.4 只投影需要的字段

Trace、Trajectory、Evaluation 和 Memory 可能包含 Prompt、模型输出、工具参数、用户标识、业务正文、文件路径或外部引用。默认只返回：

• ID 与血缘字段；

• 状态、耗时、Token 和计数；

• 内容字段的长度、哈希、是否为空；

• 经授权的脱敏摘要。

  只有在问题定位确实需要时，再读取完整正文。

4.5 统一记录请求证据

每次 API 查询至少记录：

• Region、AgentSpace、对象类型；

• API Action 或 SLS Project/Logstore；

• 查询窗口与过滤条件的脱敏版本；

• requestId；

• 分页位置；

• 返回条数、是否截断、是否完整；

• 客户端版本和查询时间。

5.1 列出 AgentSpace

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

如果响应包含 nextToken，继续传入：

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

5.2 获取一个 AgentSpace

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

重点读取：

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

建议一次读取并保存本次查询链路所需的资源定位信息：

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')

其中：

• cmsWorkspace 用来继续定位原始 Trace 所在的 XTrace Project 和 Logstore；

• slsProject 是当前 AgentSpace 的 AgentLoop 数据 Project，Trajectory、评估和实验明细从这里查询；

• regionId 是后续 CMS/SLS 查询默认使用的地域。

  完成标志：CMS_WORKSPACE、AGENTSPACE_SLS_PROJECT 和 RESOURCE_REGION 均非空，且返回的 agentSpace 与目标空间一致。不要根据 AgentSpace 名称猜测 Project 或 Workspace。

6.1 从 AgentSpace 定位 XTrace Store

原始 Trace 的 Project 不应从 AgentSpace 名称或 slsProject 推断。完整定位链路是：

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

先取最近 24 小时的 Unix 秒时间窗口：

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

再查询 Workspace 中标识为 apm.trace_set.storage 的 SLS Logstore 实体：

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")

响应通过 header 描述列顺序，通过 data 返回二维数据。例如：

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

按 header 映射出：

• TRACE_PROJECT：project_name 列；

• TRACE_LOGSTORE：logstore_name 列；

• TRACE_REGION：region 列；为空时使用 AgentSpace 的 regionId。

  下面的写法按列名动态取值，不依赖固定列序：

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}

不要把 logstore-tracing 写死为所有环境的唯一值；应以 EntityStore 实际返回的 logstore_name 为准。如果最近 24 小时查不到实体，可将定位窗口扩大到 7 天，并确认调用方拥有当前 Workspace 的 cms:GetEntityStoreData 权限。

可选地调用 GetServiceObservability 核对 APM 可观测实例状态及 entryPointInfo.project，但 Trace 查询仍应使用 EntityStore 返回的 Project 和 Logstore 组合：

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

完成标志：已经从 CMS 响应中读回非空的 TRACE_PROJECT、TRACE_LOGSTORE 和可用地域，而不是根据命名规则猜测。

6.2 验证 XTrace Store

查询前验证上一步解析出的 Project/Logstore 确实存在且可读：

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

完成标志：SLS 返回的 Project 和 Logstore 与 CMS EntityStore 定位结果一致。

6.3 按 Trace ID 查询所有 Span

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

如果一个 Trace 超过 100 个 Span，增加 offset 继续分页，直到没有新记录。不要只读取第一页就判断 Trace 完整。

常见字段包括：

• traceId、spanId、parentSpanId；

• serviceName、operationName；

• startTime、duration、statusCode；

• attributes.gen_ai.span.kind；

• attributes.gen_ai.session.id；

• attributes.gen_ai.agent.name；

• 输入、输出、模型、Token、Tool 等 gen_ai.* 属性。

  字段是否存在取决于探针、框架适配和脱敏配置。有 Trace 不代表 Tool、Skill、子 Agent 或业务结果字段一定完整。

6.4 按 Session 查询 Trace

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

如果接入端没有上报 attributes.gen_ai.session.id，平台不能仅凭时间相邻可靠地恢复 Session。不要把时间接近的两个 Trace 强行判定为同一业务任务。

6.5 Trace 完整性检查

至少验证：

• Span ID 去重后数量；

• parent-child 引用是否闭合；

• 是否存在根 Span；

• 输入和输出字段是否按策略采集；

• Tool/LLM/Agent Span 是否与实际调用一致；

• 查询窗口是否覆盖延迟到达的 Span；

• 是否读取完所有分页。

  完成标志：可以从一个明确的 traceId 读回所有可见 Span，并能区分“确实没有某类调用”和“埋点/字段缺失”。

7.1 数据位置

Trajectory 的 Project 直接来自 GetAgentSpace 响应中的 slsProject，Logstore 为 agent-trajectory：

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

按第 5.2 节得到 AGENTSPACE_SLS_PROJECT 后，先验证 Logstore 可读：

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

这里的 slsProject 与原始 Trace 的 XTrace Project 是两套定位信息，不能互相替代：

完成标志：GetAgentSpace.slsProject 非空，且 GetLogStore 成功返回 agent-trajectory 的信息。

如果 slsProject 为空，或 GetLogStore 返回资源不存在，应先确认当前 AgentSpace 已产生 Agent 轨迹且调用方拥有读取权限；不要改用 XTrace Project 代替。

7.2 查询列表

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 按不同标识查询

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

# 从原始 Trace 追到 Trajectory
--query 'trace_id:"<trace-id>"'

# 查询一个 Session 的轨迹
--query 'session_id:"<session-id>"'

# 查询某个 Agent 应用
--query 'service_names:"<service-name>"'

# 查询包含某工具的轨迹
--query 'tool_names:"<tool-name>"'

# 限制步骤数与耗时
--query 'step_count >= 10 AND duration_ms >= 5000'

Trajectory 的常见查询字段包括：

• 血缘：trajectory_id、previous_trajectory_ref、trace_id、terminal_span_id、session_id、turn_id；

• 时间与规模：start_time、end_time、duration_ms、step_count；

• 模型与 Token：models、model_call_count、total_tokens、input_tokens、output_tokens、cached_tokens；

• 工具与 Skill：tool_names、tool_call_count、tool_errors、skill_ids、skill_names、skill_call_count；

• Agent：agent_name、agent_version、subagent_trajectory_ids、sub_agent_count；

• 内容：input、output、atif_content、model_calls、tool_calls、skills；

• 数据质量：degraded、degraded_reason、input_empty_reason、version。

  字段可能随清洗版本变化。消费端应允许新增字段，并根据 version 或 cleaning_version 做兼容，而不是假定固定列序。

7.4 内容与 ATIF

atif_content 可能很大。列表页不应读取或展示完整 ATIF；详情查询才按 trajectory_id 拉取完整内容。对于异常大的 input/output，建议只返回前若干字符，并显式标记 truncated=true，不要静默截断。

完成标志：能按 trajectory_id 或 trace_id 读到有序行为数据，并明确数据是否降级、内容是否截断、清洗版本是什么。

8.1 列出 Dataset

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

可用 --dataset-name 精确过滤；有 nextToken 时继续翻页。

8.2 查询 Dataset Schema

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

先读 Schema，再生成查询。公共字段类型包括 text、long、double、json。系统字段常见为 id、__time__ 和内部序列字段；客户端不要依赖内部序列字段。

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'

查询规则：

• 只使用单 Dataset SELECT；

• 不使用 JOIN、UNION、INTERSECT、EXCEPT 或子查询；

• 显式列出字段和 LIMIT；

• 不把用户输入直接拼入 SQL；

• SELECT 不写 LIMIT 时，服务默认最多返回 1,000 行；单次查询上限以目标地域的接口文档和实际响应为准。

8.4 时间窗口、分页与截断

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 发生截断时，检查响应的 meta.truncation，不能把截断后的文本当作完整样本。

8.5 SearchExpr

# 关键词、数值与布尔条件
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 支持比较、AND/OR/NOT、括号、field:value、field:* 和前缀匹配。不要在 SearchExpr 一侧使用 IN、BETWEEN、LIKE、IS NULL、任意函数或 JSON Filter DSL。

8.6 语义检索

目标字段必须在 Dataset Schema 中启用 embedding。

# 距离阈值，值越小通常越相近
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 距离排序
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 响应不是对象数组

ExecuteQuery 的返回格式是列与二维行分离：

{
  "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>"
}

调用方必须使用 columns[j] 解释 rows[i][j]。

完成标志：Schema 与查询字段一致，meta.progress 表示完成，分页全部读取，截断状态已处理，并且关键血缘字段不为空。

9.1 统一对象：ContextStore

当前 AgentLoop API 用 ContextStore 统一表示上下文库：

• contextType=memory：记忆库；

• contextType=experience：经验库。

  两者可以使用同一组 List/Get/Search API，但业务含义、身份隔离和内容来源不同。

9.2 列出上下文库

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

# 只列记忆库
aliyun agentloop list-context-stores \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --context-type memory \
  --max-results 100

# 只列经验库
aliyun agentloop list-context-stores \
  --profile "$AL_PROFILE" \
  --region "$AL_REGION" \
  --agent-space "$AL_AGENT_SPACE" \
  --context-type experience \
  --max-results 100

响应重点关注 contextStoreName、contextType、status、serviceNames、createTime、updateTime 和 nextToken。

9.3 获取上下文库配置

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

经验库常见配置包括 source.agentSpace、source.startTime、serviceNames、metadataField 和 miningInterval。状态为 Active/Running 只代表资源或挖掘任务状态，不证明已有可召回内容。

对于 contextType=memory，如果响应包含 config.innerSource，它会直接给出该记忆库的事件源位置：

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

这个 Logstore 保存通过 Context API 写入、等待抽取的短期事件；长期记忆结果仍通过 SearchContext 或对应 Dataset 查询。事件 Project 与 AgentSpace 的 slsProject 一致，名称规则为 memory_events_ 加 MD5(agentSpace + "|" + contextStoreName) 的 32 位小写十六进制值。优先使用 API 返回的 innerSource；如果当前 SDK 只解析了通用配置，可按同一规则计算后再用 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 的来源由 config.source.agentSpace 和 serviceNames 描述，经验挖掘读取该 AgentSpace 的 Trajectory，不使用同名的 memory_events_* Logstore。

9.4 搜索记忆或经验

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

身份过滤的字段名取决于 ContextStore 的元数据映射。调用前应通过 GetContextStore 和产品约定确认字段，不要假定每个库都使用 userId。

安全要求：

• 记忆查询必须带足够的租户/用户/Agent/应用/Run 隔离条件；

• 经验查询应带服务、场景或其他适用边界；

• threshold 和 limit 需要用真实测试集校准；

• HTTP 200 + 空 results 表示请求可达但无匹配内容，不等于服务故障；

• Search 成功不代表召回已注入 Agent，更不代表质量改善。

9.5 按 ID、全量导出与审计历史

ContextStore 的常用读取路径是 List/Get/Search。如果业务需要确定性全量导出、按 ID 遍历或审计历史，优先选择以下之一：

1. 使用正式开放的 Dataset 物化/导出方案；

2. 使用所在地域明确开放的专用 ContextStore API；

3. 对既有旧版 MemoryStore 使用下一节的 CMS 兼容接口。

10.1 查询顺序

先查询 Evaluator、Evaluation Task 和 Evaluation Run 的配置与状态，再到 AgentSpace 的 SLS Project 查询逐样本明细。控制面状态与结果明细必须分别核对。

10.2 查询评估器

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>'

查询结果应保留评估器版本。任务创建时通常会冻结配置快照，当前最新评估器不一定等于历史 Run 实际使用的版本。

10.3 查询评估任务和 Run

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>'

Task/Run 控制面回答“配置是什么、执行到哪一步”，不一定返回逐样本完整评分明细。

10.4 查询评估明细

评估明细位于 AgentSpace slsProject 的 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

常见字段：

• task_id、run_id、eval_id；

• evaluator_name、evaluator_display_name；

• status；

• score_name、score_value、score_range、normalized_score_value；

• explanation、evaluation_process；

• eval_info；

• data_link；

• eval_metrics、custom_outputs、eval_latency。

  低分查询示例：

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

默认不要导出 eval_info、完整 evaluation_process 或 custom_outputs 正文。只有在得到数据授权、确实需要定位单个 Case 时才读取。

完成标志：Task 和 Run 状态可读；评估明细条数与预期样本/评估器组合可以解释；失败、不可评和成功评分分开统计；低分 Case 能回到 data_link 指向的 Trace 或 Dataset Item。

10.5 查询 Playground 运行明细

Playground 的单次运行和评估结果写入 AgentSpace slsProject 的 playground_detail。它与正式评估任务的 evaluation_detail 分开，适合回查交互式调试记录：

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 记录可能包含输入、输出、模型参数和评分等敏感内容。列表查询应先读取 ID、状态、模型和时间字段，只有在定位单次运行时才读取完整内容。

11.1 查询实验计划

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 查询实验记录

CLI 中的 run 表示一次实验记录：

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>'

实验记录常见字段包括 recordId、planId、status、任务总数/完成数/失败数、progress、executedAt、completedAt、datasetId、experimentConfig、evaluationTaskId 和错误信息。

11.3 查询逐样本实验输出

逐样本实验输出位于 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

常见字段：

• experiment_id；

• experiment_metadata.experiment_group_name；

• data_config.dataset_id；

• data_config.dataset_item_id；

• experiment_output；

• experiment_metrics；

• status。

  实验评分仍在 evaluation_detail，通过以下字段关联：

• data_link.experiment_id；

• data_link.experiment_group_name；

• data_link.dataset_id；

• data_link.dataset_item_id。

  完成标志：Baseline 和 Candidate 使用同一 Dataset Item 集合、同一评估器版本与同一环境口径；逐样本输出和逐样本评分均可追溯。只比较聚合均值不足以证明改动有效。

12.1 列出和获取定义

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 重点查看 source、顺序 nodes、sink、执行策略和最后运行信息。当前公开契约的核心形态是“一份数据源 → 顺序处理节点 → Dataset Sink”；不要把它描述成任意 DAG、多源 Join 或多 Sink 平台。

12.2 查询 Run

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>'

Run 详情重点查看：

• status；

• 数据窗口；

• triggerType；

• attempt/maxAttempts；

• startTime/finishTime；

• stats；

• errorCode/errorMessage；

• 可选的 inline results。

12.3 查询统计

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 必须回查 Dataset

Run Succeeded 后仍要查询目标 Dataset，至少核对：

• 源选择范围与目标行数；

• trace_id/trajectory_id/session_id 等血缘字段；

• 必填字段为空的比例；

• 重复 ID；

• 转换字段；

• 截断；

• 被过滤数据是否可解释。

  完成标志：目标 Dataset 的真实行已读回并满足字段契约，而不是只看到 Pipeline 状态成功。

13.1 Dataset 标注

execute-query 支持 --annotation-filter，可按标注条件筛选 Dataset 数据。标注条件的字段、操作符和值应与 Dataset 的标注配置一致。

自动评分与人工标注必须分字段保存，不能覆盖后把机器结论当成人工金标。

13.2 Prompt 和运行时 Skill

Prompt 和运行时 Skill 属于 Agent 资产域；Evaluator Skill 属于评估域，两者不是同一种资源。查询 Prompt 或运行时 Skill 时，应使用 Agent 资产 API 文档中对应的版本、发布状态和 Label 条件，不能用 Evaluator Skill 查询替代。

13.3 Token、成本与质量指标

Token、模型时延和工具调用可从 Trace 或 Trajectory 字段聚合；评估质量从 evaluation_detail 聚合。两者来自不同证据面，聚合时要明确时间窗口、去重单位和分母：

• Trace 指标通常按 traceId 去重；

• Session 指标按 Session ID；

• Trajectory 指标按 trajectory_id；

• Dataset 指标按 Dataset Item id；

• Evaluation 指标按 eval_id，同时按 evaluator 拆分；

• Experiment 指标按 experiment_id + group + dataset_item_id。

14.1 从一个 Trace 找到 Trajectory 和 Dataset 样本

1. 在 CMS EntityStore 定位出的 TRACE_PROJECT/TRACE_LOGSTORE 中按 traceId 读取完整 Span。

2. 在 agent-trajectory 按 trace_id 查询 Trajectory。

3. 记录 trajectory_id、session_id 和清洗版本。

4. 在目标 Dataset 中查询显式保存的 trace_id 或 trajectory_id。

5. 如果 Dataset Schema 没有血缘字段，不能靠时间接近做确定性关联。

   Dataset 示例：

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

14.2 从 Dataset Item 找到评估结果

1. 从 Dataset 获取 Item id。

2. 在 evaluation_detail 查询 data_link.dataset_item_id。

3. 同时限定 task_id 或 run_id，避免匹配历史复跑。

4. 按 evaluator 分开解释分数，不把不同指标直接平均成“总质量”。

14.3 从实验记录核对 Baseline 与 Candidate

1. 通过 GetExperimentRun 获取 recordId、Dataset、配置组和关联评估任务。

2. 在 experiment_detail 按 experiment_id 获取每个 Dataset Item 的输出。

3. 在 evaluation_detail 按 data_link.experiment_id 获取评分。

4. 用 dataset_item_id + experiment_group_name 对齐结果。

5. 检查是否存在缺失输出、重复样本、失败或不可评记录。

14.4 从经验召回结果回到来源轨迹

经验结果只有在元数据中保留 sourceTraceId、trace_id、trajectory_id 或等价字段时才能确定性回溯。字段名取决于 ContextStore 配置。

如果没有来源标识，只能说“召回到一条经验”，不能声称它来自某个具体 Trace。

18.1 AgentLoop 查询接口

18.2 Trace 与 Trajectory 数据定位接口

18.3 评估与实验查询命令

调用前应确认目标账号拥有相应 RAM 读取权限，并使用目标地域支持的 AgentLoop API 版本。

19.1 先枚举 AgentSpace 中实际存在的 Logstore

固定名称表示数据合同固定，不表示每个 AgentSpace 创建后立即拥有全部 Logstore。许多 Logstore 会在启用相应接入、审计、评估、实验、记忆或效率分析能力后创建。应先使用 GetAgentSpace.slsProject 枚举实际资源：

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

如果返回数量达到 500，继续增加 offset，直到读取完整。对准备查询的每个 Logstore，再验证资源和索引：

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 证明资源存在，GetIndex 证明哪些字段可以做关键词、范围或 SQL 查询；两者都不能证明目标时间窗口内已有数据。

19.2 Trajectory 与轨迹特征 Logstore

这些 Logstore 的 Project 均来自 GetAgentSpace.slsProject：

查询轨迹特征时，优先用 trajectory_id 或 feature_id 关联四个视图。trajectory-feature-event 是轨迹派生事件，不等于应用直接上报的 agent-event。

19.3 Agent 原始事件与审计 Logstore

这组 Logstore 也位于 AgentSpace 的 slsProject。原始事件由接入链路写入；派生审计数据在启用相应审计能力并产生结果后出现。

跨 agent-event 与 agent-event-webtracking 查询时，应显式投影相同字段并增加来源列，再使用 UNION ALL；不要假定两个 Logstore 在每个时间段都有数据。ebpf-event 属于运行时数据范围，不应与 AI 应用事件在没有关联键时直接拼接。

19.4 评估、实验与 Playground Logstore

experiment_detail 保存实验输出，实验评分仍在 evaluation_detail。playground_detail 用于交互调试，不应当作正式 Evaluation Task/Run 的结果来源。

19.5 Token 与成本效率 Logstore

启用 Token/成本效率分析后，AgentSpace Project 中可能出现以下 Logstore：

读取效率数据时，先用 mining-catalog 确认已发布的 Run 和窗口，再读取 Feature、Fragment 或 Serving 数据。不要仅凭某个 Logstore 有行就认定该窗口已完成发布。

19.6 动态名称或由资源配置决定的 Logstore

Experience ContextStore 没有一个必须与库同名的 Event Logstore。它通过 config.source.agentSpace 和 serviceNames 选择来源，主要从该 AgentSpace 的 agent-trajectory 读取轨迹，召回结果通过 ContextStore API 查询。

19.7 几类“Event”不要混淆

还要区分 agent-trajectory 与服务运行日志中的 agentloop-trajectory：前者是客户 AgentSpace 内的业务 Trajectory，后者是 Trajectory 服务自身的运行日志。名称相似，但 Project、Schema、权限和用途都不同。

19.8 流程控制、计量与服务运行 Logstore

AgentLoop 的任务执行还会使用流程控制或服务观测 Logstore。常见类别包括：

流程控制或服务运行 Logstore 的名称、Project 和保留期可能随地域及部署环境变化。它们能解释任务为什么等待或失败，但不能替代客户数据面的 Trace、Trajectory、Dataset、Evaluation、Experiment 或 Context 查询结果。

19.9 通用 Logstore 查询模板

确认 Project、Logstore、索引和时间范围后，再执行有界查询：

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

第一次查询未知 Schema 时，先读取少量记录并结合 GetIndex 确认字段，再编写正式过滤和 SQL。查询完成必须记录 Project、Logstore、时间窗口、过滤条件、分页、完整性标记和 requestId。