ZAG23/ai-sre-k8s
GitHub: ZAG23/ai-sre-k8s
一个基于 kagent 与 Amazon Bedrock 的多智能体 SRE 管道，实现 Kubernetes 事件的自动诊断与修复。
Stars: 0 | Forks: 0
# 多智能体 SRE 管道（使用 kagent + Amazon Bedrock）
一个基于 [kagent](https://kagent.dev) 构建的 Kubernetes 原生多代理 SRE 系统，能够自主诊断并修复集群事件。五个专业代理通过 A2A（Agent-to-Agent）协议协同工作，由 Amazon Bedrock 的 OpenAI 兼容 Mantle 端点提供的 LLM 驱动。
基于 [NextWork 项目指南](https://learn.nextwork.org/projects/39c3c0b0-c5a1-4980-82bf-b8dd44c0230b)，并包含以下重大修正与增强。
## 架构
```
┌─────────────────────────────────────┐
│ │
│ sre-orchestrator │
│ DeepSeek V3.2 │
│ │
│ Coordinates incident response. │
│ Delegates to specialist agents. │
│ │
└──────────────┬──────────────────────┘
│
│ delegates via
│ agents-as-tools
│
┌──────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────────────┐
│ │ │ │ │ │
│ sre-diagnostician │ │ sre-remediator │ │ sre-architect │
│ GPT-OSS-120B │ │ GPT-OSS-120B │ │ DeepSeek V3.2 │
│ │ │ │ │ │
│ READ-ONLY │ │ PATCH / DELETE │ │ DESIGN ONLY │
│ Investigate cluster │ │ Quick fixes │ │ No cluster tools │
│ + Memory (30 days) │ │ │ │ │
│ │ │ │ │ │
└──────────┬───────────┘ └──────────┬───────────┘ └──────────┬───────────┘
│ │ │
│ │ ┌────────▼──────────┐
│ │ │ │
│ │ │ sre-builder │
│ │ │ Qwen3 Coder 480B │
│ │ │ │
│ │ │ CREATE / APPLY │
│ │ │ HITL approval │
│ │ │ │
│ │ └────────┬──────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ kagent-tool-server (MCP) │
│ │
│ k8s_get_resources k8s_patch_resource k8s_apply_manifest │
│ k8s_describe_resource k8s_label_resource k8s_create_resource │
│ k8s_get_events k8s_annotate_resource k8s_create_resource │
│ k8s_get_pod_logs k8s_delete_resource _from_url │
│ k8s_get_resource_yaml │
│ │
└─────────────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ Kubernetes Cluster │
│ │
│ namespaces · deployments · configmaps · pods │
│ events · services · secrets · replicasets │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 代理角色
| 代理 | 模型 | 提供商 | 职责 |
|------|------|--------|------|
| **sre-orchestrator** | DeepSeek V3.2 | Bedrock Mantle | 协调事件响应，委派给专家 |
| **sre-diagnostician** | GPT-OSS-120B | Bedrock Mantle | 只读集群调查 + 会话间记忆 |
| **sre-architect** | DeepSeek V3.2 | Bedrock Mantle | 设计修复方案（无直接集群访问权限） |
| **sre-builder** | Qwen3 Coder 480B | Bedrock Mantle | 生成并应用 Kubernetes 清单（HITL 授权） |
| **sre-remediator** | GPT-OSS-120B | Bedrock Mantle | 修补现有资源，快速修复 |
### 工作流程
1. 用户将事件报告（或告警 JSON）通过 A2A `message/send` 协议发送给 **协调器**
2. 协调器委派给 **诊断器** 进行实时集群调查
3. 根据发现结果：
- 快速修复（错误镜像标签、错误配置）→ **修复器** 就地打补丁
- 缺失资源 → **架构师** 设计修复方案 → **构建器** 实施（需 HITL 批准）
4. 协调器总结完整结果
## 先决条件
- Kubernetes 集群（测试于 minikube v1.38+）
- [kagent](https://kagent.dev) 通过 Helm（OCI chart）安装
- 启用了 Bedrock 访问权限的 AWS 账户（建议使用 us-east-2）
- AWS IAM 凭证 + [Bedrock API 密钥](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html)
- Python 3.x（用于 OpenSRE 和演示脚本）
- [OpenSRE CLI](https://github.com/Tracer-Cloud/opensre)（`brew install Tracer-Cloud/opensre/opensre`）
## 安装设置
### 1. 安装 kagent
kagent 使用基于 OCI 的 Helm 图表（而非传统 Helm 仓库）。
```
export OPENAI_API_KEY="placeholder"
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
-n kagent --create-namespace \
--set agents.k8s-agent.enabled=false \
--set agents.kgateway-agent.enabled=false \
--set agents.istio-agent.enabled=false \
--set agents.promql-agent.enabled=false \
--set agents.helm-agent.enabled=false \
--set agents.observability-agent.enabled=false \
--set agents.cilium-debug-agent.enabled=false \
--set agents.cilium-manager-agent.enabled=false \
--set agents.cilium-policy-agent.enabled=false \
--set agents.argo-rollouts-agent.enabled=false
```
### 2. 创建 Kubernetes 密钥
该密钥需要 AWS IAM 凭据（用于代理 Pod 运行时）和 Bedrock API 密钥（用于通过 Mantle 端点访问模型）。
```
kubectl create secret generic kagent-bedrock-aws -n kagent \
--from-literal=AWS_ACCESS_KEY_ID= \
--from-literal=AWS_SECRET_ACCESS_KEY= \
--from-literal=BEDROCK_API_KEY= \
--from-literal=AWS_SESSION_TOKEN=""
```
### 3. 发现可用模型
Bedrock API 密钥适用于 **Mantle** 端点（OpenAI 兼容）。列出所在区域可用的模型：
```
curl -s "https://bedrock-mantle..api.aws/v1/models" \
-H "Authorization: Bearer $BEDROCK_API_KEY" \
| python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"
```
### 4. 部署 ModelConfigs 和代理
```
kubectl apply -f agents/bedrock-modelconfig.yaml
kubectl apply -f agents/sre-orchestrator.yaml \
-f agents/sre-architect.yaml \
-f agents/sre-diagnostician.yaml \
-f agents/sre-remediator.yaml \
-f agents/sre-builder.yaml
```
或使用部署脚本：
```
./demo/05-deploy-agents.sh
```
### 5. 验证
```
./demo/00-status.sh
```
所有代理应显示 `READY: True` 和 `ACCEPTED: True`。
## 演示
运行端到端的完整事件响应演示：
```
./demo/00-status.sh # check fleet health
./demo/01-break-app.sh # deploy broken app (bad image + missing ConfigMap)
./demo/02-investigate.sh # send alert to orchestrator via A2A message/send
./demo/04-open-ui.sh # review the conversation + approve HITL in the web UI
./demo/03-cleanup.sh # reset for next run
```
### 被破坏的工作负载测试什么
`broken-workload.yaml` 部署了一个包含两个故意错误的 Deployment：
1. **`nginx:nonexistent-tag`** — 触发 `ImagePullBackOff`
2. 引用了不存在的 ConfigMap `app-config`
代理团队应完成：诊断两个问题 → 修补镜像标签 → 创建缺失的 ConfigMap → 验证 Pod 正常运行。
### A2A 协议
脚本 `02-investigate.sh` 使用 **A2A JSON-RPC 协议**（`message/send`）调用代理，而不是 REST 会话 API。正确的端点为：
```
POST /api/a2a/{namespace}/{agent-name}/
```
带有 JSON-RPC 载荷：
```
{
"jsonrpc": "2.0",
"id": "",
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{"kind": "text", "text": "your prompt here"}]
}
}
}
```
HITL 授权提示返回 `"status": {"state": "input-required"}`，应通过 kagent 网页 UI 处理。
## 秘密任务：代理记忆
诊断器代理启用了记忆功能，可在多次调查之间保留上下文。记忆通过在代理规格中配置 `memory` 块启用：
```
declarative:
memory:
modelConfig: bedrock-deepseek
ttlDays: 30
```
这为代理提供了三个额外工具：`save_memory`、`load_memory` 和 `prefetch_memory`。关键信息会自动提取并存储在向量数据库中以支持相似性搜索。
### 记忆需要 pgvector
代理记忆使用 PostgreSQL 并启用 pgvector 扩展。kagent 自带的 PostgreSQL **不包含** pgvector。尝试通过 Helm 启用会导致：
```
helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
-n kagent --set database.postgres.vectorEnabled=true
```
控制器崩溃并显示：
```
failed to create vector extension: ERROR: extension "vector" is not available
```
**要在生产中使用记忆**，请选择以下方式之一：
- 使用外部 PostgreSQL 并安装 pgvector（例如 Amazon RDS with pgvector）
- 替换捆绑的 PostgreSQL 镜像为包含该扩展的镜像（例如 `pgvector/pgvector:pg18`）
无论数据库是否支持，内存 CRD 配置都会被 kagent 接受和应用，因此代理在数据库支持后即可“记忆就绪”。
## 项目结构
```
ai-sre-k8s/
├── agents/
│ ├── bedrock-modelconfig.yaml # ModelConfigs (DeepSeek, GPT-OSS, Qwen3 Coder)
│ ├── sre-orchestrator.yaml # Coordinator agent (agents-as-tools)
│ ├── sre-diagnostician.yaml # Read-only investigator + memory
│ ├── sre-architect.yaml # Remediation planner (no tools)
│ ├── sre-builder.yaml # Manifest generator + applier (HITL)
│ └── sre-remediator.yaml # In-place patcher
├── demo/
│ ├── 00-status.sh # Health check
│ ├── 01-break-app.sh # Deploy broken workload
│ ├── 02-investigate.sh # Trigger agent investigation via A2A
│ ├── 03-cleanup.sh # Delete test namespace
│ ├── 04-open-ui.sh # Open kagent web UI
│ └── 05-deploy-agents.sh # Apply all agent resources
├── broken-workload.yaml # Intentionally broken Deployment
├── broken-app-alert.json # Alert payload for the orchestrator
└── README.md
```
## Bedrock Mantle 配置参考
### 端点
Mantle 端点提供 OpenAI 兼容 API，使用 Bedrock API 密钥作为 Bearer 令牌进行认证。
| 设置 | 值 |
|------|----|
| 基础 URL | `https://bedrock-mantle..api.aws/v1` |
| 认证 | `Authorization: Bearer ` |
| kagent 提供商 | `OpenAI`（非 `Bedrock`） |
### ModelConfig 模式
```
apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
name: bedrock-deepseek
namespace: kagent
spec:
apiKeySecret: kagent-bedrock-aws
apiKeySecretKey: BEDROCK_API_KEY
model: deepseek.v3.2
provider: OpenAI
openAI:
baseUrl: "https://bedrock-mantle.us-east-2.api.aws/v1"
```
### 代理环境变量注入
每个代理都需要通过 `deployment.env` 注入 AWS 凭据：
```
spec:
declarative:
deployment:
env:
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: kagent-bedrock-aws
key: AWS_ACCESS_KEY_ID
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: kagent-bedrock-aws
key: AWS_SECRET_ACCESS_KEY
- name: AWS_SESSION_TOKEN
valueFrom:
secretKeyRef:
name: kagent-bedrock-aws
key: AWS_SESSION_TOKEN
```
## 对 NextWork 项目指南的修正
在使用本项目的构建过程中遇到的问题，对应指南各步骤的修正如下。
### 步骤 1 — kagent 安装
**问题：`kagent install --profile minimal` 不是当前的安装方法。**
kagent 现在使用基于 OCI 的 Helm 图表。正确的命令为：
```
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent -n kagent --create-namespace
```
不存在传统的 `helm repo add kagent ...` 仓库。尝试执行 `helm repo add kagent https://kagent-dev.github.io/kagent` 会返回 `404 Not Found`。
**问题：图表默认部署 10 个内置示例代理。**
这些代理（k8s-agent、helm-agent、istio-agent、cilium 代理、argo-rollouts-agent 等）都需要一个不存在默认的 `default-model-config` ModelConfig，导致每个 Pod 出现 `CreateContainerConfigError`。请使用 `--set agents..enabled=false` 禁用每个代理。
### 步骤 2 — 配置 Bedrock 和 OpenRouter 模型提供程序
**问题：`provider: Bedrock` 原生集成需要特定密钥和环境变量注入。**
指南中创建的 `bedrock-credentials` 密钥包含 IAM 凭据，且 ModelConfig 使用 `provider: Bedrock`。这仅在代理 YAML 中也包含 `deployment.env` 块并注入 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 时才有效，否则 Pod 会因 `CreateContainerConfigError: couldn't find key AWS_ACCESS_KEY_ID` 而失败。
**问题：OpenRouter 即使使用 BYOK 仍需信用额度。**
若在 OpenRouter 中配置 Bedrock BYOK，OpenRouter 仍会从信用余额中扣除小额费用。信用为零的账户会返回 `402 Payment Required`，即使 BYOK 已激活。每个 API 密钥还有月度预算限制，需在 [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys) 提升限额。
**推荐修复：直接使用 Bedrock Mantle 端点。**
不要使用 `provider: Bedrock` 或通过 OpenRouter 路由，而是使用 `provider: OpenAI` 并指向 Bedrock Mantle 端点（`https://bedrock-mantle..api.aws/v1`）。这使用rock API 密钥作为 Bearer 令牌，无中间商成本。
### 步骤 2 — Bedrock 端点 URL
**问题：存在两个不同的 Bedrock 端点，且不可互换。**
| 端点 | URL | 认证 | 是否支持 Claude |
|------|-----|------|------|
| **Mantle**（OpenAI 兼容） | `bedrock-mantle..api.aws/v1` | Bedrock API 密钥（Bearer） | 否 |
| **Runtime**（原生 API） | `bedrock-runtime..amazonaws.com` | SigV4（IAM） | 是 |
[cloudnativedeepdive.com 指南](https://www.cloudnativedeepdive.com/implem/) 引用的 `bedrock-runtime.us-east-1.amazonaws.com/openai/v1` 路径返回 `UnknownOperationException`。OpenAI 兼容端点是 **Mantle**，而非 Runtime。
### 步骤 2 — Mantle 上不可用 Claude 模型
**问题：指南中对 Bedrock ModelConfig 使用了 `us.anthropic.claude-sonnet-4-20250514-v1:0`。**
Anthropic Claude 模型**不通过** Bedrock Mantle（OpenAI 兼容）端点提供。它们仅可通过原生 Bedrock Runtime API（SigV4 认证）或 OpenRouter 等第三方路由器访问。
**推荐修复：使用 Mantle 上实际可用的模型。**
通过 `/v1/models` 查询可用模型。推荐替代方案：
- `deepseek.v3.2` — 推理与协调
- `openai.gpt-oss-120b` — 通用目的，价格极低
- `qwen.qwen3-coder-480b-a35b-instruct` — 代码/清单生成
- `mistral.mistral-large-3-675b-instruct` — 推理替代方案
### 步骤 2 — 跨区域模型 ID 前缀
**问题：带有 `us.` 或 `global.` 前缀的模型 ID（如 `us.anthropic.claude-opus-4-6-v1`）用于原生 Bedrock Runtime 的跨区域推断配置概况。Mantle 端点使用无前缀的基础模型 ID（例如 `deepseek.v3.2`）。**
### 步骤 3 — 代理工具格式
**问题：指南使用的扁平化工具名称格式与实际的 kagent v1alpha2 API 不匹配。**
指南中显示：
```
tools:
- name: kagent.tools.k8s.GetResources
```
实际的 kagent v1alpha2 API 使用 MCP 服务器工具引用：
```
tools:
- type: McpServer
mcpServer:
apiGroup: kagent.dev
kind: RemoteMCPServer
name: kagent-tool-server
toolNames:
- k8s_get_resources
```
工具名称使用 `snake_case`（例如 `k8s_get_resources`），而非 PascalCase（`GetResources`）。
### 步骤 3 — requireApproval 位置
**问题：指南将 `requireApproval` 放在 `declarative` 下，但应位于 `mcpServer` 工具定义内部。**
指南显示：
```
declarative:
requireApproval:
- kagent.tools.k8s.DeleteResource
```
正确格式：
```
tools:
- type: McpServer
mcpServer:
name: kagent-tool-server
toolNames:
- k8s_delete_resource
requireApproval:
- k8s_delete_resource
```
### 步骤 3 — ModelConfig 在代理 YAML 中的位置
**问题：指南将 `modelConfig` 直接放在 `spec` 下，但应位于 `spec.declarative` 下。**
指南显示：
```
spec:
type: Declarative
modelConfig: bedrock-native
declarative:
systemMessage: ...
```
正确格式：
```
spec:
type: Declarative
declarative:
modelConfig: bedrock-native
systemMessage: ...
```
### 步骤 5 — OpenSRE 告警修复路径
**问题：指南引用路径 `opensre investigate -i tests/e2e/kubernetes/fixtures/datadog_k8s_alert.json`，但该路径在全新设置中不存在。请使用包含的 `broken-app-alert.json` 或直接交互运行 `opensre investigate`。**
### 步骤 6 — 通过 API 调用代理
**问题：指南仅使用 kagent 仪表板聊天作为调用方法。**
如需程序化/脚本化调用，请使用 A2A JSON-RPC 协议访问 `/api/a2a/{namespace}/{agent-name}/`，方法为 `message/send`。REST 会话 API（`POST /api/sessions/{id}/events`）是代理运行时的内部接口，外部调用会返回 `403 Session does not belong to this agent`。
### 秘密任务 — Memory TTL 字段
**问题：指南使用 `ttl: 604800`（秒），但实际 CRD 字段为 `ttlDays`（整数，天）。**
指南显示：
```
memory:
modelConfig: bedrock-native
ttl: 604800
```
正确格式：
```
memory:
modelConfig: bedrock-deepseek
ttlDays: 30
```
### 秘密任务 — pgvector 在捆绑 PostgreSQL 中不可用
**问题：`helm upgrade kagent ... --set database.postgres.vectorEnabled=true` 会导致控制器崩溃。**
捆绑的 PostgreSQL 镜像（`postgres:18`）未包含 pgvector 扩展。启用 `vectorEnabled=true` 会导致控制器崩溃并显示 `failed to create vector extension: ERROR: extension "vector" is not available`。
无论数据库是否支持，内存 CRD 配置都会被 kagent 接受和应用，因此代理在数据库支持后即可“记忆就绪”。
### 通用 — Helm 图表基于 OCI
**问题：** `helm upgrade kagent kagent/kagent ...` 会报错 `Error: repo kagent not found`。kagent 不发布传统 Helm 仓库。请使用 OCI 注册表：
```
helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent -n kagent --reuse-values
```
### 通用 — Pod 必须在 ModelConfig 更改后重启
更改 ModelConfig 不会自动传播到运行中的代理 Pod。更改配置后必须重启：
```
kubectl rollout restart deploy/sre-orchestrator deploy/sre-architect \
deploy/sre-diagnostician deploy/sre-remediator deploy/sre-builder -n kagent
```
### 通用 — 密钥必须包含所有预期键
kagent 运行时要求密钥中包含 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN`，即使某些值为空字符串。仅包含 `BEDROCK_API_KEY` 的密钥会导致 Pod 启动时出现 `CreateContainerConfigError`。
标签：A2A协议, Agent-to-Agent, AIOps, Amazon Bedrock, DLL 劫持, kagent, LLM, LLM驱动运维, Mantle, OpenAI兼容, PyRIT, SRE, Unmanaged PE, 专家代理, 事故响应, 偏差过滤, 分布式系统, 协作智能体, 响应大小分析, 多Agent, 多智能体系统, 大语言模型, 子域名突变, 容器编排, 弹性架构, 智能体编排, 智能运维, 测试用例, 站点可靠性工程, 自动化响应, 自动化运维, 逆向工具, 零停机