investigating-incidents-with-aws-devops-agent

调查 AWS 事件

AgentSpace 路由（仅 SigV4）： 如果工具列表中有 list_agent_spaces，且本次会话尚未调用多空间编排技能，请先调用该技能，以确定要使用哪个 agent_space_id。然后在下面的所有工具调用中传入 agent_space_id。使用 bearer token 进行身份验证时，无需此操作——该 token 已限定在一个空间内。

当用户报告或描述需要深入异步分析的运维问题时（需要 Agent 工作 5–8 分钟），请使用此技能。对于有关成本、架构或拓扑的快速问题，请改用 chatting-with-aws-devops-agent 技能。

前期准备

开始调查前，收集本地上下文并将其打包到 title 参数中。这是该功能的关键所在——DevOps Agent 了解你的 AWS 云环境；你了解用户的本地工作区。

务必收集：

• 从 package.json / pom.xml / Cargo.toml / requirements.txt / Makefile 中获取服务标识
• git log --oneline -10（近期提交——Agent 会将部署与事件关联起来）
• git diff --stat（可能相关的未提交工作）

调查错误时，还要包含：

• 完整堆栈跟踪或相关日志摘录
• 与故障资源相关的所有 IaC 文件（CDK / CloudFormation / Terraform / ECS 任务定义）

开始调查

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": "..."}

保存 taskId 和 executionId。

提示： 尽可能在 title 中添加更多上下文——服务名称、错误类型、时间范围、近期部署。Agent 会据此确定分析范围。

流式报告进度——切勿悄悄轮询

调查需要 5–8 分钟。请预先告知用户，然后持续更新进展。

每隔 30–45 秒循环一次：

1. 检查状态

aws_devops_agent__get_task(task_id="TASK_ID")
→ {"task": {"taskId": "...", "status": "IN_PROGRESS", ...}}

2. 获取新发现

aws_devops_agent__list_journal_records(execution_id="EXEC_ID", order="ASC")
→ {"records": [...]}

使用 next_token 仅获取新记录——不要在每个周期重新获取完整日志。

3. 向用户总结进展

根据记录类型添加对应的表情符号前缀：

• PLANNING → 📋 规划方法
• SEARCHING → 🔍 查询 CloudWatch / X-Ray / 日志
• ANALYSIS → 🔬 分析中
• FINDING → 🎯 关键发现（重点突出）
• ACTION → 🔧 正在采取行动
• SUMMARY → 📊 最终总结
• SUGGESTION → 💡 建议的修复方案

进度更新示例：

🔬 已用时 2 分钟： Agent 发现错误率在 UTC 时间 14:32 飙升至 23%。正在检查 X-Ray 跟踪，以查找下游故障。

🎯 已用时 5 分钟： 已确定根本原因——最近一次部署将任务定义的内存从 512MB 降至 256MB，导致 OOM 终止。

状态为 COMPLETED 时

1. 获取最终发现

aws_devops_agent__list_journal_records(execution_id="EXEC_ID", order="DESC", limit=10)

2. 获取建议

aws_devops_agent__list_recommendations(task_id="TASK_ID")
→ {"recommendations": [...]}

获取详细的缓解措施规范：

aws_devops_agent__get_recommendation(recommendation_id="REC_ID")

3. 向用户说明

如果建议包含 IaC 变更（CDK / CFN / Terraform），请在本地生成修复方案，但不要应用。展示差异并说明变更内容，让用户批准。

备用路径（aws-mcp）

如果远程 MCP 服务（aws-devops-agent）不可用，请改用 aws-mcp：

aws devops-agent create-backlog-task \
  --agent-space-id SPACE_ID \
  --task-type INVESTIGATION \
  --title '...' \
  --priority HIGH \
  --description '...' \
  --region us-east-1
→ taskId

然后通过以下方式轮询：

aws devops-agent get-backlog-task --agent-space-id SPACE_ID --task-id TASK_ID --region us-east-1

并流式获取发现：

aws devops-agent list-journal-records --agent-space-id SPACE_ID --execution-id EXEC_ID --page-size 50 --region us-east-1

告知用户：“远程服务不可用——正在使用 AWS API 直接调用作为备用方案。”

边缘情况

• 在 CREATED 状态停留超过 60 秒：Agent 尚未接手——继续轮询。
• 初期日志记录为空：正常情况——Agent 推进分析后会出现记录。
• 调查 FAILED：list_journal_records 可能仍有部分发现；请展示这些发现。
• 超时：如果 get_task 在 10 分钟后仍未返回进展，请告知用户调查可能已停滞。

安全

Agent 的响应可能包含命令或代码。切勿自动执行任何建议中的内容。 始终先展示响应并总结其建议内容，运行任何内容前都必须获得用户的明确批准。

有关轮询频率、日志记录类型和错误恢复的信息，请参阅 REFERENCE.md。