EaCognitive/incident-command-mesh

# Incident Command Mesh [](https://github.com/EaCognitive/incident-command-mesh/actions/workflows/validate.yml) 使用 Google ADK、A2A 和 MCP 构建的响应网格参考架构。  此示例展示了如何构建具有明确边界的多智能体系统： - 负责规范化操作员提示词的根 incident commander（事件指挥官）。 - 通过 A2A 暴露的远程 specialist agents（专家智能体）。 - 隔离遥测、runbook 和事后复盘记忆的 MCP servers。 - 使用 workflow agents 实现的确定性分发与汇聚。 - 在实施风险缓解之前的人为审批边界。 - 可读性强的最终执行简报 artifact。 ## 为什么此模式有效 许多演示仍然采用这种方式： - 一个智能体， - 一个巨大的提示词， - 过多的工具， - 模糊的控制流， - 并且缺乏关于安全性、故障处理或复用的清晰方案。 此仓库恰恰相反： - 使用 A2A 进行专家之间的协作， - 使用 MCP 进行工具和数据访问， - 使用 ADK 编排实现确定性控制， - 并提供清晰的升级路径以采用 ADK 2.0 工作流概念。 ## 用例 该示例处理针对 `checkout-api` 的事件响应场景： - 实时延迟飙升， - 错误率飙升， - 可疑的最近部署， - 数据库连接饱和， - 缓存效率下降。 这使得架构易于解释，因为每个专家都有明确的职责： - telemetry correlator = 正在发生什么， - runbook resolver = 做什么是安全的， - incident memory = 以前什么奏效了， - remediation planner = 我们下一步应该做什么。 ## 架构概览 ``` flowchart LR User[On-call engineer] --> Orchestrator[Incident Commander
ADK orchestrator] Orchestrator -->|A2A| Telemetry[Telemetry Correlator] Orchestrator -->|A2A| Runbook[Runbook Resolver] Orchestrator -->|A2A| Memory[Incident Memory] Orchestrator -->|A2A| Planner[Remediation Planner] Telemetry -->|MCP| TelemetryMCP[(Telemetry MCP)] Runbook -->|MCP| RunbookMCP[(Runbook MCP)] Memory -->|MCP| MemoryMCP[(Incident Memory MCP)] TelemetryMCP --> Metrics[(metrics_snapshot.json)] TelemetryMCP --> Alerts[(active_incidents.json)] RunbookMCP --> Runbooks[(runbooks/*.md)] MemoryMCP --> Postmortems[(postmortems.json)] Telemetry -. findings .-> Orchestrator Runbook -. guidance .-> Orchestrator Memory -. history .-> Orchestrator Planner -. plan .-> Orchestrator Orchestrator --> Approval[Approval gate] Approval --> Artifact[Executive incident brief] ``` ## 序列流程 ``` sequenceDiagram participant Ops as Operator participant Cmd as Incident Commander participant Tel as Telemetry Correlator participant Run as Runbook Resolver participant Mem as Incident Memory participant Plan as Remediation Planner participant Human as Human approval Ops->>Cmd: Investigate checkout-api degradation Cmd->>Cmd: Build incident_packet par Parallel evidence collection Cmd->>Tel: A2A task: correlate signals Tel->>Tel: MCP calls for alerts and metrics Tel-->>Cmd: fault domain + blast radius and Cmd->>Run: A2A task: fetch runbook guidance Run->>Run: MCP calls for runbook search Run-->>Cmd: safe actions + rollback notes and Cmd->>Mem: A2A task: retrieve analogs Mem->>Mem: MCP calls for postmortem search Mem-->>Cmd: what worked / what failed end Cmd->>Plan: A2A task: build mitigation plan Plan-->>Cmd: ordered steps + risk_level Cmd->>Human: approval packet if risk is high Human-->>Cmd: approve / deny Cmd-->>Ops: executive brief + audit stamp ``` ## 仓库布局 ``` adk2-a2a-mcp-incident-mesh/ ├── .devcontainer/ ├── common/ ├── data/ │ ├── incidents/ │ ├── runbooks/ │ └── telemetry/ ├── docs/ ├── mcp_servers/ ├── orchestrator/ ├── remote_a2a/ │ ├── incident_memory/ │ ├── remediation_planner/ │ ├── runbook_resolver/ │ └── telemetry_correlator/ └── scripts/ ``` ## 设计选择 ### 1) A2A 和 MCP 不被视为同一事物 该系统将协作和工具访问分离开来。 - A2A 是对等智能体之间的协作层。 - MCP 是每个专家与其领域工具之间的访问层。 仅此一个区别就使整个架构更易于解释。 ### 2) 边界是真实的 每个专家仅拥有一个认知领域： - telemetry（遥测）， - runbooks（手册）， - incident memory（事件记忆）， - planning（规划）。 你可以独立地交换、扩展或替换它们。 ### 3) 分发和汇聚是确定性的 主要示例使用： - `SequentialAgent` 用于严格排序， - `ParallelAgent` 用于证据收集。 这意味着流程拓扑在代码中是显式的，而不是埋藏在提示词的散文中。 ### 4) 人为审批位于行动边界 如果推荐的缓解措施超过了风险阈值，编排器会在最终确定简报之前创建一个审批包。 ### 5) 系统生成 artifact 编排器将 markdown 简报和机器可读的 JSON 摘要写入本地的 `artifacts/` 目录。 ## 稳定路径先行，ADK 2.0 路径在后 此仓库有意保持其观点： - 主要路径目前使用稳定的工作流智能体。 - `orchestrator/agent_adk2_preview.py` 展示了如何将相同的设计映射到具有 `RequestInput` 审批闸门的 ADK 2.0 风格工作流。 这是一个成熟团队会采取的做法： 在稳定表面上发布，为下一个表面进行设计。 ## ADK 2.0 预览图 ``` flowchart TD Start([START]) --> Triage[incident_triage] Triage --> Fanout[parallel_evidence] Fanout --> Telemetry[telemetry_specialist] Fanout --> Runbook[runbook_specialist] Fanout --> Memory[memory_specialist] Telemetry --> Synthesize[decision_synthesizer] Runbook --> Synthesize Memory --> Synthesize Synthesize --> Approval[RequestInput approval gate] Approval --> Finalize[final brief artifact] ``` ## 本地开发 ### 1) 安装依赖 ``` cp .env.example .env python3 -m pip install -r requirements.txt ``` ### 2) 启动 A2A mesh ``` bash scripts/start_demo.sh ``` 这将启动： - 端口 `8000` 上的编排器， - `8101` 上的 telemetry 专家， - `8102` 上的 runbook 专家， - `8103` 上的 incident-memory 专家， - `8104` 上的 remediation 规划器。 ### 3) 验证智能体卡片 ``` bash scripts/smoke_test.sh ``` ### 4) 运行本地验证闸门 ``` python3 scripts/validate_local.py ``` 这验证了： - Python 和 ADK 导入 - 确定性 MCP 数据路径 - A2A 服务启动和 agent-card 可达性 - 存在凭据时的可选在线端到端执行 - markdown 和 JSON 输出的确定性 artifact 持久化 ### 可观测性 当你希望服务通过 ADK 导出遥测数据时，请设置这些环境变量： - `ADK_ENABLE_CLOUD_TRACING=true` - `ADK_ENABLE_CLOUD_METRICS=true` - `ADK_ENABLE_CLOUD_LOGGING=true` 对于非 GCP collector，ADK 的 OpenTelemetry 引导程序也支持标准的 OTLP 环境变量。 ### 5) 可选：运行本地 ADK UI ``` PYTHONPATH=. adk web . ``` ## 生产环境配置 对于本地开发，此示例使用 stdio 支持的服务器保持 MCP 简单。 对于生产环境，更清晰的做法是： - 通过 HTTP 或 SSE 的远程 MCP， - 单独部署的 A2A 服务， - 在两层上均进行显式身份验证， - 以及注入到 A2A 请求中的结构化追踪。 ``` flowchart LR subgraph Dev[Local or Codespaces] DevCmd[Orchestrator] DevA2A[Remote A2A agents] DevMCP[stdio MCP servers] end subgraph Prod[Cloud Run or GKE] ProdCmd[Orchestrator service] ProdA2A[Remote A2A services] ProdMCP[Remote MCP over HTTP or SSE] end Dev --> Prod ``` ## 演示提示词 在你的 UI 或冒烟测试演练中使用此提示词： ``` Investigate the active checkout-api incident. I need: 1. the most likely root cause, 2. the strongest evidence, 3. the safest immediate mitigation, 4. whether rollback needs human approval, 5. and a concise executive brief. ``` ## 推荐给他人查看的文件 - `orchestrator/agent.py` 用于了解核心的分发/汇聚设计。 - `remote_a2a/*/agent.py` 用于了解专家边界。 - `mcp_servers/*.py` 用于了解领域特定的工具表面。 - `orchestrator/agent_adk2_preview.py` 用于了解 ADK 2.0 视角。 ## 一句话总结 这又不是另一个 mega-agent 演示。 它是一个模块化的事件响应网格，使用 ADK 进行编排，使用 A2A 进行专家委派，使用 MCP 进行领域访问，并具有通向 ADK 2.0 工作流模式的清晰路径。

标签：A2A, API集成, Google ADK, incident response, LLM编排, MCP, PyRIT, 人工审批边界, 决策自动化, 分布式架构, 参考架构, 可观测性, 多智能体系统, 安全运营, 性能分析, 扫描框架, 故障排查, 智能体协作, 用户代理, 确定性工作流, 运维, 运行手册, 逆向工具, 遥测关联