Documentation Grafana Cloud AI and machine learning Grafana Assistant Introduction Understand investigations

Understand Assistant investigations

Grafana Assistant Investigations coordinate multiple specialist agents to analyze incidents in parallel. Use this concept guide to understand how investigations differ from chat, what each agent does, and how Grafana Assistant structures reports.

Before you begin

• Investigations entitlement: Enable Grafana Assistant Investigations for your Grafana Cloud organization.
• Investigation access: Assign the Assistant Investigation User role if your organization uses RBAC.
• Incident context: Summarize the symptom, impact, and affected services before launching an investigation.

What investigations are

Investigations convert a single prompt into a structured workflow that specialist agents handle. Each agent runs targeted queries against metrics, logs, traces, or profiles, shares findings in a shared workspace, and contributes to a final report. The Assistant keeps you informed through chat updates while the investigation workspace manages long-running tasks in the background.

When to prefer investigations over chat

Stay in chat for quick questions or incremental troubleshooting. Launch an investigation when the issue spans multiple data sources or services, when you need agents to keep working while you coordinate the incident, or when you want a durable report that documents timelines, to-dos, and recommended actions.

Investigation lifecycle

1. Launch: Provide a detailed prompt that captures the incident summary, timeframe, and focus areas.
2. Agent execution: Investigation agents fan out across domains, including Prometheus metrics, Loki logs, Tempo traces, Pyroscope profiles, and SQL data sources, to gather evidence.
3. Updates: Chat messages summarize progress. You can steer agents with feedback or additional hints.
4. Report: Once agents finish, the investigation workspace compiles a structured summary, timeline, and recommended follow-ups.

Investigations track token usage separately from chat and respect the monthly tenant limits defined in Grafana Cloud.

Working with investigation reports

The Summary section delivers quick status updates and recommended next steps so you can brief stakeholders fast.

Expand the Report to read the full findings along with the queries and evidence each agent collected.

The Timeline records agent tasks in order, which helps during post-incident reviews, while the Activity log provides the raw events you need to reproduce a step.

When you are ready to communicate, ask the Assistant to convert the findings into incident updates, backlog items, or dashboard follow-ups.

Best practices

Launch prompts that include precise @ mentions so agents begin with the correct dashboards and data sources. While the investigation runs, offer feedback whenever a finding drifts from the scope to keep the agents focused. If the incident changes dramatically, start a new investigation; the fresh run captures the updated context without carrying assumptions forward.

Next steps

• Learn about Control Assistant data sources to understand how the Assistant connects to your telemetry.
• Try Run a systematic investigation to practice the investigation workflow.