# How to Use the AWS DevOps Agent for Incident Investigation: MCP Workflow Guide

> Learn to use the AWS DevOps Agent for incident investigation. This MCP-enabled AI engine automates root-cause analysis across CloudWatch, X-Ray, and logs for efficient problem solving.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-26

---

**The AWS DevOps Agent is an MCP-enabled AI engine that automates root-cause analysis by querying CloudWatch, X-Ray, and deployment logs, delivering structured findings through a journal-based polling interface.**

The AWS DevOps Agent operates as a sandboxed investigative engine within the AWS MCP Server, providing autonomous incident analysis for AWS infrastructure. According to the `aws/agent-toolkit-for-aws` repository, this agent follows a strict skill-based workflow defined in [`investigating-incidents-with-aws-devops-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/investigating-incidents-with-aws-devops-agent/SKILL.md) to correlate logs, traces, and recent deployments without manual AWS CLI navigation.

## Configure the DevOps Agent Environment

Before initiating investigations, configure credentials using the `setup-devops-agent` command defined in [`plugins/aws-agents-for-devsecops/commands/setup-devops-agent.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/commands/setup-devops-agent.md). The agent supports **Bearer token** or **SigV4** authentication.

For multi-account environments, the agent uses **AgentSpace routing** to select the correct `agent_space_id`. When multiple spaces exist, invoke `list_agent_spaces` to identify the target account and region context before starting the investigation.

```bash

# Install the DevOps Agent plugin (Claude Code example)

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-agents-for-devsecops
/reload-plugins

# Configure credentials (run once per workspace)

aws-agents-for-devsecops:setup

```

## Compile the Investigation Context

The DevOps Agent requires a structured `title` parameter embedding the service name, error type, time window, and recent deployment identifiers. Gather local repository state to provide this context:

- Service manifest ([`package.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/package.json), [`pom.xml`](https://github.com/aws/agent-toolkit-for-aws/blob/main/pom.xml), [`requirements.txt`](https://github.com/aws/agent-toolkit-for-aws/blob/main/requirements.txt))
- Last 10 Git commits (`git log --oneline -10`)
- Uncommitted changes (`git diff --stat`)
- Relevant IaC files (CDK, CloudFormation, Terraform, ECS task definitions)
- Stack trace or log excerpt triggering the investigation

```bash

# Generate a descriptive incident title

SERVICE=$(jq -r .name package.json)
COMMITS=$(git log --oneline -10 | head -n1)
DIFF_COUNT=$(git diff --stat | wc -l)
TITLE="${SERVICE} outage – ${COMMITS} – ${DIFF_COUNT} uncommitted changes, 503 errors since deployment 2h ago"

```

## Initiate the Investigation

Call `aws_devops_agent__investigate()` with the compiled title. The function returns a `taskId` and `executionId` that uniquely identify the investigation session, as documented in [`plugins/aws-agents-for-devsecops/commands/investigate.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/commands/investigate.md).

```python
response = aws_devops_agent__investigate(
    title="ECS 503 errors on checkout-service since commit abc1234 deployed 2h ago. CDK: ECS Fargate behind ALB. Error: upstream connect error."
)

# Returns: {"status": "investigation_started", "taskId": "t-123", "executionId": "e-456"}

```

## Monitor Progress via Journal Records

Poll the investigation status every 30-45 seconds using `aws_devops_agent__get_task(task_id="TASK_ID")`. While status remains `IN_PROGRESS`, stream new journal records via `aws_devops_agent__list_journal_records(execution_id="EXEC_ID", order="ASC")`.

The agent categorizes each journal record by type: **PLANNING**, **SEARCHING**, **ANALYSIS**, **FINDING**, **ACTION**, **SUMMARY**, and **SUGGESTION**. Surface these to users with appropriate indicators (📋, 🔍, 🔬, 🎯, 🔧, 📊, 💡) for transparent progress tracking.

```python
import time

task_id = "t-123"
exec_id = "e-456"

while True:
    status = aws_devops_agent__get_task(task_id=task_id)
    if status["task"]["status"] == "COMPLETED":
        break

    records = aws_devops_agent__list_journal_records(
        execution_id=exec_id, order="ASC", next_token=next_token
    )
    for rec in records["records"]:
        print(f"{rec['type']}: {rec['message']}")
    time.sleep(35)

```

## Extract Findings and Remediation

When the task reaches `COMPLETED`, retrieve the final findings using `aws_devops_agent__list_journal_records` with `order="DESC"`. Then pull actionable remediation items via `aws_devops_agent__list_recommendations(task_id="TASK_ID")`.

```python

# Fetch final journal entries

final_records = aws_devops_agent__list_journal_records(
    execution_id="e-456", order="DESC", limit=10
)

# Retrieve recommendations

recommendations = aws_devops_agent__list_recommendations(task_id="t-123")
for rec in recommendations["recommendations"]:
    detail = aws_devops_agent__get_recommendation(recommendation_id=rec["id"])

```

## Review IaC Changes Before Application

Remediation recommendations may include Infrastructure-as-Code snippets (CDK, CloudFormation, Terraform). **Never auto-apply** these changes. Generate a local diff and present it for user approval before executing any `aws devops-agent apply` commands.

```diff
--- a/lib/ecs-stack.ts
+++ b/lib/ecs-stack.ts
@@ -42,7 +42,7 @@
   memoryLimitMiB: 512,
-  cpu: 256,
+  cpu: 512,
   ...

```

If the MCP endpoint becomes unavailable, the skill automatically falls back to native AWS CLI commands (`aws devops-agent …`) as specified in the fallback path of [`SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/SKILL.md).

## Summary

- The AWS DevOps Agent runs as a sandboxed Python script inside the AWS MCP Server, using the Model Context Protocol for secure AWS API access.
- Investigations require a structured `title` parameter and return `taskId`/`executionId` for tracking.
- Monitor ongoing analysis by polling `aws_devops_agent__get_task` and streaming `aws_devops_agent__list_journal_records` every 30-45 seconds.
- Final results include categorized journal records and actionable recommendations that may contain IaC changes.
- Always require explicit user approval before applying any infrastructure modifications suggested by the agent.

## Frequently Asked Questions

### What happens if the MCP endpoint is unavailable during an investigation?

The skill automatically falls back to native AWS CLI commands using the `aws devops-agent …` syntax. This fallback path is defined in the **Fallback path** section of [`investigating-incidents-with-aws-devops-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/investigating-incidents-with-aws-devops-agent/SKILL.md), ensuring investigations can continue even when the MCP server connection drops.

### How does the AWS DevOps Agent handle multi-account investigations?

When using SigV4 authentication, the agent leverages **AgentSpace routing**. Call `list_agent_spaces` to enumerate available spaces and select the appropriate `agent_space_id` that corresponds to the target AWS account and region. This ensures the investigation executes within the correct organizational context.

### What types of journal records does the agent generate during analysis?

The agent produces seven distinct record categories: **PLANNING** (orchestration strategy), **SEARCHING** (log and trace queries), **ANALYSIS** (correlation of findings), **FINDING** (identified issues), **ACTION** (remediation steps taken), **SUMMARY** (synthesized results), and **SUGGESTION** (recommendations for prevention). Each record includes a timestamp and message for complete audit trails.

### Can the AWS DevOps Agent automatically apply remediation recommendations?

No. While the agent generates detailed remediation recommendations that may include IaC snippets, the workflow explicitly requires manual review. You must generate a local diff and obtain user approval before applying any changes. According to the source skill definition, auto-application is blocked by design to prevent unintended infrastructure modifications.