Monitor the Agent

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Monitor the Agent

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

Overview

In this guide, you can learn how to monitor your agent's performance and your deployment's health.

Agent sandboxes produce logs during execution that you can use to monitor agent behavior and diagnose issues. You can retrieve these logs in the following ways:

• [Use the API or CLI agent logs](https://www.mongodb.com/docs/agentengine/manage/monitor.md#std-label-agent-engine-monitor-runtime-logs: Retrieve agent runtime logs including stdout/stderr output, print() statements, and framework debug output.

• [Use the API for deployment event logs](https://www.mongodb.com/docs/agentengine/manage/monitor.md#std-label-agent-engine-monitor-deploy-events: Access structured deployment event logs to trace deployment behavior, investigate failures, and verify lifecycle transitions.

To check the [live health of your deployed agent](https://www.mongodb.com/docs/agentengine/manage/monitor.md#std-label-agent-engine-monitor-workspace-health, use the agentengine status command or the workspace health card in the Atlas Agent Engine UI.

To debug latency or unexpected behavior in a specific agent run, see [Inspect Agent Execution Traces.](https://www.mongodb.com/docs/agentengine/manage/inspect-traces.md#std-label-agent-engine-inspect-traces

To learn how to view usage and health metrics for your project and workspaces, see [Monitor Your Agents in the Atlas Agent Engine UI.](https://www.mongodb.com/docs/agentengine/manage/monitoring-ui.md#std-label-agent-engine-monitoring-ui

View Agent Runtime Logs

The MongoDB Atlas Agent Engine captures stdout/stderr output, print() statements, logging calls, and framework debug output from your deployed agents and stores them in S3. You can retrieve these logs by using the Atlas Agent Engine UI, the API, or the CLI.

Use the UI

To view logs on the UI, perform the following steps:

1. Select Workspaces from the left navigation bar and click the workspace you want to view.

2. Click the Logs tab to open an interactive log viewer.

3. Adjust the period of time you want to view by selecting the 15m, 1h, or 6h button. You can also change the time zone by using the time zone selector. To view logs for a longer period of time, use the [log export feature.](https://www.mongodb.com/docs/agentengine/manage/monitor.md#std-label-agent-engine-monitor-log-export

4. Select options from the Level, Source, and Service dropdown menus to filter the logs. Then, click Search to apply the filters. Level and source filters return exact matches, so selecting INFO returns only INFO entries, not INFO and higher severities.

Use the API

Query agent runtime logs by using the following endpoint:

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

Pass the object ID of the project to query as the {id} value. The caller must belong to that project's organization.

The following query parameters are available:

Results are paginated by using a cursor. Each response includes a nextCursor field, unless the response is the last page, and a hasMore boolean. To retrieve the following page, pass the value of nextCursor as the cursor parameter in your next request.

Each log entry in the logs array contains the following fields:

Use the CLI

Use the following CLI command to retrieve agent runtime logs:

agentengine logs [flags]

The command resolves the workspace from the current directory's .agentengine/ state file. To target a different workspace, pass either the --context flag with a named context, or pass the --workspace-id flag together with --project-id, --org-id, and --base-url. For more information about managing workspaces, see [Manage Workspaces.](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-workspaces

The following flags are available:

Examples

This section provides example CLI commands for common log retrieval tasks.

The following command retrieves logs from the last hour:

agentengine logs

The following command tails live logs as they are written:

agentengine logs --follow

The following command retrieves only error-level logs from the agent sandbox service:

agentengine logs --source agent --level error

The following command searches for a substring in logs from the last 30 minutes:

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

The following command retrieves all logs from the last six hours:

agentengine logs --all --since 6h

Export Raw Runtime Logs

To view runtime logs for a period longer than six hours, you can export the raw logs for either the agent or tool service. Exported logs include up to 24 hours of data, and you can download them as a gzip-compressed JSON Lines file.

Use the UI

To export raw runtime logs from the UI, perform the following steps:

1. Select Workspaces from the left navigation bar and click the workspace you want to view.

2. Click the Logs tab to open an interactive log viewer.

3. Click Export to open the raw export dialog.

4. From the Service dropdown menu, select Agent or Tool.

5. From the Time period dropdown menu, select a preset range of the previous 6, 12, or 24 hours, or specify a custom range. A custom range cannot exceed 24 hours. Then, choose your time zone from the Time zone dropdown menu.

6. Click Export to download the log file.

Use the CLI

Use the following CLI command to export raw runtime logs:

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

The following flags are available:

The command writes the download atomically, so an unsuccessful or interrupted export does not leave a partial file at the destination.

The following command exports the previous 24 hours of agent service logs:

agentengine logs export --service agent

The following command exports six hours of tool service logs to a specified file:

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

Log Format

Agent sandboxes emit logs as structured JSON records. The following table describes the fields in each record:

The following example shows the format of a single structured log record:

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

View Deployment Events

The MongoDB Atlas Agent Engine records a structured event log for each deployment, capturing every state transition from creation through completion. You can use the deploy event log to trace deployment behavior, investigate failures, and verify that expected lifecycle transitions occurred. You can access the event log by using the Atlas Agent Engine UI, the CLI, or the API.

Each event contains the following fields:

Use the UI

The Atlas Agent Engine UI shows an Event Log tab on the Deployment page for all deployments, both active and completed.

• For active deployments, which are pending, in_progress, or cleaning_up, events stream in real time through SSE.

• For completed deployments, the card loads the full event history from the REST endpoint.

Each event row displays the UTC timestamp, severity level (info, success, warn, or error), lifecycle stage, component, and message. You can filter events by level and by stage to narrow the view.

Use the CLI

To view the event log for a specific deployment by, use the agentengine deploy logs command. To learn more, see [View Deployment Event Log.](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-logs

You can also stream events in real time during an active deployment by using the -f flag with agentengine deploy get. To learn more, see [Check Deployment Status.](https://www.mongodb.com/docs/agentengine/deploy/deploy-build.md#std-label-agent-engine-deploy-build-status

Use the API

To query deployment events directly, use the following API endpoint:

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

Results are paginated by using a cursor. Use the after and limit query parameters to control pagination. limit defaults to 100 and cannot exceed 100.

Check Workspace Health

After a deployment succeeds, you can check the live health of your deployed agent at any time. The workspace health view shows the current readiness of each agent component, the number of ready replicas, and a timestamp indicating when the health was last checked.

Use the UI

The workspace overview page in the Atlas Agent Engine UI includes a Live Deployment Health card. The card shows per-component health, including status, ready replicas, and reason. You can click Refresh to re-fetch the current health at any time. A Last checked at timestamp shows when the health was last retrieved.

Use the CLI

To view the live health of your deployed agent, run the following command:

agentengine status

The command calls the workspace health endpoint and renders the results as a summary, as shown in the following example:

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

Pass the --verbose flag to include additional deployment and runtime details, or pass --json to output the full status as JSON.

View Policy Denials

The Monitoring page in the Atlas Agent Engine UI includes a Policy denials tile. The tile shows how many calls the [Policy Engine](https://www.mongodb.com/docs/agentengine/manage/governance/policy-engine.md#std-label-agent-engine-policy-engine denied over a time window that you select. You can use the tile to find agents that a policy blocks repeatedly, which indicates that the agent attempted unauthorized work or that a policy is too restrictive for the workload. The tile shows data for your organization and projects only.

The tile counts the denials that the AUTHORIZED_TOOLS policy type produces and the denials that the execution and session budget policies produce. The tile does not count the denials that the AUTHORIZED_MODELS policy type produces. To learn more about each policy type, see [Policy Types.](https://www.mongodb.com/docs/agentengine/manage/governance/policy-engine.md#std-label-agent-engine-policy-types

To learn more about the Monitoring page, see [Monitor Your Agents in the Atlas Agent Engine UI.](https://www.mongodb.com/docs/agentengine/manage/monitoring-ui.md#std-label-agent-engine-monitoring-ui

View CLI Debug Logs

Every agentengine command writes a structured JSON log file to a platform-specific directory on your machine. The CLI retains the 20 most recent log files. When a command is unsuccessful, the final stderr line includes the path to the log file for that command.

The following table lists the log locations by platform:

To override the log file path, use the --log-file flag or the AGENTENGINE_LOG_FILE environment variable. The following environment variables also control logging behavior:

• AGENTENGINE_LOG_LEVEL sets file verbosity

• AGENTENGINE_NO_LOG disables file logging

• AGENTENGINE_LOG_MAX_FILES sets the number of retained log files

• AGENTENGINE_NO_LOG_PRUNE disables automatic retention pruning

List CLI Log Files

To list all CLI log files, sorted by most recent first, run the following command:

agentengine debug logs list [--json]

Each row shows the filename and the command that was run. Pass the --json flag to receive a machine-readable object with schema_version, status, and a logs array. Each entry in the array includes name, path, modified_at, size_bytes, and command.

View a CLI Log File

To print the contents of a log file, run the following command:

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

Pass the log filename shown by agentengine debug logs list, or use --last to print the most recent log. The output is formatted as raw JSON lines by default. Pass the --pretty flag to format and colorize each record.

The following example uses the agentengine debug logs commands to list and view log files:

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

Additional Resources

To learn more about the API endpoints discussed in this guide, see the API documentation.