Supervisar al agente

Overview

En esta guía, aprenderá a supervisar el rendimiento de su agente y el estado de su implementación.

Los entornos aislados de agentes generan registros durante la ejecución que puede utilizar para supervisar el comportamiento del agente y diagnosticar problemas. Puede recuperar estos registros de las siguientes maneras:

Utilice los registros del agente de la API o la CLI: Recupere los registros de tiempo de ejecución del agente, incluida la salida stdout/stderr, las instrucciones print() y la salida de depuración del marco.
Utilice la API para los registros de eventos de implementación: acceda a los registros de eventos de implementación estructurados para rastrear el comportamiento de la implementación, investigar fallas y verificar las transiciones del ciclo de vida.

Para comprobar el estado en tiempo real del agente desplegado, utilice el comando agentengine status o la tarjeta de estado del espacio de trabajo en la interfaz de usuario de la plataforma.

Para depurar la latencia o el comportamiento inesperado en una ejecución específica del agente, consulte la sección "Inspeccionar los rastros de ejecución del agente".

Ver registros de ejecución del agente

El motor de agentes de MongoDB Atlas captura la salida estándar (stdout/stderr), las sentencias print(), las llamadas logging y la salida de depuración del framework de los agentes implementados, y las almacena en S3. Puede recuperar estos registros mediante la interfaz de usuario de la plataforma, la API o la interfaz de línea de comandos (CLI).

Utiliza la interfaz de usuario

Para ver los registros en la interfaz de usuario, siga los siguientes pasos:

Seleccione Workspaces en la barra de navegación izquierda y haga clic en el espacio de trabajo que desea ver.
Haga clic en la pestaña Logs para abrir un visor de registros interactivo.
Ajusta el periodo de tiempo que deseas visualizar seleccionando el botón 15m, 1h o 6h. También puedes cambiar la zona horaria con el selector de zona horaria. Para ver los registros de un periodo más largo, utiliza la función de exportación de registros.
Seleccione las opciones de los menús desplegables Level, Source y Service para filtrar los registros. A continuación, haga clic en Search para aplicar los filtros. Los filtros de nivel y origen devuelven coincidencias exactas, por lo que al seleccionar INFO solo se mostrarán las entradas INFO, no las INFO ni las de mayor gravedad.

Usar la API

Consulte los registros de ejecución del agente utilizando el siguiente punto final:

GET /api/v1/projects/{id}/agent-logs

Pase el ID del objeto del proyecto a consultar como valor {id}. El usuario que realiza la llamada debe pertenecer a la organización de dicho proyecto.

Los siguientes parámetros de consulta están disponibles:

Parameter	Requerido	Descripción
`workspace_id`	Sí	Identificador del espacio de trabajo para recuperar los registros.
`start_time`	No	Hora de inicio de RFC3339. Por defecto, es una hora atrás. El intervalo entre `start_time` y `end_time` no puede exceder las seis horas.
`end_time`	No	Hora de finalización de RFC3339. Por defecto, es ahora.
`level`	No	El nivel de registro debe coincidir exactamente. Este parámetro acepta `DEBUG`, `INFO`, `WARNING` o `ERROR`.
`execution_id`	No	Filtrar por ID de ejecución (coincidencia exacta).
`session_id`	No	Filtrar por ID de sesión (coincidencia exacta).
`source`	No	Filtrar por origen del registro: `stdout`, `stderr`, `python-logging` o `node-logging`.
`service`	No	Filtrar por servicio: `agent` o `tool`.
`search`	No	Coincidencia de subcadenas sin distinción de mayúsculas y minúsculas en el campo `message` o `bootId`.
`limit`	No	Número máximo de entradas a devolver. Por defecto es `500`, máximo `5000`.
`cursor`	No	Cursor de paginación opaco devuelto por una respuesta anterior.
`order`	No	Orden de clasificación de los resultados. Este parámetro acepta `asc` o `desc`. El valor predeterminado es `asc`.
`tail`	No	Valor booleano que especifica si se deben devolver las entradas más recientes en lugar de paginar desde el inicio del rango de tiempo. No se puede combinar con el parámetro `cursor`.

Los resultados se paginan mediante un cursor. Cada respuesta incluye un campo nextCursor, salvo que se trate de la última página, y un valor booleano hasMore. Para obtener la página siguiente, pase el valor de nextCursor como parámetro cursor en su próxima solicitud.

Cada entrada de registro en el array logs contiene los siguientes campos:

Campo	Descripción
`timestamp`	Hora en que se registró la entrada del registro, en formato RFC3339.
`level`	Nivel de registro: `DEBUG`, `INFO`, `WARNING` o `ERROR`.
`message`	Contenido del mensaje de registro.
`source`	Origen del registro: `stdout`, `stderr`, `python-logging` o `node-logging`.
`service`	Servicio que generó el registro.
`tenantId`	Inquilino propietario del agente en funcionamiento.
`executionId`	Ejecución asociada a la entrada del registro.
`sessionId`	Sesión asociada a la entrada del registro.
`workspaceId`	Espacio de trabajo asociado a la entrada del registro.
`traceId`	Identificador de seguimiento asociado a la entrada del registro.
`bootId`	Identificador del arranque del pod que generó la entrada de registro.
`logger`	Nombre del registrador, si el registro se originó a partir de una llamada `logging`.
`podName`	Pod de Kubernetes que generó el registro.
`fields`	Campos adicionales estructurados de clave-valor adjuntos a la entrada del registro.

Utilice la interfaz de línea de comandos (CLI).

Utilice el siguiente comando de CLI para recuperar los registros de ejecución del agente:

agentengine logs [flags]

El comando resuelve el espacio de trabajo a partir del archivo de estado .agentengine/ del directorio actual. Para seleccionar un espacio de trabajo diferente, utilice el indicador --context con un contexto con nombre, o bien el indicador --workspace-id junto con --project-id, --org-id y --base-url. Para obtener más información sobre la gestión de espacios de trabajo, consulte la sección «Gestionar espacios de trabajo».

Las siguientes banderas están disponibles:

Flag	Descripción
`--session-id`	Filtrar por ID de sesión.
`--execution-id`	Filtrar por ID de ejecución.
`--source`	Filtrar por entorno aislado de origen: `agent` o `tool`. Acepta una lista separada por comas o espacios.
`--level`	Nivel de registro que debe coincidir exactamente: `debug`, `info`, `warn` o `error`. Acepta una lista separada por comas o espacios.
`--grep`	Búsqueda de subcadenas en mensajes de registro sin distinción entre mayúsculas y minúsculas. No utiliza comodines ni expresiones regulares.
`--since`	Hora de inicio como una duración (por ejemplo, `30m`, `2h`) o marca de tiempo RFC3339. El valor predeterminado es `1h`. Máximo `6h`.
`--until`	Hora de finalización como duración o marca de tiempo RFC3339. Por defecto, es ahora.
`--tail`	Número máximo de entradas más recientes a devolver. El valor predeterminado es `500`. Limitado a `5000`, pero puede usar `--all` para recuperar todas las entradas de registro en el rango de tiempo.
`--all`	Recupera todos los registros dentro del rango de tiempo, paginando automáticamente a través de todas las páginas.
`-f`, `--follow`	Realizar sondeos continuos en busca de nuevos registros.
`--json`	Genera los registros en formato JSON en lugar de en un formato legible para humanos.
`--workspace-id`	ID del espacio de trabajo al que se debe apuntar. Debe combinarse con `--project-id`, `--org-id` y `--base-url`, o utilizarse en un directorio con un espacio de trabajo registrado.
`--project-id`	ID del proyecto. Se utiliza con `--workspace-id`.
`--org-id`	ID de la organización. Se utiliza con `--workspace-id`.
`--base-url`	URL base de la plataforma. Se utiliza con `--workspace-id`.
`--workspace`	En un monorepo, selecciona un espacio de trabajo específico por nombre desde la raíz `agent.yaml`.
`--context`	Plataforma de destino con nombre que se utilizará en lugar de un ID de espacio de trabajo. Ejecute `agentengine context list` para ver los contextos disponibles.

Ejemplos

Esta sección proporciona ejemplos de comandos de la interfaz de línea de comandos (CLI) para tareas comunes de recuperación de registros.

El siguiente comando recupera los registros de la última hora:

agentengine logs

El siguiente comando muestra los registros en tiempo real a medida que se escriben:

agentengine logs --follow

El siguiente comando recupera únicamente los registros de nivel de error del servicio sandbox del agente:

agentengine logs --source agent --level error

El siguiente comando busca una subcadena en los registros de los últimos 30 minutos:

agentengine logs --grep "connection refused" --since 30m

El siguiente comando recupera todos los registros de las últimas seis horas:

agentengine logs --all --since 6h

Exportar registros de ejecución sin procesar

Para ver los registros de ejecución de un período superior a seis horas, puede exportar los registros sin procesar del agente o del servicio de herramientas. Los registros exportados incluyen hasta 24 horas de datos y puede descargarlos como un archivo JSON Lines comprimido con gzip.

Utiliza la interfaz de usuario

Para exportar los registros de ejecución sin procesar desde la interfaz de usuario, siga los siguientes pasos:

Seleccione Workspaces en la barra de navegación izquierda y haga clic en el espacio de trabajo que desea ver.
Haga clic en la pestaña Logs para abrir un visor de registros interactivo.
Haga clic en Export para abrir el cuadro de diálogo de exportación sin procesar.
En el menú desplegable Service, seleccione Agent o Tool.
En el menú desplegable Time period, seleccione un rango preestablecido de las 6, 12 o 24 horas anteriores, o bien, especifique un rango personalizado. Un rango personalizado no puede exceder las 24 horas. A continuación, seleccione su zona horaria en el menú desplegable Time zone.
Haz clic en Export para descargar el archivo de registro.

Utilice la interfaz de línea de comandos (CLI).

Utilice el siguiente comando de CLI para exportar los registros de ejecución sin procesar:

agentengine logs export --service <agent|tool> [flags]

Las siguientes banderas están disponibles:

Flag	Descripción
`--service`	(Obligatorio) Servicio de tiempo de ejecución para exportar. Puede especificar `agent` o `tool`.
`--since`	Hora de inicio, que puede especificarse como una duración o una marca de tiempo RFC3339. El valor predeterminado es `24h`. El intervalo entre los valores `--since` y `--until` no puede exceder las 24 horas.
`--until`	Hora de finalización como duración o marca de tiempo RFC3339. Por defecto, se utiliza la hora actual.
`-o`, `--output`	Ruta del archivo de salida. Por defecto es `agent-logs-<service>-<end-time>.jsonl.gz`. El comando no sobrescribe ningún archivo existente en esta ruta.
`--workspace-id`	ID del espacio de trabajo al que se debe apuntar. Debe combinarse con `--project-id`, `--org-id` y `--base-url`, o utilizarse en un directorio con un espacio de trabajo registrado.
`--project-id`	ID del proyecto. Se utiliza con `--workspace-id`.
`--org-id`	ID de la organización. Se utiliza con `--workspace-id`.
`--base-url`	URL base de la plataforma. Se utiliza con `--workspace-id`.
`--workspace`	En un monorepo, selecciona un espacio de trabajo específico por nombre desde la raíz `agent.yaml`.
`--context`	Plataforma de destino con nombre que se utilizará en lugar de un ID de espacio de trabajo. Ejecute `agentengine context list` para ver los contextos disponibles.

El comando escribe la descarga de forma atómica, por lo que una exportación fallida o interrumpida no deja un archivo parcial en el destino.

El siguiente comando exporta las 24 horas anteriores de registros de servicio del agente:

agentengine logs export --service agent

El siguiente comando exporta seis horas de registros de servicio de la herramienta a un archivo especificado:

agentengine logs export --service tool --since 6h --output logs.jsonl.gz

Formato de registro

Los entornos aislados de agentes emiten registros como registros JSON estructurados. La siguiente tabla describe los campos de cada registro:

Campo	Descripción
`timestamp`	Marca de tiempo ISO 8601 que indica cuándo se emitió el registro.
`level`	Nivel de gravedad del registro, como `DEBUG`, `INFO`, `WARNING` o `ERROR`.
`logger`	Nombre del registrador de Python que emitió el registro.
`message`	Texto del mensaje de registro legible para humanos
`service`	Origen del registro, que puede ser `agent` o `tool`.
`tenantId`	Identificador del inquilino propietario del agente en ejecución
`workspaceId`	Identificador del espacio de trabajo donde se implementa el agente.
`executionId`	Identificador de la ejecución actual del agente.
`sessionId`	Identificador de la sesión actual
`podName`	Nombre del pod de Kubernetes del contenedor que emitió el registro
`source`	Flujo que produjo la entrada de registro, que puede ser `stdout` o `stderr`.
`fields`	Mapa de pares clave-valor que contienen metadatos estructurados sobre el evento de registro.

El siguiente ejemplo muestra el formato de un único registro de log estructurado:

{
  "timestamp": "2025-10-15T14:32:07.123456Z",
  "level": "INFO",
  "logger": "agent.executor",
  "message": "Tool call completed",
  "service": "tool",
  "tenantId": "t-abc123",
  "workspaceId": "ws-def456",
  "executionId": "exec-789xyz",
  "sessionId": "sess-uvw012",
  "podName": "tool-ws-def456-5b8d9f-jklmn",
  "source": "stdout",
  "fields": {
    "toolName": "search",
    "durationMs": 243
  }
}

Ver eventos de despliegue

El motor del agente de MongoDB Atlas registra un registro de eventos estructurado para cada despliegue, capturando cada transición de estado desde su creación hasta su finalización. Puede usar este registro para rastrear el comportamiento del despliegue, investigar fallos y verificar que se hayan producido las transiciones del ciclo de vida previstas. Puede acceder al registro de eventos mediante la interfaz de usuario de la plataforma, la interfaz de línea de comandos (CLI) o la API.

Cada evento contiene los siguientes campos:

Campo	Descripción
`category`	La categoría o etapa de la transición del ciclo de vida que desencadenó el evento. Los valores posibles son: `lifecycle`, `secret_sync`, `cr_create`, `oe_rollout`, `aer_rollout`, `tool_pod_rollout`, `memory_rollout`, `deploy_diagnostic` y `post_deploy_health`.
`component`	El componente de despliegue asociado al evento.
`reason`	Un código de motivo legible por máquina para el evento.
`message`	Una descripción del evento legible para humanos.
`condition_ref`	La condición asociada al evento, como `Available` o `SecretsReady`.

Utiliza la interfaz de usuario

La interfaz de usuario de la plataforma muestra una pestaña de Registro de eventos en la página de Implementación para todas las implementaciones, tanto activas como completadas.

Para las implementaciones activas, que son pending, in_progress o cleaning_up, los eventos se transmiten en tiempo real a través de SSE.
Para las implementaciones completadas, la tarjeta carga el historial completo de eventos desde el punto final REST.

Cada fila de evento muestra la marca de tiempo UTC, el nivel de gravedad (info, success, warn o error), la etapa del ciclo de vida, el componente y el mensaje. Puede filtrar los eventos por nivel y por etapa para refinar la visualización.

Utilice la interfaz de línea de comandos (CLI).

Para ver el registro de eventos de una implementación específica, utilice el comando agentengine deploy logs. Para obtener más información, consulte Ver registro de eventos de implementación.

También puede transmitir eventos en tiempo real durante una implementación activa utilizando la bandera -f con agentengine deploy get. Para obtener más información, consulte la sección "Comprobar el estado de la implementación".

Usar la API

Para consultar directamente los eventos de despliegue, utilice el siguiente punto final de la API:

GET /api/v1/projects/{project_id}/deployments/{deployment_id}/events

Los resultados se paginan mediante un cursor. Utilice los parámetros de consulta after y limit para controlar la paginación. limit toma como valor predeterminado 100 y no puede exceder 100.

Comprobar el estado del espacio de trabajo

Tras una implementación exitosa, puede consultar el estado en tiempo real del agente implementado en cualquier momento. La vista de estado del espacio de trabajo muestra la disponibilidad actual de cada componente del agente, el número de réplicas listas y una marca de tiempo que indica la última vez que se comprobó su estado.

Utiliza la interfaz de usuario

La página de resumen del espacio de trabajo en la interfaz de usuario de la plataforma incluye una tarjeta de estado de implementación en tiempo real. Esta tarjeta muestra el estado de cada componente, incluyendo el estado, las réplicas listas y el motivo. Puede hacer clic en Actualizar para obtener el estado actual en cualquier momento.La marca de tiempo "Última comprobación" indica cuándo se recuperó el estado por última vez.

Utilice la interfaz de línea de comandos (CLI).

Para ver el estado en tiempo real de su agente desplegado, ejecute el siguiente comando:

agentengine status

El comando llama al punto final de estado del espacio de trabajo y muestra los resultados como un resumen, como se muestra en el siguiente ejemplo:

✓ my-agent is ready
summary
  deployment:  deploy-55996f39 (succeeded 21h ago)
  readiness:   4/4 components ready
  health:      healthy (checked just now)
  invoke:      https://<base-url>/api/v1/projects/<project-id>/workspaces/<workspace-id>/invoke
  stream:      https://<base-url>/api/v1/projects/<project-id>/workspaces/<workspace-id>/invokeStream
  dashboard:   https://<base-url>/project/<project-id>/workspaces/<workspace-id>/deployments
components
  Orchestration Engine      healthy (2 replicas)  [scope: project]
  Agent Sandbox             healthy (4 replicas)  [scope: workspace]
  Tool Sandbox              healthy (4 replicas)  [scope: workspace]
  Secrets                   healthy  [scope: workspace]

Pase el indicador --verbose para incluir detalles adicionales de implementación y tiempo de ejecución, o pase --json para mostrar el estado completo como JSON.

Ver denegaciones de póliza

La página Observability de la interfaz de usuario de la plataforma incluye un mosaico Policy denials. Este mosaico muestra cuántas llamadas rechazó el Motor de políticas durante el intervalo de tiempo que usted seleccione. Puede usar el mosaico para encontrar agentes que una política bloquea repetidamente, lo que indica que el agente intentó realizar tareas no autorizadas o que la política es demasiado restrictiva para la carga de trabajo. El mosaico muestra datos solo para su organización y proyectos.

El mosaico contabiliza las denegaciones generadas por el tipo de política AUTHORIZED_TOOLS y las generadas por las políticas de ejecución y presupuesto de sesión. El mosaico no contabiliza las denegaciones generadas por el tipo de política AUTHORIZED_MODELS. Para obtener más información sobre cada tipo de política, consulte Tipos de políticas.

Ver registros de depuración de la CLI

Cada comando agentengine escribe un archivo de registro JSON estructurado en un directorio específico de la plataforma en su máquina. La CLI conserva los 20 archivos de registro más recientes. Cuando un comando falla, la última línea stderr incluye la ruta al archivo de registro correspondiente.

La siguiente tabla enumera las ubicaciones de los registros por plataforma:

Plataforma	ruta
macOS	`~/Library/Logs/agentengine/agentengine-<timestamp>-<pid>.log`
Linux	`${XDG_STATE_HOME:-~/.local/state}/agentengine/logs/`
Windows	`%LOCALAPPDATA%\agentengine\Logs\`

Para anular la ruta del archivo de registro, utilice la bandera --log-file o la variable de entorno AGENTENGINE_LOG_FILE. Las siguientes variables de entorno también controlan el comportamiento del registro:

AGENTENGINE_LOG_LEVEL establece la verbosidad del archivo
AGENTENGINE_NO_LOG desactiva el registro de archivos
AGENTENGINE_LOG_MAX_FILES establece el número de archivos de registro retenidos
AGENTENGINE_NO_LOG_PRUNE desactiva la poda de retención automática

Listar archivos de registro de la CLI

Para listar todos los archivos de registro de la CLI, ordenados del más reciente al más antiguo, ejecute el siguiente comando:

agentengine debug logs list [--json]

Cada fila muestra el nombre del archivo y el comando ejecutado. Pase el indicador --json para recibir un objeto legible por máquina con schema_version, status y una matriz logs. Cada entrada de la matriz incluye name, path, modified_at, size_bytes y command.

Ver un archivo de registro de la CLI

Para imprimir el contenido de un archivo de registro, ejecute el siguiente comando:

agentengine debug logs get [<logfile>] [--last] [--pretty]

Indique el nombre del archivo de registro que muestra agentengine debug logs list, o use --last para imprimir el registro más reciente. La salida se formatea como líneas JSON sin formato por defecto. Use el indicador --pretty para formatear y colorear cada registro.

El siguiente ejemplo utiliza los comandos agentengine debug logs para listar y ver los archivos de registro:

agentengine debug logs list
agentengine debug logs get agentengine-2026-05-13T11-43-57Z-12345.log
agentengine debug logs get --last --pretty

Recursos adicionales

Para obtener más información sobre los puntos finales de la API que se describen en esta guía, consulte la documentación de la API.

Volver

Permisos de rol de Atlas

Inspeccionar los rastros de ejecución del agente