AgentLoop:Guía de uso de la API de consulta de datos de AgentLoop

                               ┌─────────────────────────────┐
                               │ AgentLoop API 2026-05-20    │
                               │ AgentSpace / Dataset /      │
                               │ ContextStore / Pipeline /   │
                               │ Evaluation / Experiment     │
                               └──────────────┬──────────────┘
                                              │ Control plane, structured queries
                                              ▼
Client / SDK / Aliyun CLI ───────────────── AgentLoop
          │                                   │
          │                                   ├─ Dataset ExecuteQuery
          │                                   └─ Context SearchContext
          │
          ├─ CMS API 2024-03-30 ── Locates the XTrace Store through EntityStore; compatible with legacy  Memory API
          │
          └─ SLS API 2020-12-30 ── Trace / Trajectory / Evaluation / Experiment details

3.1 Preparar la CLI

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

Las consultas de registros de SLS utilizan get-logs-v2. Antes de integrarlo formalmente, use Help para revisar los parámetros que admite su cliente actual:

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

3.2 Identidad y credenciales

Puede usar un perfil existente de Aliyun CLI, STS, OAuth o un rol de RAM. Para programas en producción, prefiera credenciales temporales o un rol de instancia. No escriba pares AK/SK, valores SecurityToken, claves de API de ContextStore, cookies ni URL firmadas en código, documentación, registros ni Git.

Los ejemplos de este tema emplean marcadores de posición y variables independientes de forma consistente:

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

Si utiliza un perfil con nombre, mantenga ese mismo perfil durante toda la cadena de consultas. No vuelva al perfil predeterminado a mitad del proceso.

3.3 Endpoints y versiones de API

Las llamadas HTTP directas deben firmarse según las reglas ROA/POP de Alibaba Cloud. No construya un comando curl sin firma. Prefiera el SDK oficial o Aliyun CLI.

3.4 Privilegio mínimo

Otorgue acciones de RAM según el objeto que lea y evite usar agentloop:* directamente:

4.1 Fije el contexto antes de cada consulta

Cada solicitud de consulta debe fijar como mínimo lo siguiente:

1. La región regionId.

2. El AgentSpace.

3. El objeto de datos.

4. El intervalo de tiempo, preferentemente el intervalo semiabierto [from, to).

5. El límite de paginación.

6. Si se permite leer contenido sensible, como prompts, salidas, parámetros de herramientas y cuerpos de memoria.

4.2 No mezcle unidades de tiempo

Convierta la zona horaria de negocio en el lado del cliente. Conserve los valores originales UTC y epoch para que los límites de los informes no se desfasen un día.

4.3 La paginación tiene tres formas

• nextToken + maxResults: la mayoría de las listas de recursos, como AgentSpace, Dataset, ContextStore, Evaluator, Evaluation y Pipeline;

• offset + limit o page + pageSize: algunas listas de Experiment;

• offset + line o LIMIT de SQL: consultas de SLS.

  No interprete una primera página vacía como "sin datos". Revise la ventana de tiempo, las condiciones de filtro, nextToken, los permisos y la latencia de los datos.

4.4 Proyecte solo los campos necesarios

Traces, Trajectories, Evaluations y Memory pueden contener prompts, salidas de modelos, parámetros de herramientas, identificadores de usuarios, contenido de negocio, rutas de archivos o referencias externas. De forma predeterminada, devuelva únicamente:

• Identificadores y campos de linaje;

• estado, duración, tokens y conteos;

• la longitud, el hash y si los campos de contenido están vacíos;

• resúmenes autorizados y redactados.

  Lea el contenido completo solo cuando la resolución de problemas realmente lo requiera.

4.5 Registre evidencias de solicitud de forma consistente

Para cada consulta de API, registre como mínimo lo siguiente:

• La región, el AgentSpace y el tipo de objeto;

• La acción de API o el Project y logstore de SLS;

• Una versión redactada de la ventana de consulta y las condiciones de filtro;

• requestId;

• La posición de paginación;

• La cantidad de entradas devueltas, si el resultado está truncado y si está completo;

• La versión del cliente y la hora de la consulta.

5.1 Listar AgentSpaces

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

Si la respuesta contiene nextToken, páselo en la siguiente solicitud:

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

5.2 Obtener un AgentSpace

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

Campos clave que debe leer:

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

Lea y guarde en un solo paso los localizadores de recursos que requiere esta cadena de consultas:

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

Donde:

• cmsWorkspace sirve para localizar después el Project y logstore de XTrace donde se almacenan los Traces sin procesar;

• slsProject es el Project de datos de AgentLoop del AgentSpace actual. Consulte los detalles de Trajectory, evaluación y experimentos desde este Project;

• regionId es la región que se usa de forma predeterminada en las consultas posteriores de CMS y SLS.

  Criterios de finalización: CMS_WORKSPACE, AGENTSPACE_SLS_PROJECT y RESOURCE_REGION no están vacíos, y el valor agentSpace devuelto coincide con el espacio de destino. No deduzca el Project ni el Workspace a partir del nombre del AgentSpace.

6.1 Localizar el XTrace Store desde AgentSpace

No deduzca el Project de los Traces sin procesar a partir del nombre del AgentSpace ni de slsProject. La cadena de búsqueda completa es la siguiente:

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

Primero, obtenga una ventana de tiempo en segundos Unix correspondiente a las últimas 24 horas:

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

Luego, consulte las entidades de logstore de SLS en el Workspace marcado como 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")

La respuesta utiliza header para describir el orden de las columnas y data para devolver datos bidimensionales. Por ejemplo:

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

Asigne los siguientes campos mediante header:

• TRACE_PROJECT: la columna project_name;

• TRACE_LOGSTORE: la columna logstore_name;

• TRACE_REGION: la columna region; si está vacía, utilice regionId del AgentSpace.

  El siguiente enfoque lee los valores dinámicamente por nombre de columna y no depende de un orden fijo:

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}

No codifique logstore-tracing como único valor para todos los entornos. Utilice el logstore_name que EntityStore devuelve realmente. Si no se encuentra ninguna entidad en las últimas 24 horas, amplíe la ventana de búsqueda a 7 días y compruebe que quien realiza la llamada tenga el permiso cms:GetEntityStoreData en el Workspace actual.

De manera opcional, llame a GetServiceObservability para comprobar el estado de la instancia de observability de APM y entryPointInfo.project. Sin embargo, las consultas de Trace deben seguir usando la combinación de Project y logstore que devuelve EntityStore:

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

Criterios de finalización: los valores obtenidos de la respuesta de CMS incluyen un TRACE_PROJECT y un TRACE_LOGSTORE no vacíos, además de una región disponible. No deben ser valores deducidos por convenciones de nombres.

6.2 Comprobar el XTrace Store

Antes de consultar, compruebe que el Project y el logstore resueltos en el paso anterior existan y permitan lectura:

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

Criterios de finalización: el Project y el logstore que devuelve SLS coinciden con el resultado de búsqueda de EntityStore de CMS.

6.3 Consultar todos los Spans por ID de 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 'traceId:"<trace-id>"' \
  --line 100 \
  --offset 0 \
  --reverse false

Si un Trace tiene más de 100 Spans, aumente offset y continúe paginando hasta que no se devuelvan registros nuevos. No considere completo un Trace tras leer solo la primera página.

Entre los campos comunes se incluyen:

• traceId, spanId y parentSpanId.

• serviceName y operationName.

• startTime, duration y statusCode.

• attributes.gen_ai.span.kind.

• attributes.gen_ai.session.id.

• attributes.gen_ai.agent.name.

• Los atributos gen_ai.* para entrada, salida, modelo, tokens, herramientas, etc.

  La existencia de un campo depende del probe, la adaptación del framework y la configuración de redacción. Que exista un Trace no garantiza que los campos de Tool, Skill, subagente o resultado de negocio estén completos.

6.4 Consultar Traces por 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

Si la integración no reporta attributes.gen_ai.session.id, la plataforma no reconstruirá de forma fiable una Session basándose solo en la proximidad temporal. No agrupe dos Traces cercanos en el tiempo dentro de la misma tarea de negocio.

6.5 Comprobar la integridad del Trace

Compruebe como mínimo lo siguiente:

• La cantidad de ID de Span tras eliminar duplicados;

• Si las referencias padre-hijo están cerradas;

• Si existe un Span raíz;

• Si los campos de entrada y salida se recopilan según la directiva;

• Si los Spans de Tool, LLM y Agent coinciden con las llamadas reales;

• Si la ventana de consulta abarca los Spans que llegan tarde;

• Si se leyeron todas las páginas.

  Criterios de finalización: usted puede recuperar todos los Spans visibles a partir de un traceId explícito y distinguir entre "cierto tipo de llamada realmente no ocurrió" y "faltan instrumentación o campos".

7.1 Ubicación de los datos

El Project de Trajectory proviene directamente del campo slsProject de la respuesta de GetAgentSpace, y el logstore es agent-trajectory:

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

Después de obtener AGENTSPACE_SLS_PROJECT como se describe en la sección 5.2, compruebe que el logstore permita lectura:

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

El slsProject mencionado aquí y el Project de XTrace de los Traces sin procesar son dos conjuntos de localizadores distintos. No se sustituyen entre sí:

Criterios de finalización: GetAgentSpace.slsProject no está vacío y GetLogStore devuelve correctamente información sobre agent-trajectory.

Si slsProject está vacío, o GetLogStore indica que el recurso no existe, confirme primero que el AgentSpace actual haya generado Trajectories de agentes y que quien realiza la llamada tenga permisos de lectura. No sustituya el valor por el Project de XTrace.

7.2 Consultar una lista

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 Consultar por distintos identificadores

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

Los campos de consulta comunes de un Trajectory incluyen:

• Linaje: trajectory_id, previous_trajectory_ref, trace_id, terminal_span_id, session_id y turn_id.

• Tiempo y escala: start_time, end_time, duration_ms y step_count.

• Modelo y tokens: models, model_call_count, total_tokens, input_tokens, output_tokens y cached_tokens.

• Herramientas y Skills: tool_names, tool_call_count, tool_errors, skill_ids, skill_names y skill_call_count.

• Agente: agent_name, agent_version, subagent_trajectory_ids y sub_agent_count.

• Contenido: input, output, atif_content, model_calls, tool_calls y skills.

• Calidad de datos: degraded, degraded_reason, input_empty_reason y version.

  Los campos pueden cambiar según la versión de limpieza. Los consumidores deben admitir campos nuevos y gestionar la compatibilidad con base en version o cleaning_version, en lugar de asumir un orden fijo de columnas.

7.4 Contenido y ATIF

atif_content puede ser muy extenso. Una página de lista no debe leer ni mostrar el ATIF completo. Extraiga el contenido total solo en una consulta de detalle, mediante trajectory_id. Para un input/output excepcionalmente grande, devuelva solo los primeros caracteres y marque explícitamente truncated=true. No trunque el contenido de forma silenciosa.

Criterios de finalización: usted puede leer datos de comportamiento ordenados por trajectory_id o trace_id, y determinar si los datos están degradados, si el contenido está truncado y cuál es la versión de limpieza.

8.1 Listar Datasets

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

Utilice --dataset-name para filtrar con precisión. Si se devuelve nextToken, continúe con la paginación.

8.2 Consultar el esquema de un Dataset

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

Lea primero el esquema y luego genere la consulta. Los tipos de campo comunes incluyen text, long, double y json. Los campos del sistema suelen ser id, __time__ y campos de secuencia internos. Los clientes no deben depender de los campos de secuencia internos.

8.3 SELECT de 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, __time__, question, answer, trace_id FROM <dataset-name> ORDER BY __time__ DESC LIMIT 100'

Reglas de consulta:

• Use solo SELECT de un único Dataset.

• No utilice JOIN, UNION, INTERSECT, EXCEPT ni subconsultas.

• Enumere explícitamente los campos y LIMIT.

• No concatene entradas de usuario directamente en SQL.

• SELECT sin LIMIT devuelve como máximo 1000 filas de forma predeterminada. El límite por consulta depende de la referencia de API de la región de destino y de la respuesta real.

8.4 Ventanas de tiempo, paginación y truncamiento

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: cuando ocurra un truncamiento, revise el campo de respuesta meta.truncation. No trate el texto truncado como una muestra completa.

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 admite comparaciones, AND/OR/NOT, paréntesis, field:value, field:* y coincidencias de prefijo. No utilice IN, BETWEEN, LIKE, IS NULL, funciones arbitrarias ni el DSL de filtro JSON del lado de SearchExpr.

8.6 Búsqueda semántica

El campo de destino debe tener embedding habilitado en el esquema del Dataset.

# 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 La respuesta no es un arreglo de objetos

ExecuteQuery devuelve las columnas y las filas bidimensionales por separado:

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

Quien realiza la llamada debe usar columns[j] para interpretar rows[i][j].

Criterios de finalización: el esquema coincide con los campos de la consulta, meta.progress indica que terminó, se leyeron todas las páginas, se gestionó el estado de truncamiento y los campos clave de linaje no están vacíos.

9.1 Objeto unificado: ContextStore

La API actual de AgentLoop utiliza ContextStore para representar los almacenes de contexto de forma unificada:

• contextType=memory: un almacén de memoria;

• contextType=experience: un almacén de experiencia.

  Ambos pueden usar el mismo conjunto de API de List, Get y Search, pero difieren en su significado de negocio, aislamiento de identidad y origen del contenido.

9.2 Listar almacenes de contexto

# 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

En la respuesta, preste atención a contextStoreName, contextType, status, serviceNames, createTime, updateTime y nextToken.

9.3 Obtener la configuración de un almacén de contexto

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

Los elementos de configuración comunes de un almacén de experiencia incluyen source.agentSpace, source.startTime, serviceNames, metadataField y miningInterval. Un estado Active o Running solo refleja el estado del recurso o de la tarea de minería. No demuestra que ya exista contenido recuperable.

Para contextType=memory, si la respuesta contiene config.innerSource, este indica directamente la ubicación del origen de eventos de ese almacén de memoria:

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

Este logstore almacena eventos a corto plazo que se escribieron mediante la API de Context y esperan extracción. Los resultados de memoria a largo plazo se consultan a través de SearchContext o del Dataset correspondiente. El Project de eventos coincide con slsProject del AgentSpace. La regla de nomenclatura es memory_events_ más MD5(agentSpace + "|" + contextStoreName) como valor hexadecimal en minúsculas de 32 caracteres. Utilice preferentemente innerSource devuelto por la API. Si el SDK actual solo analiza configuraciones generales, calcule el valor con la misma regla y compruébelo con 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}"

Los orígenes de contextType=experience se describen mediante config.source.agentSpace y serviceNames. La minería de experiencias lee las Trajectories de ese AgentSpace y no utiliza el logstore memory_events_* que tiene el mismo nombre.

9.4 Buscar memoria o experiencia

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

Los nombres de campo utilizados para el filtrado por identidad dependen del mapeo de metadatos del ContextStore. Antes de llamar a la API, confirme los campos mediante GetContextStore y el acuerdo del producto. No asuma que todos los almacenes usan userId.

Requisitos de seguridad:

• Una consulta de memoria debe incluir condiciones de aislamiento suficientes para el inquilino, el usuario, el agente, la aplicación y la ejecución (Run);

• Una consulta de experiencia debe incluir el servicio, el escenario u otros límites aplicables;

• threshold y limit deben calibrarse con un conjunto de pruebas real;

• Un código HTTP 200 con results vacío significa que la solicitud llegó al servicio, pero ningún contenido coincidió. No indica un error del servicio;

• Que una búsqueda (Search) se ejecute correctamente no significa que el contenido recuperado se haya inyectado en el agente, ni que la calidad haya mejorado.

9.5 Consulta por ID, exportación completa e historial de auditoría

Las rutas de lectura comunes de un ContextStore son List, Get y Search. Si su negocio requiere una exportación completa determinista, un recorrido por ID o un historial de auditoría, utilice una de las siguientes opciones:

1. Use la solución de materialización o exportación de Dataset disponible oficialmente;

2. Use una API dedicada de ContextStore que esté explícitamente disponible en su región;

3. Para un MemoryStore heredado existente, use la interfaz compatible con CMS que se describe en la siguiente sección.

10.1 Orden de consulta

Primero consulte la configuración y el estado del Evaluator, la Evaluation Task y la Evaluation Run. Después, consulte los detalles por muestra en el SLS Project del AgentSpace. Compruebe el estado del plano de control y los detalles de los resultados por separado.

10.2 Consultar evaluadores

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

Conserve la versión del evaluador en los resultados de la consulta. Por lo general, la instantánea de configuración se congela cuando se crea la tarea, por lo que el evaluador más reciente no es necesariamente la versión que utilizó una Run histórica.

10.3 Consultar tareas y ejecuciones de evaluación

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

El plano de control de Task y Run indica cuál es la configuración y cuánto ha avanzado la ejecución. No necesariamente devuelve los detalles completos de puntuación por muestra.

10.4 Consultar detalles de evaluación

Los detalles de evaluación se encuentran en slsProject del AgentSpace, dentro del 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

Campos comunes:

• task_id, run_id y eval_id.

• evaluator_name y evaluator_display_name.

• status.

• score_name, score_value, score_range y normalized_score_value.

• explanation y evaluation_process.

• eval_info.

• data_link.

• eval_metrics, custom_outputs y eval_latency.

  Ejemplo de consulta para puntuaciones bajas:

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

De forma predeterminada, no exporte eval_info, evaluation_process completo ni el contenido de custom_outputs. Léalo únicamente después de obtener la autorización de datos y cuando realmente necesite investigar un caso individual.

Criterios de finalización: los estados de Task y Run se pueden leer; la cantidad de entradas de detalle de evaluación se explica mediante las combinaciones esperadas de muestras y evaluadores; las entradas con errores, no evaluables y puntuadas correctamente se cuentan por separado; y un caso con puntuación baja se puede rastrear hasta data_link o el Dataset Item al que apunta.

10.5 Consultar detalles de ejecución de Playground

Una ejecución individual de Playground y sus resultados de evaluación se escriben en slsProject del AgentSpace, dentro del logstore playground_detail. Este logstore es independiente de evaluation_detail de las tareas de evaluación formales y resulta adecuado para revisar registros de depuración interactiva:

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

Los registros de Playground pueden contener información confidencial, como entradas, salidas, parámetros de modelo y puntuaciones. Una consulta de lista debe leer primero los campos de ID, estado, modelo y hora. Lea el contenido completo solo cuando investigue una ejecución individual.

11.1 Consultar planes de experimentos

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 Consultar registros de experimentos

En la CLI, run representa un registro de experimento:

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

Los campos comunes de un registro de experimento incluyen recordId, planId, status, los recuentos de tareas totales, completadas y con errores, progress, executedAt, completedAt, datasetId, experimentConfig, evaluationTaskId y mensajes de error.

11.3 Consultar la salida del experimento por muestra

La salida del experimento por muestra se almacena en 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

Campos comunes:

• experiment_id;

• experiment_metadata.experiment_group_name;

• data_config.dataset_id;

• data_config.dataset_item_id;

• experiment_output;

• experiment_metrics;

• status.

  Las puntuaciones del experimento siguen estando en evaluation_detail y se vinculan mediante los siguientes campos:

• data_link.experiment_id;

• data_link.experiment_group_name;

• data_link.dataset_id;

• data_link.dataset_item_id.

  Criterios de finalización: Baseline y Candidate utilizan el mismo conjunto de Dataset Items, la misma versión de evaluador y la misma línea base de entorno. Además, tanto la salida por muestra como las puntuaciones por muestra deben ser rastreables. Comparar únicamente promedios agregados no basta para demostrar que un cambio es eficaz.

12.1 Listar y obtener definiciones

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

En GetPipeline, preste atención al origen, los nodos ordenados, el destino (sink), la directiva de ejecución y la información de la última ejecución. La estructura central del contrato público actual es "un origen de datos → nodos de procesamiento ordenados → Dataset Sink". No lo describa como un DAG arbitrario, una unión de múltiples orígenes ni una plataforma de múltiples destinos.

12.2 Consultar ejecuciones

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

En los detalles de la Run, preste atención a lo siguiente:

• status;

• La ventana de datos;

• triggerType;

• attempt/maxAttempts;

• startTime/finishTime;

• stats;

• errorCode/errorMessage;

• Resultados en línea opcionales.

12.3 Consultar estadísticas

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 Debe consultar el Dataset nuevamente

Después de que una Run alcance el estado Succeeded, aún debe consultar el Dataset de destino y comprobar como mínimo lo siguiente:

• El alcance de selección del origen y el recuento de filas de destino;

• trace_id/trajectory_id/session_id y otros campos de linaje;

• La proporción de campos obligatorios que están vacíos;

• IDs duplicados;

• Campos convertidos;

• Truncamiento;

• Si los datos filtrados se pueden explicar.

  Criterios de finalización: las filas reales del Dataset de destino se leyeron de vuelta y cumplen con el contrato de campos, en lugar de mostrar únicamente un estado de Pipeline exitoso.

13.1 Anotaciones de Dataset

execute-query admite --annotation-filter, que le permite filtrar datos de Dataset según condiciones de anotación. Los campos, operadores y valores de estas condiciones deben coincidir con la configuración de anotación del Dataset.

Las puntuaciones automáticas y las anotaciones manuales deben almacenarse en campos separados. No las sobrescriba para luego tratar una conclusión automática como un estándar de referencia humano.

13.2 Prompts y Skills de tiempo de ejecución

Los Prompts y los Skills de tiempo de ejecución pertenecen al dominio de activos del agente, mientras que los Skills de Evaluator pertenecen al dominio de evaluación. No son el mismo tipo de recurso. Cuando consulte un Prompt o un Skill de tiempo de ejecución, utilice las condiciones de versión, estado de publicación y etiqueta de la referencia de API de activos del agente. Una consulta de Skill de Evaluator no sirve como sustituto.

13.3 Métricas de token, costo y calidad

Los tokens, la latencia del modelo y las llamadas a herramientas se pueden agregar a partir de campos de Trace o Trajectory. La calidad de evaluación se agrega desde evaluation_detail. Ambos provienen de planos de evidencia distintos, así que especifique la ventana de tiempo, la unidad de deduplicación y el denominador cuando realice la agregación:

• Las métricas de Trace generalmente se deduplican por traceId;

• Las métricas de sesión se deduplican por Session ID;

• Las métricas de Trajectory se deduplican por trajectory_id;

• Las métricas de Dataset se deduplican por el id del Dataset Item;

• Las métricas de evaluación se deduplican por eval_id y también se dividen por evaluador;

• Las métricas de experimento se deduplican por experiment_id + group + dataset_item_id.

14.1 Encontrar la Trajectory y la muestra de Dataset a partir de un Trace

1. En TRACE_PROJECT/TRACE_LOGSTORE, ubicado mediante CMS EntityStore, lea los Spans completos por traceId.

2. En agent-trajectory, consulte la Trajectory por trace_id.

3. Registre trajectory_id, session_id y la versión de limpieza.

4. En el Dataset de destino, consulte trace_id o trajectory_id almacenados explícitamente.

5. Si el esquema del Dataset no tiene campos de linaje, no podrá establecer una asociación determinista basada en la proximidad temporal.

   Ejemplo de Dataset:

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

14.2 Encontrar resultados de evaluación a partir de un Dataset Item

1. Obtenga el id del Item desde el Dataset.

2. En evaluation_detail, consulte data_link.dataset_item_id.

3. Restrinja también task_id o run_id para evitar coincidencias con reejecuciones históricas.

4. Interprete las puntuaciones por evaluador de forma independiente. No promedie métricas distintas directamente en una puntuación de calidad general.

14.3 Verificar Baseline y Candidate a partir de registros de experimentos

1. Utilice GetExperimentRun para obtener recordId, el Dataset, el grupo de configuración y la tarea de evaluación asociada.

2. En experiment_detail, obtenga la salida de cada Dataset Item por experiment_id.

3. En evaluation_detail, obtenga las puntuaciones por data_link.experiment_id.

4. Utilice dataset_item_id + experiment_group_name para alinear los resultados.

5. Compruebe si hay salidas faltantes, muestras duplicadas y registros con errores o no evaluables.

14.4 Rastrear un resultado de recuperación de experiencia hasta su trayectoria de origen

Un resultado de experiencia se puede rastrear de forma determinista solo cuando sus metadatos conservan sourceTraceId, trace_id, trajectory_id o un campo equivalente. Los nombres de los campos dependen de la configuración del ContextStore.

Si no existe un identificador de origen, solo podrá indicar que se recuperó una experiencia. No afirme que proviene de un Trace específico.

import os

from alibabacloud_agentloop20260520.client import Client
from alibabacloud_agentloop20260520 import models as agentloop_models
from alibabacloud_tea_openapi import models as openapi_models

region = os.environ["AL_QUERY_REGION"]
agent_space = os.environ["AL_QUERY_AGENT_SPACE"]
dataset_name = os.environ["AL_QUERY_DATASET"]

# The example reads credentials from standard environment variables. In production, prefer STS, a RAM role, or a unified credential provider.
config = openapi_models.Config(
    access_key_id=os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"],
    access_key_secret=os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"],
    security_token=os.environ.get("ALIBABA_CLOUD_SECURITY_TOKEN"),
    region_id=region,
    endpoint=f"agentloop.{region}.aliyuncs.com",
    connect_timeout=3000,
    read_timeout=15000,
)
client = Client(config)

request = agentloop_models.ExecuteQueryRequest(
    type="SQL",
    query=(
        f"SELECT id, __time__, question, answer "
        f"FROM {dataset_name} ORDER BY __time__ DESC LIMIT 100"
    ),
)
response = client.execute_query(agent_space, dataset_name, request)
body = response.body

records = [dict(zip(body.columns, row)) for row in body.rows]
print({
    "request_id": body.request_id,
    "count": body.meta.count,
    "progress": body.meta.progress,
    "records": records,
})

18.1 Operaciones de consulta de AgentLoop

18.2 Operaciones de ubicación de datos de Trace y Trajectory

18.3 Comandos de consulta de evaluación y experimentos

Antes de llamar a la API, confirme que la cuenta de destino tiene los permisos de lectura de RAM correspondientes y utilice una versión de la API de AgentLoop que admita la región de destino.

19.1 Primero enumere los logstores que existen realmente en el AgentSpace

Un nombre fijo significa que el contrato de datos es fijo. No implica que cada AgentSpace tenga todos los logstores inmediatamente después de su creación. Muchos logstores se crean después de habilitar la capacidad correspondiente de integración, auditoría, evaluación, experimentos, memoria o análisis de eficiencia. Primero utilice GetAgentSpace.slsProject para enumerar los recursos reales:

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

Si la cantidad de entradas devueltas alcanza 500, siga incrementando offset hasta haber leído todo. Para cada logstore que planee consultar, compruebe el recurso y el índice:

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 demuestra que el recurso existe, y GetIndex demuestra qué campos admiten consultas por palabra clave, por rango o SQL. Ninguno de los dos demuestra que ya existan datos dentro de la ventana de tiempo de destino.

19.2 Logstores de trayectoria y de funciones de trayectoria

El Project de estos logstores siempre proviene de GetAgentSpace.slsProject:

Cuando consulte funciones de trayectoria, correlacione preferentemente las cuatro vistas mediante trajectory_id o feature_id. El logstore trajectory-feature-event se deriva de una trayectoria y no equivale al evento agent-event que reporta la aplicación.

19.3 Logstores de eventos de agente sin procesar y de auditoría

Estos logstores también residen en el slsProject de AgentSpace. La ingesta escribe los eventos sin procesar. Los datos de auditoría derivados aparecen cuando se habilita la capacidad de auditoría correspondiente y genera resultados.

Cuando ejecute consultas entre agent-event y agent-event-webtracking, proyecte explícitamente los mismos campos y agregue una columna de origen. Después utilice UNION ALL. No asuma que ambos logstores contienen datos en todas las ventanas de tiempo. El logstore ebpf-event pertenece al ámbito de datos en tiempo de ejecución, así que no lo combine directamente con eventos de aplicaciones de IA si no cuenta con una clave de correlación.

19.4 Logstores de evaluación, experimentos y Playground

El logstore experiment_detail almacena la salida del experimento, mientras que la puntuación permanece en evaluation_detail. Por su parte, playground_detail sirve para depurar de manera interactiva y no debe tratarse como la fuente de resultados de una tarea o ejecución de evaluación formal.

19.5 Logstores de tokens, costos y eficiencia

Cuando se habilita el análisis de eficiencia de tokens y costos, el Project de AgentSpace puede contener los siguientes logstores:

Para leer datos de eficiencia, primero utilice mining-catalog y confirme las ejecuciones y ventanas publicadas. Luego lea los datos de Feature, Fragment o Serving. No concluya que una ventana se publicó solo porque un logstore tiene filas.

19.6 Logstores con nombres dinámicos o determinados por la configuración de recursos

Un ContextStore de experiencia no requiere un logstore de eventos que comparta su nombre. Este selecciona el origen mediante config.source.agentSpace y serviceNames, y lee trayectorias principalmente del logstore agent-trajectory de ese AgentSpace. Los resultados de recuperación se consultan a través de la API de ContextStore.

19.7 Diferencie los distintos tipos de eventos

También distinga agent-trajectory del logstore agentloop-trajectory presente en los registros operativos del servicio. El primero corresponde a la trayectoria de negocio dentro del AgentSpace del cliente, mientras que el segundo es el registro operativo del propio servicio de trayectorias. Aunque los nombres son similares, el Project, el esquema, los permisos y los propósitos difieren por completo.

19.8 Logstores de control de procesos, medición y operación del servicio

La ejecución de tareas de AgentLoop también utiliza logstores de control de procesos o de observación del servicio. A continuación se describen las categorías más comunes:

Los nombres, los Projects y los periodos de retención de los logstores de control de procesos u operación del servicio varían según la región y el entorno de despliegue. Estos logstores explican por qué una tarea está en espera o terminó con errores, pero no reemplazan los resultados de consultas de Trace, trayectoria, Dataset, Evaluation, Experiment o Context del plano de datos del cliente.

19.9 Plantilla general de consulta de logstores

Una vez que confirme el Project, el logstore, el índice y el rango de tiempo, ejecute una consulta acotada:

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

Si consulta un esquema desconocido por primera vez, lea un número reducido de registros y utilice GetIndex para confirmar los campos antes de escribir los filtros y el SQL definitivos. Al terminar una consulta, registre el Project, el logstore, la ventana de tiempo, las condiciones de filtro, la paginación, el indicador de integridad y el requestId.