Troubleshooting agent
When receiving an alert from Monte Carlo, the troubleshooting agent can automatically work through 100s of hypothesis and highlight the ones that are most likely to have caused the issue. It will consider changes in the data, system issues (e.g. Airflow or dbt failures) and code changes when analyzing an alert, and will automatically traverse lineage to identify the root cause.
Troubleshooting agent analysis
Agent context
The agent relies on the same metadata, query logs, and metrics collected from various integrations for monitoring in order to quickly rule out or further investigate many hypotheses of root cause. The optimal conditions for the agent are data warehouses and lakehouses with data sampling enabled, full lineage instrumentation, query history, and active integrations like GitHub, GitLab, dbt, Databricks Workflows, and Airflow.
Agent investigations & hypotheses
Below are a few examples of investigation paths that the agent can perform.
| Type | Hypothesis investigated |
|---|---|
| Row count changes | Has there been similar row count changes upstream? |
| Query changes | Was there a query that usually runs that was modified? |
| Job failure | Has a dbt model, Databricks job, or Airflow DAG failed? |
| Failed queries | Did a query that usually runs fail/error? |
| Missing query | Is a query that usually runs missing in the logs? |
| Non-writing query | Is a query that usually writes or updates data writing zero updates? |
| Additional query | Did a query that hasn't been seen before run? |
| Validation failure | Has a validation on this asset recently failed? |
| Pull requests | Was there a recent pull request? |
| Data analysis | Are there underlying correlations in the data of affected records? (Currently only available for cloud Deployments) |
Accessing the Troubleshooting Agent
In the Monte Carlo UI
The Troubleshooting Agent is available from multiple surfaces:
- Alert detail page -- The agent is embedded directly in the alert page. Click Troubleshoot to start an investigation.
- Slack -- Click the Troubleshoot alert button on any Monte Carlo Slack alert notification to trigger the agent. Results are posted in the alert thread with a link to open full findings in Monte Carlo.
- Operations Agent -- Ask the Operations Agent to "troubleshoot this alert" and it routes to the Troubleshooting Agent automatically.
Via the Agent Toolkit (MCP)
The analyze-root-cause skill in the Agent Toolkit exposes the Troubleshooting Agent through AI coding agents like Claude Code and Cursor.
Agent instructions
You can provide instructions to the agent in Settings > AI Agents.
Access control
Two different permissions apply to the Troubleshooting Agent, and they are deliberately distinct:
- May run the agent —
ai-agents/troubleshooting/access. Governs who can run the Troubleshooting Agent on alerts and view its analyses. Every built-in role grants it by default, including Viewers. Users without it see the Troubleshoot controls disabled and cannot view analyses. - May administer its settings —
settings/ai-agents/access(read) andsettings/ai-agents/edit(write). Govern who can open Settings > AI Agents and view or change the agent's configuration, including its instructions and usage restrictions. This is separate from running the agent: a user can run it without being able to reconfigure it, or vice versa.
To restrict the agent — for example, to limit running it to a specific team, to scope a team to only the alerts on the assets they own, or to control who may administer its settings — see Controlling access to the AI agents in the custom role recipes.
Preview caveats
During the preview phase, the following monitor alert types are not yet supported:
- Comparison
- Merged alerts
FAQ
How do I restrict access to the Troubleshooting Agent?
Running the agent is controlled by the ai-agents/troubleshooting/access permission, which every built-in role grants by default (including Viewers). To take it away from a group of users — or limit it to a specific team — combine a custom role that denies the permission with your authorization groups. To control who may instead administer the agent's settings in Settings > AI Agents, restrict the settings/ai-agents permissions — a separate lever. See Access control above, and the Controlling access to the AI agents recipe for the exact policy (deny both settings/ai-agents/access and settings/ai-agents/edit, not the wildcard).
Security & data privacy
For more detail on security and data privacy, see the AI Features and Technical Information documentation.
Feedback
Have feedback or requests on the troubleshooting agent? Reach out via our Support Agent.
Updated 11 days ago