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

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 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. 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.

# 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, pom.xml, 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

# 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.

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.

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").

# 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.

--- 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}