Multi-Agent Workflows

Overview

When you ask a question in free-form AI Chat, OpsWorker coordinates several AI agents to gather information from different sources. Agents are selected automatically based on your question and the integration capabilities connected for the cluster and org.

How It Works

Free-form Chat runs a three-stage flow:

Tool router (Amazon Nova) prefilters the full tool set down to the tools relevant to your question, keeping the orchestrator focused and fast.
Orchestrator agent reasons about the question and delegates work to sub-agents through an invoke_agent tool.
Sub-agents each own a domain (cluster reads, source code, metrics, optimization, diagrams) and return their findings to the orchestrator, which synthesizes the final answer.

flowchart TD
    Q[Your question] --> TR[Tool router - Amazon Nova]
    TR --> Orch[Orchestrator agent]
    Orch -->|invoke_agent| Inv[investigate]
    Orch -->|invoke_agent| Val[validate_resources]
    Orch -->|invoke_agent| Dep[check_dependencies]
    Orch -->|invoke_agent| Logs[analyze_logs]
    Orch -->|invoke_agent| SC[source_code]
    Orch -->|invoke_agent| RO[resource_optimizer]
    Inv --> Combine[Synthesize answer]
    Val --> Combine
    Dep --> Combine
    Logs --> Combine
    SC --> Combine
    RO --> Combine
    Combine --> Answer[Answer with diagrams and charts]

Capability Gating

Each sub-agent requires one or more integration capabilities. The capability tokens are cluster, sourcecontrol, and metrics. The orchestrator can only invoke sub-agents whose capabilities are connected for the cluster and org; the rest are shown as unavailable with their missing_capabilities listed.

Sub-agent	Purpose	Required capabilities
`investigate`	Discover and reason about affected resources	`cluster`
`validate_resources`	Verify resource existence, state, and config	`cluster`
`check_dependencies`	Map upstream/downstream service dependencies	`cluster`
`analyze_logs`	Search and interpret pod/container logs	`cluster`
`source_code` (Source Code & Repository Agent)	Read commits, PRs/MRs, and file contents	`sourcecontrol`
`resource_optimizer`	Right-sizing and cost recommendations	`cluster` + `metrics`

The cluster capability comes from the installed Kubernetes Agent, sourcecontrol from a GitHub or GitLab integration, and metrics from the Grafana MCP integration (Prometheus via a Grafana datasource).

Diagram Generation

Alongside the data sub-agents, Chat can auto-generate Mermaid topology and flow diagrams (for example, "draw me a diagram of the payment flow") and auto-charts Prometheus time-series results inline, so answers include visuals, not just text.

Example: Multi-Source Investigation

Question: "Why is the api-gateway service slow?"

The orchestrator may invoke:

investigate / analyze_logs (cluster): Checks pod status, resource utilization, events, and logs for error patterns.
resource_optimizer (cluster + metrics): Runs Prometheus queries through Grafana MCP for latency percentiles and request rates, and flags under- or over-provisioning.
source_code (sourcecontrol): Checks recent commits and merged PRs/MRs that may have introduced a regression.

The response synthesizes data from all invoked sub-agents into a coherent answer.

Agent Transparency

The portal shows which agents were invoked during each response:

Execution blocks: Each agent's activity is displayed, showing what tools were used and what data was retrieved
Tool calls: See the specific queries each agent ran (e.g., "get pods in namespace production")

This transparency helps you understand how the AI arrived at its answer and verify the data sources.

Agent Availability

Capability	Required Integration	Enabled By	Sub-agents it unlocks
`cluster`	Kubernetes Agent	Kubernetes Agent installed (core requirement)	`investigate`, `validate_resources`, `check_dependencies`, `analyze_logs`
`sourcecontrol`	GitHub or GitLab	GitHub or GitLab integration	`source_code`
`metrics`	Grafana MCP	Grafana MCP integration	`resource_optimizer` (with `cluster`)

note

The metrics capability requires the Grafana MCP integration (OpsWorker → Grafana query access for Prometheus). This is separate from Grafana Alerting (Grafana → OpsWorker alert webhook). See the Grafana Integration guide for details on both.

Read-Only with One Write Path

The cluster-facing sub-agents are read-only: Chat never executes kubectl mutations. The only way Chat proposes a change is when the source_code or resource_optimizer agent opens a Git pull request / merge request, which a human reviews and merges.

Within a conversation, agents share context:

Data gathered by one agent is available to others in the same session
Follow-up questions build on previous answers
The AI maintains awareness of which resources and namespaces have been discussed

Next Steps

AI Agents Overview: Learn about each agent
Example Prompts: Try multi-agent prompts

Overview​

How It Works​

Capability Gating​

Diagram Generation​

Example: Multi-Source Investigation​

Agent Transparency​

Agent Availability​

Read-Only with One Write Path​

Context Sharing​

Next Steps​