investigating-incidents-with-aws-devops-agent

Investigate an AWS incident

AgentSpace routing (SigV4 only): If list_agent_spaces is available in your tool list and the multi-space orchestration skill has NOT been invoked yet this session, invoke it first to determine which agent_space_id to use. Then pass agent_space_id on all tool calls below. For bearer token auth this is unnecessary — the token is already scoped to one space.

Use this when the user is reporting or describing an operational problem that needs deep async analysis (5–8 minutes of agent work). For fast questions about cost, architecture, or topology, use the chatting-with-aws-devops-agent skill instead.

Pre-flight

Before starting an investigation, gather local context and pack it into the title parameter. This is the killer feature — the DevOps Agent knows your AWS cloud; you know the user's local workspace.

Always collect:

• Service identity from package.json / pom.xml / Cargo.toml / requirements.txt / Makefile
• git log --oneline -10 (recent commits — agent correlates deploys to incidents)
• git diff --stat (uncommitted work that might be relevant)

When investigating errors, also include:

• The full stack trace or relevant log excerpt
• Any IaC files relevant to the failing resource (CDK / CloudFormation / Terraform / ECS task def)

Start the investigation

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."
)
→ {"status": "investigation_started", "taskId": "...", "executionId": "...", "message": "...", "next_steps": "..."}

Save the taskId and executionId.

Tip: Pack as much context as possible into the title — service name, error type, time window, recent deploys. The agent uses this to scope its analysis.

Stream progress — never silently poll

Investigations take 5–8 minutes. Tell the user up front, then keep them informed.

Loop every 30–45 seconds: