Monitore o agente

Visão geral

Neste guia, você pode aprender a monitorar o desempenho do seu agente e a integridade do seu sistema.

As sandboxes do agente produzem registros durante a execução que você pode usar para monitorar o comportamento do agente e diagnosticar problemas. Você pode recuperar esses registros das seguintes maneiras:

Use os registros de agente API ou CLI: recupere registros de tempo de execução de agente , incluindo saída stdout/stderr, declarações print() e saída de depuração de framework.
Use a API para registros de evento de implantação: acesse registros de evento de implantação estruturados para rastrear o comportamento da implantação, investigar falhas e verificar transições do ciclo de vida.

Para verificar a integridade do seu agente implantado, use o comando agentengine status ou o cartão de integridade do espaço de trabalho na interface do usuário da plataforma.

Para depurar latência ou comportamento inesperado na execução de um agente específico, consulte Inspecionar rastreamentos de execução do agente.

Exibir registros de tempo de execução do agente

O MongoDB Atlas Agent Engine captura saída stdout/stderr, declarações print(), chamadas logging e saída de depuração de framework de seus agentes implementados e os armazena em S3. Você pode recuperar esses registros usando a UI da plataforma, a API ou a CLI.

Usar a IU

Para visualizar registros na UI, execute as seguintes etapas:

Selecione Workspaces na barra de navegação à esquerda e clique no espaço de trabalho que deseja visualizar.
Clique na guia Logs para abrir um visualizador de registro interativo.
Ajuste o período de tempo que pretende visualizar selecionando o botão 15m, 1h ou 6h. Você também pode alterar o zona horário usando o seletor de zona horário. Para visualizar registros por um longo período de tempo, use o recurso de exportação de registros.
Selecione opções nos menus suspensos Level, Source e Service para filtrar os registros. Em seguida, clique em Search para aplicar os filtros. Os filtros de nível e de origem retornam correspondências exatas, portanto, selecionar INFO retorna apenas entradas INFO, não INFO e gravidades mais altas.

Usar a API

Consulte os registros de tempo de execução do agente usando o seguinte endpoint:

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

Passe o ID do objeto do projeto para query como o valor {id}. O chamador deve pertencer à organização desse projeto.

Os seguintes parâmetros de query estão disponíveis:

Parâmetro	Obrigatório	Descrição
`workspace_id`	Sim	Identificador de espaço de trabalho para o qual recuperar registros.
`start_time`	No	Hora de início da RFC3339. O padrão é uma hora atrás. O intervalo entre `start_time` e `end_time` não pode exceder seis horas.
`end_time`	No	Hora de término RFC3339. O padrão é agora.
`level`	No	Nível de registro para corresponder exatamente. Este parâmetro aceita `DEBUG`, `INFO`, `WARNING` ou `ERROR`.
`execution_id`	No	Filtre por ID de execução (correspondência exata).
`session_id`	No	Filtre por ID da sessão (correspondência exata).
`source`	No	Filtrar por origem de registro: `stdout`, `stderr`, `python-logging` ou `node-logging`.
`service`	No	Filtrar por serviço: `agent` ou `tool`.
`search`	No	Correspondência de substring sem distinção entre maiúsculas e minúsculas no campo`message` ou `bootId`.
`limit`	No	Número máximo de entradas a retornar. Padrão para `500`, máximo `5000`.
`cursor`	No	Cursor de paginação opaco retornado por uma resposta anterior.
`order`	No	Ordem de classificação dos resultados. Este parâmetro aceita `asc` ou `desc`. O padrão é `asc`.
`tail`	No	Booleano que especifica se devem ser retornadas as entradas mais recentes em vez de paginar desde o início do intervalo de tempo. Não pode ser combinado com o parâmetro `cursor`.

Os resultados são paginados usando um cursor. Cada resposta inclui um camponextCursor, a menos que a resposta seja a última página, e um booleano hasMore. Para recuperar a página seguinte, passe o valor de nextCursor como o parâmetro cursor em sua próxima solicitação.

Cada entrada de registro na array logs contém os seguintes campos:

Campo	Descrição
`timestamp`	Hora em que a entrada do registro foi registrada, no formato RFC3339.
`level`	Nível de registro: `DEBUG`, `INFO`, `WARNING` ou `ERROR`.
`message`	Conteúdo da mensagem de registro.
`source`	Origem do registro: `stdout`, `stderr`, `python-logging` ou `node-logging`.
`service`	Serviço que gerou o registro.
`tenantId`	Inquilino que possui o agente em execução.
`executionId`	Execução associada à entrada de registro.
`sessionId`	Sessão associada à entrada de registro.
`workspaceId`	Espaço de trabalho associado à entrada de registro.
`traceId`	Identificador de rastreamento associado à entrada de registro.
`bootId`	Identificador para a inicialização do pod que produziu a entrada de registro.
`logger`	Nome do registrador, se o registro se originou de uma chamada `logging`.
`podName`	Pod do Kubernetes que produz o log.
`fields`	Campos de valor-chave estruturados adicionais anexados à entrada de registro.

Usar a CLI

Use o seguinte comando da CLI para recuperar registros de tempo de execução do agente :

agentengine logs [flags]

O comando resolve o espaço de trabalho do arquivo de estado .agentengine/ do diretório atual. Para direcionar um espaço de trabalho diferente, passe o sinalizador --context com um contexto nomeado ou passe o sinalizador --workspace-id junto com --project-id, --org-id e --base-url. Para mais informações sobre o gerenciamento de espaços de trabalho, consulte Gerenciar espaços de trabalho.

As seguintes bandeiras estão disponíveis:

bandeira	Descrição
`--session-id`	Filtrar por ID da sessão.
`--execution-id`	Filtre por ID de execução.
`--source`	Filtre por sandbox de origem: `agent` ou `tool`. Aceita uma lista separada por vírgula ou espaço.
`--level`	Nível de registro para corresponder exatamente: `debug`, `info`, `warn` ou `error`. Aceita uma lista separada por vírgula ou espaço.
`--grep`	Pesquisa de substring sem distinção entre maiúsculas e minúsculas em mensagens de registro. Não é um global ou regex.
`--since`	Hora de início como uma duração (por exemplo, `30m`, `2h`) ou carimbo de data/hora RFC3339. O padrão é `1h`. Máximo de `6h`.
`--until`	Hora de término como duração ou carimbo de data/hora RFC3339. O padrão é agora.
`--tail`	Número máximo de entradas mais recentes a serem retornadas. O padrão é `500`. Limite de `5000`, mas você pode usar `--all` para recuperar todas as entradas de registro no intervalo de tempo.
`--all`	Buscar todos os registros no intervalo de tempo, paginando automaticamente em todas as páginas.
`-f`, `--follow`	Pesquisa contínua de novos registros.
`--json`	Registros de saída como JSON em vez de formato legível por humanos.
`--workspace-id`	ID do espaço de trabalho a ser segmentado. Deve ser combinado com `--project-id`, `--org-id` e `--base-url` ou usado em um diretório com um espaço de trabalho registrado.
`--project-id`	ID do projeto. Usado com `--workspace-id`.
`--org-id`	ID da organização. Usado com `--workspace-id`.
`--base-url`	URL base da plataforma . Usado com `--workspace-id`.
`--workspace`	Em um monorepo, seleciona um espaço de trabalho específico pelo nome da raiz `agent.yaml`.
`--context`	Destino de plataforma nomeado para usar em vez de um ID de espaço de trabalho. Execute `agentengine context list` para ver seus contextos disponíveis.

Exemplos

Esta seção fornece exemplo de comandos CLI para tarefas comuns de recuperação de registro.

O comando a seguir recupera registros da última hora:

agentengine logs

O comando a seguir acompanha os registros ativos conforme eles são gravados:

agentengine logs --follow

O comando a seguir recupera apenas registros de nível de erro do serviço de sandbox do agente :

agentengine logs --source agent --level error

O comando a seguir procura uma substring nos registros dos últimos 30 minutos:

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

O comando a seguir recupera todos os registros das últimas seis horas:

agentengine logs --all --since 6h

Exportar registros brutos de tempo de execução

Para visualizar os registros de tempo de execução por um período superior a seis horas, você pode exportar os registros brutos do serviço do agente ou da ferramenta. Os registros exportados incluem até 24 horas de dados, e você pode baixá-los como um arquivo JSON Lines compactado com gzip.

Usar a IU

Para exportar registros de tempo de execução brutos da UI, execute as seguintes etapas:

Selecione Workspaces na barra de navegação à esquerda e clique no espaço de trabalho que deseja visualizar.
Clique na guia Logs para abrir um visualizador de registro interativo.
Clique em Export para abrir a caixa de diálogo de exportação bruta.
No menu suspenso Service, selecione Agent ou Tool.
No menu suspenso Time period, selecione um intervalo predefinido das horas 6, 12 ou 24 anteriores, ou especifique um intervalo personalizado. Um intervalo personalizado não pode exceder 24 horas. Em seguida, escolha seu zona horário no menu suspenso Time zone.
Clique em Export para baixar o arquivo de log.

Usar a CLI

Use o seguinte comando da CLI para exportar registros de tempo de execução brutos:

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

As seguintes bandeiras estão disponíveis:

bandeira	Descrição
`--service`	(Obrigatório) Serviço de tempo de execução para exportação. Você pode especificar `agent` ou `tool`.
`--since`	Hora de início, que você pode passar como uma duração ou um carimbo de data/hora RFC3339. O padrão é `24h`. O intervalo entre os valores `--since` e `--until` não pode exceder 24 horas.
`--until`	Hora de término como duração ou carimbo de data/hora RFC3339. O padrão é a hora atual.
`-o`, `--output`	Caminho do arquivo de saída. O padrão é `agent-logs-<service>-<end-time>.jsonl.gz`. O comando não substitui um arquivo existente neste caminho.
`--workspace-id`	ID do espaço de trabalho a ser segmentado. Deve ser combinado com `--project-id`, `--org-id` e `--base-url` ou usado em um diretório com um espaço de trabalho registrado.
`--project-id`	ID do projeto. Usado com `--workspace-id`.
`--org-id`	ID da organização. Usado com `--workspace-id`.
`--base-url`	URL base da plataforma . Usado com `--workspace-id`.
`--workspace`	Em um monorepo, seleciona um espaço de trabalho específico pelo nome da raiz `agent.yaml`.
`--context`	Destino de plataforma nomeado para usar em vez de um ID de espaço de trabalho. Execute `agentengine context list` para ver seus contextos disponíveis.

O comando grava o download atomicamente, portanto, uma exportação malsucedida ou interrompida não deixa um arquivo parcial no destino.

O comando a seguir exporta as 24 horas anteriores dos registros de serviço do agente :

agentengine logs export --service agent

O comando a seguir exporta seis horas de registros de serviço de ferramentas para um arquivo especificado:

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

Formato de registro

As sandboxes do agente emitem registros como registros JSON estruturados. A tabela a seguir descreve os campos em cada registro:

Campo	Descrição
`timestamp`	Carimbo de data/hora ISO 8601 que indica quando o registro foi emitido
`level`	Nível de gravidade do registro, como `DEBUG`, `INFO`, `WARNING` ou `ERROR`
`logger`	Nome do registrador Python que emitiu o registro
`message`	Texto da mensagem de registro legível para humanos
`service`	Origem do registro, que pode ser `agent` ou `tool`
`tenantId`	Identificador para o locatário que possui o agente em execução
`workspaceId`	Identificador para o espaço de trabalho onde o agente está distribuído
`executionId`	Identificador para a execução atual do agente
`sessionId`	Identificador para a sessão atual
`podName`	Nome do pod do Kubernetes do container que emitiu o registro
`source`	Fluxo que produz a entrada de registro, que pode ser `stdout` ou `stderr`
`fields`	Mapa de pares de chave-valor contendo metadados estruturados sobre o evento de registro

O exemplo a seguir mostra o formato de um único registro de log estruturado:

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

Exibir eventos de sistema

O Mecanismo de Agente do MongoDB Atlas registra um log de evento estruturado para cada implantação, capturando cada transição de estado, da criação à conclusão. Você pode usar o registro de evento de implantação para rastrear o comportamento da implantação, investigar falhas e verificar se ocorreram as transições esperadas do ciclo de vida. Você pode acessar o registro de evento usando a UI da plataforma, a CLI ou a API.

Cada evento contém os seguintes campos:

Campo	Descrição
`category`	A categoria ou estágio da transição do ciclo de vida que acionou o evento. Os valores possíveis são: `lifecycle`, `secret_sync`, `cr_create`, `oe_rollout`, `aer_rollout`, `tool_pod_rollout`, `memory_rollout`, `deploy_diagnostic` e `post_deploy_health`.
`component`	O componente de implementação associado ao evento.
`reason`	Um código de razão legível por máquina para o evento.
`message`	Uma descrição legível por humanos do evento.
`condition_ref`	A condição associada ao evento, como `Available` ou `SecretsReady`.

Usar a IU

A UI da plataforma mostra uma guia Registro de eventos na página Implementação para todas as implantações, ativas e concluídas.

Para implantações ativas, que são pending, in_progress ou cleaning_up, os eventos são transmitidos em tempo real por meio do SSE.
Para sistemas concluídos, o cartão carrega o histórico completo de evento do endpoint REST.

Cada linha de evento exibe o carimbo de data/hora UTC, nível de gravidade (info, success, warn ou error), estágio do ciclo de vida, componente e mensagem. Você pode filtrar eventos por nível e por estágio para restringir a visualização.

Usar a CLI

Para exibir o registro de evento de um sistema específico, use o comando agentengine deploy logs. Para saber mais, consulte Exibir registro de eventos de sistema.

Você também pode transmitir eventos em tempo real durante uma implantação ativa usando o sinalizador -f com agentengine deploy get. Para saber mais, consulte Verificar o status do sistema.

Usar a API

Para consultar eventos de sistema diretamente, use o seguinte endpoint da API:

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

Os resultados são paginados usando um cursor. Utilize os parâmetros de consulta after e limit para controlar a paginação. limit tem como padrão 100 e não pode exceder 100.

Verificar a integridade do espaço de trabalho

Após o sucesso de uma implementação, você pode verificar a integridade do seu agente implementado a qualquer momento. A visualização de integridade do espaço de trabalho mostra a prontidão atual de cada componente do agente , o número de réplicas prontas e um carimbo de data/hora que indica quando a integridade foi verificada pela última vez.

Usar a IU

A página de visão geral do espaço de trabalho na interface do usuário da plataforma inclui um cartão de integridade do sistema ativo. O cartão mostra a integridade por componente, incluindo status, réplicas prontas e motivo. Você pode clicar em Atualizar para buscar novamente a integridade atual a qualquer momento. Um carimbo de data/hora da última vez mostra quando a integridade foi recuperada pela última vez.

Usar a CLI

Para visualizar a integridade ao vivo do seu agente implementado, execute o seguinte comando:

agentengine status

O comando chama o endpoint de integridade do espaço de trabalho e renderiza os resultados como um resumo, conforme mostrado no exemplo a seguir:

✓ 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]

Passe o sinalizador --verbose para incluir detalhes adicionais de implantação e tempo de execução ou passe --json para gerar o status completo como JSON.

Ver negações da política

A página Observability na interface do usuário da plataforma inclui um bloco Policy denials. O bloco mostra quantas chamadas o Mecanismo de Política negado em uma janela de tempo que você seleciona. Você pode usar o bloco para localizar agentes que uma política bloqueia repetidamente, o que indica que o agente tentou um trabalho não autorizado ou que uma política é muito restritiva para o volume de trabalho. O bloco mostra dados apenas da sua organização e projetos.

O bloco conta as negações que o tipo de política AUTHORIZED_TOOLS produz e as negações que as políticas de execução e orçamento de sessão produzem. O bloco não conta as negações que o tipo de política AUTHORIZED_MODELS produz. Para saber mais sobre cada tipo de política, consulte Tipos de política.

Visualizar registros de depuração CLI

Cada comando agentengine grava um arquivo de log JSON estruturado em um diretório específico da plataforma em sua máquina. A CLI mantém os arquivos de log mais recentes do 20. Quando um comando não é bem-sucedido, a linha final stderr inclui o caminho para o arquivo de log desse comando.

A tabela a seguir lista os locais de registro por plataforma:

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

Para substituir o caminho do arquivo de log , use o sinalizador --log-file ou a variável de ambiente AGENTENGINE_LOG_FILE. As seguintes variáveis de ambiente também controlam o comportamento de registro:

AGENTENGINE_LOG_LEVEL define a verbosidade do arquivo
AGENTENGINE_NO_LOG desabilita o registro de arquivos
AGENTENGINE_LOG_MAX_FILES define o número de arquivos de log retidos
AGENTENGINE_NO_LOG_PRUNE desabilita a remoção automática da retenção

Listar arquivos de log CLI

Para listar todos os arquivos de log CLI, ordenados pelos mais recentes primeiro, execute o seguinte comando:

agentengine debug logs list [--json]

Cada linha mostra o nome do arquivo e o comando que foi executado. Passe o sinalizador --json para receber um objeto legível por máquina com schema_version, status e uma array logs. Cada entrada na array inclui name, path, modified_at, size_bytes e command.

Visualizar um arquivo de log CLI

Para imprimir o conteúdo de um arquivo de log, execute o seguinte comando:

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

Passe o nome do arquivo de log mostrado por agentengine debug logs list ou use --last para imprimir o registro mais recente. A saída é formatada como linhas JSON brutas por padrão. Passe o sinalizador --pretty para formatar e personalizar cada registro.

O exemplo seguinte utiliza os comandos agentengine debug logs para listar e visualizar arquivos de log:

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

Recursos adicionais

Para saber mais sobre os endpoints da API discutidos neste guia, consulte a documentação da API.

Voltar

Permissões de função do Atlas

Inspecionar rastreamentos de execução do agente