Ismail-2001/The-Kubernetes-of-AI-Agents
GitHub: Ismail-2001/The-Kubernetes-of-AI-Agents
面向生产环境的 LLM Agent 编排平台，通过多租户隔离、策略引擎、成本预算和可观测性体系解决 AI Agent 从原型到规模化部署的工程难题。
Stars: 5 | Forks: 0
# AI Agent 的 Kubernetes
[](LICENSE)
## 当前状态
由构建该项目的工程师进行了端到端验证。以下每个数字都与运行中的代码进行了交叉核对——不是文档，也不是猜测。
| 领域 | 评分 | 正常工作的功能 | 已验证的缺陷 |
|:---|:---:|:---|:---|
| 功能完整性 | 93% | 完整的 agent CRUD（REST + gRPC）、带有断路器 + 3 模型 fallback 链的 LLM 路由、Docker 中的沙箱化工具执行、结构化 tool-calling（OpenAI `tools` 参数）、每个 namespace 的 token 预算（硬性 `RESOURCE_EXHAUSTED` 停止） | 错误处理不够全面；输入没有 JSON Schema |
| 可靠性 | 85% | 沙箱生命周期（在 3 次以上的评估运行中创建→执行→终止）、Temporal 确定性（在 6/6 个并发工作流中 0 状态损坏）、**并发信号量 + 指数退避（最大 10，处理了 429s）**、gRPC 重试（指数退避 + 抖动，3 次重试）、PgBouncer 连接池（25 个连接，事务模式） | Redis 单实例（存在 Sentinel 代码，但未部署）；Docker 层缓存未优化 |
| 安全性 | 70% | OPA/Rego 拒绝/允许已进行实时验证，所有 `/api/*` 上的 JWT bearer auth，静态 secret 使用 AES-256-GCM 加密，每次内部调用都带有 gRPC `x-service-token`，CORS 无通配符白名单，沙箱网络隔离（`egaop-sandbox` 内部网络），**PII 扫描现在会阻止请求**，**感知 namespace 的速率限制**（3 个服务），**安全响应头 + 1MB 请求体限制**（Fastify），**npm audit 0 个 CVE**（修复了 19 个） | TLS 加密正常工作，但 **mTLS 已禁用**（`@grpc/grpc-js` v1.14.4 bug，`requestCert:false`）；**`x-service-token` 作为补偿性控制**接入所有 9 个服务中；未进行渗透测试；从未运行过 Trivy 镜像扫描（需要 GitHub runner） |
| 可观测性 | 79% | 结构化 JSON 日志（pino），带有 traceId/namespace/service，所有服务上的 Prometheus RED 指标，OTel 分布式追踪（gRPC 上下文传播），5 条 Grafana 告警规则验证已触发 + 定义了 10 条 Prometheus 告警规则（包含 $50/hr 的 LLM 成本预算） | Dashboard 渲染未经验证；没有正式的审计日志格式 |
| 可操作性 | 75% | Docker Compose（所有 17 个容器健康），backup→destroy→restore 3/3 循环已验证（pg_dump，Redis SAVE，Grafana sqlite），所有服务均有健康检查，每 6 小时备份一次并保留 30 天，**本地 CI/CD 脚本**（ci-local.ps1，docker-build-all.ps1，kind-deploy.ps1），**Helm chart OPA 已修复**（5 个 bug：镜像 tag、未定义的 `now`、`count` 冲突、缺失的启动探针、弱安全 securityContext） | `.github/workflows/` 中的 CI/CD —— **从未在** GitHub 上执行过；没有自动化部署 |
| Agent 质量 | 92% | 19 个用例的黄金数据集（7 个类别），自动化运行器 + Temporal 轮询，跨运行的回归比较，**RL-2：84.2% 任务成功率**（16/19），**eval 指标 bug 已修复**（`tool_selection_accuracy` 被限制在 [0,1]） | 剩余约 2/3 的失败是由于基础设施污染（OpenRouter 饱和），而不是 agent 缺陷 |
**适用于：** 演示、单用户试点（少于 10 个并发 agent）。
**不适用于：** 多租户生产环境、无监控的部署、需要漏洞清除的工作负载。
## 为什么需要另一个 Agent 框架？
大多数 agent 框架在“hello world”处就停滞不前了——即在你的笔记本电脑上单个 agent 调用单个 LLM。它们没有解决在生产环境中真正困难且重要的问题：
- **多租户** —— 50 个团队如何共享一个平台而不互相干扰？（OPA 策略，namespace 隔离）
- **安全性** —— 你如何防止一个 agent 读取另一个 agent 的 secret？（AES-256-GCM，gRPC service-token 认证，CORS 白名单）
- **成本控制** —— 你如何阻止失控的 agent 消耗 API 额度？（每个 namespace 的每日 token/成本预算，带有硬性 `RESOURCE_EXHAUSTED` 停止）
- **可靠性** —— 当 LLM 宕机时会怎样？当 Postgres 不可用时怎么办？（LLM fallback 链、断路器、带退避的 gRPC 重试、PgBouncer 连接池、备份/恢复）
- **可观测性** —— 你如何跨微服务追踪单个 agent 请求？（OTel 分布式追踪、Prometheus RED 指标、Grafana 告警）
## 架构
```
+-------------------------------------------------------------------------------------------+
| CONTROL PLANE |
| +------------------+ +------------------+ +------------------+ |
| | API Server | | Workflow | | Secret Store | |
| | (REST + gRPC) | | Engine | | (AES-256-GCM) | |
| | (CORS allowlist)| | (Temporal) | | | |
| +--------+---------+ +--------+---------+ +--------+---------+ |
| | | | |
+-----------+--------------------+-----------------------+------------------------------------+
| EXECUTION PLANE |
| +--------+---------+ +--------+---------+ +--------+---------+ |
| | LLM Router | | Tool Proxy | | Sandbox | |
| | (fallback chain)| | (PII blocks) | | Runtime | |
| | (circuit breaker)| |(rate-limited) | | | |
| |(semaphore max 10)| | | | | |
| +--------+---------+ +--------+---------+ +------------------+ |
| | | | |
+-----------+--------------------+-----------------------+------------------------------------+
| DATA / MEMORY PLANE |
| +------------------+ +------------------+ +------------------+ |
| | Redis | | PostgreSQL | | PgBouncer | |
| | (standalone) | | (entity) | | (transaction | |
| | | | | | pool, 25 conn)| |
| +------------------+ +------------------+ +------------------+ |
+-------------------------------------------------------------------------------------------+
| POLICY PLANE |
| +------------------+ |
| | OPA / Rego | |
| | (tag 0.68.0, | |
| | 5 bugs fixed) | |
| +------------------+ |
+-------------------------------------------------------------------------------------------+
| OBSERVABILITY PLANE |
| +------------------+ +------------------+ +------------------+ |
| | OTel Collector | | Prometheus | | Grafana | |
| | (traces) | | (metrics) | | (dashboards + | |
| | | | | | 5 alert rules) | |
| +------------------+ +------------------+ +------------------+ |
+-------------------------------------------------------------------------------------------+
```
### 请求流
```
Client → API Server (JWT auth) → OPA Policy (deny/allow) → Workflow Engine (Temporal)
→ LLM Router (semaphore → circuit breaker → fallback → model call)
→ Tool Proxy (PII blocks) → Sandbox Runtime (Docker container)
→ Result → Tool result → LLM follow-up → Final Answer
```
## 功能
### 安全性
| 功能 | 实现 | 状态 |
|---------|---------------|--------|
| **gRPC 服务认证** | 每个内部 RPC 都带有签名的 `x-service-token` header，并在服务端进行验证 | ✅ 已验证 |
| **静态 Secret** | 通过 `EGAOP_MASTER_ENCRYPTION_KEY` 进行 AES-256-GCM 加密 | ✅ 已验证 |
| **CORS 白名单** | 仅允许配置的来源（环境变量，逗号分隔），无通配符 | ✅ 已验证 |
| **OPA 策略执行** | 在每个执行请求时评估 Rego 策略（拒绝/允许已进行实时验证）。**修复了 5 个 bug**（镜像 tag、未定义的 `now`、`count` 冲突、启动探针、securityContext） | ✅ 已验证 |
| **JWT 认证** | 所有 `/api/*` endpoint 上的 Bearer token 认证 | ✅ 已验证 |
| **安全响应头** | Fastify `onSend` hook：X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, HSTS, CSP, Referrer-Policy, Permissions-Policy | ✅ 已验证 |
| **请求体限制** | 强制执行 1MB 的请求体限制，content-type 验证 preHandler | ✅ 已验证 |
| **PII 扫描** | 对 tool call payload 进行基于正则表达式的扫描（SSN、电子邮件）——现在通过 `PIIViolationError` **进行阻止** | ✅ 阻止 |
| **速率限制** | 3 个服务中具备**感知 namespace** 的能力（`x-namespace` header，回退到 IP/agent-id） | ✅ 已验证 |
| **npm audit** | 0 个高危 CVE（修复了 19 个：11 个高危，8 个中危）。`testcontainers` 升级 `^10.18.0`→`^12.0.4` | ✅ 干净 |
| **TLS 加密** | 通过 TLS 加密 gRPC 流量（服务器证书 + CA）。由于 `@grpc/grpc-js` v1.14.4 bug，**mTLS（客户端证书验证）已禁用**。**补偿性控制**：通过共享拦截器将 `x-service-token` 应用层认证接入所有 9 个服务中。 | ⚠️ 部分（mTLS 关闭，应用层认证激活） |
| **渗透测试** | 未执行注入测试、模糊测试或红蓝对抗演练 | ❌ 未做 |
### 可靠性
| 功能 | 实现 | 状态 |
|---------|---------------|--------|
| **LLM fallback 链** | `gpt-4o → gpt-4o-mini → gpt-3.5-turbo`，带有 opossum 断路器（30秒超时，50% 错误阈值，30秒重置）。**速率限制错误已隔离**，不会触发断路器 | ✅ 已验证 |
| **并发控制** | 信号量（最大 10，`LLM_MAX_CONCURRENT`），针对 429s 的**指数退避加抖动**（3 次重试，`1s×2^attempt + random(500ms)`），OpenRouter `maxRetries=5` | ✅ 已验证 |
| **gRPC 重试** | 带有抖动的指数退避（3 次重试，200ms 基准，0.3 抖动因子）。可重试代码：UNAVAILABLE, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED, INTERNAL | ✅ 已验证 |
| **连接池** | PgBouncer 处于事务模式，默认 25 个连接池，最大 100 个客户端。所有服务均通过 `pgbouncer:6432` 路由 | ✅ 已验证 |
| **健康检查** | 所有 17 个服务均具有 Docker HEALTHCHECK 和 `/healthz` endpoint | ✅ 已验证 |
| **每个 namespace 的预算** | `TokenBudget` 类具有每日 token/成本限制和每分钟 RPM —— 硬停止返回 `RESOURCE_EXHAUSTED` | ✅ 已验证 |
| **Temporal 重试策略** | 针对 PII_VIOLATION 和 POLICY_DENIED 的不可重试错误分类。否则为默认的 Temporal 重试。 | ⚠️ 部分（已分类 2 种错误类型） |
| **Redis HA** | 仅部署了单个 Redis 实例。代码具有条件性的 sentinel 支持，但未配置 sentinel 容器。 | ❌ 未部署 |
| **并发上限** | 在 100% 成功率下维持 10 个并发 agent（在修复信号量后确认）。以前在 ≥12 时会降级。 | ✅ 在 10 时稳定 |
### 可观测性
| 工具 | 访问方式 | 用途 |
|:---|:---|:---|
| Grafana | `http://localhost:3003` | 5 条 Grafana 告警规则（已验证触发）+ 定义了 10 条 Prometheus 告警规则 |
| Prometheus | `http://localhost:9091` | 指标抓取（10秒间隔），每个服务的 RED 指标 |
| OTel Collector | `:4317` (gRPC) / `:4318` (HTTP) | 跨所有服务的分布式追踪，具备 W3C 上下文传播 |
| 日志 | `docker compose logs ` | 包含 `traceId`、`namespace`、`service` 字段的结构化 JSON（pino） |
### 成本控制
- 每个 namespace 的每日 token 预算（达到 `RESOURCE_EXHAUSTED` 时硬停止）
- 每个 namespace 的每日成本预算（美分）
- 每分钟 RPM 限制
- Prometheus 告警规则 `LLMCostBudgetExceeded`，阈值为 $50/hr（需要填充 `e_gaop_llm_tokens_used_total` 指标）
### 测试与质量
- 跨 29 个测试文件和 10 个工作区的**约 324 个测试**（单元测试、集成测试、契约测试、混沌测试、性能测试）
- **CI 工作流**完全定义在 `.github/workflows/` 中 —— 通过 `.\scripts\ci-local.ps1` 进行本地验证（模拟 GitHub Actions：audit→lint→typecheck→build→test→cross-cutting→Docker build→Helm lint/template）。**从未在** GitHub runner 上执行过（参见 [已知限制](#known-limitations)）
- **54 个共享包测试**，涵盖错误、namespace、速率限制、secret。全部 54/54 通过。
- **Eval 指标 bug 已修复** —— `tool_selection_accuracy` 被限制在 [0,1]，catch 块设置 null expected_tool，`compare-evals.mjs` 对齐到相同的指标
- **评估套件**，包含 19 个用例的黄金数据集：**RL-2：84.2% 任务成功率**（16/19）。剩余约 2/3 的失败可能是由于基础设施污染（OpenRouter 饱和），而不是 agent 缺陷。
## 快速开始
```
# 1. 克隆并进入
git clone https://github.com/Ismail-2001/The-Kubernetes-of-AI-Agents.git
cd The-Kubernetes-of-AI-Agents
# 2. 配置 secrets
cp .env.example .env
# 编辑 .env：设置 OPENAI_API_KEY、JWT_SECRET、POSTGRES_PASSWORD 等。
# 3. 启动所有服务
docker compose up -d
# 4. 验证
curl http://localhost:3001/health
# → {"status":"healthy"}
# 5. 打开 dashboards
# Grafana：http://localhost:3000 (admin / )
# API 文档：http://localhost:3001/api/docs
```
## 项目结构
```
├── control-plane/ # API server, workflow engine, secret store
├── execution-plane/ # LLM router (circuit breaker, semaphore), tool proxy (PII blocks), sandbox runtime
├── memory-plane/ # Redis + PostgreSQL via PgBouncer
├── observability-plane/ # Trace ingestion and replay
├── policy-plane/ # OPA/Rego engine (5 bugs fixed, tag 0.68.0)
├── packages/shared/ # @e-gaop/shared (TLS, retry interceptor, rate limiter, TokenBudget, errors)
├── infrastructure/ # PgBouncer config, migration service Dockerfile
├── charts/e-gaop/ # Helm chart (OPA CrashLoopBackOff: fixed)
├── evals/ # Golden dataset, runner, baselines (RL-1 through RL-4)
├── scripts/ # Backup/restore, mock LLM, load test, grafana-init, docker-build-all, kind-deploy, migrate
├── migrations/ # PostgreSQL migrations (6 files + rollback files)
├── observability/ # Prometheus alerts (10 rules), Grafana provisioning, OTel config
├── docs/ # Production readiness assessment, runbooks, benchmarks, CI setup
└── .github/workflows/ # CI/CD (ci.yml, deploy.yml, security-scan.yml, backup.yml — local-validated)
```
## 生产环境运维手册
| 场景 | 操作 |
|----------|--------|
| **Postgres 宕机** | 检查磁盘空间 → 检查 WAL 归档 → 从 `/backup` 恢复 |
| **LLM 预算超支** | 在 `TokenBudget` 中识别 namespace → 挂起 namespace → 查看 agent 日志 |
| **断路器打开** | 检查 `llm-router` 日志 → 验证 OpenAI API 密 → 监控恢复情况（30秒自动重置） |
| **服务不健康** | `docker compose logs ` → 在 Tempo 中检查 OTel 追踪 |
| **Schema 变更部署** | `docker compose run --rm migrate up`（通过 compose 中的 `migrate` 服务自动运行） |
| **回滚最后一次迁移** | `docker compose run --rm migrate down --count=1` |
| **检查迁移状态** | `docker compose run --rm migrate status` |
| **创建新迁移** | `node scripts/migrate.mjs create --name=add_index` |
| **危险的回滚** | 向下迁移会删除表/列 —— 请先备份：`scripts/backup.sh` |
| **从备份恢复** | `./scripts/restore.sh /backup/backup-.tar.gz` |
### 迁移系统
所有 schema 变更都通过 `scripts/migrate.mjs` 进行。每次迁移都有一个 up + down 文件：
```
migrations/
001_memory_plane.sql # up: CREATE TABLE agent_memory
001_memory_plane.down.sql # down: DROP TABLE agent_memory
002_observability_plane.sql
002_observability_plane.down.sql
...
```
迁移在 Docker Compose 启动时自动运行（通过 `migrate` 服务，在 api-server/secret-store/memory-plane 之前）。在 CI/CD 中，迁移作为部署前步骤运行。在 Kubernetes 中，`kind-deploy.ps1` 将迁移作为 Kubernetes job 运行。
### Secrets 管理
Secrets **永远不会写入磁盘**。在 CI/CD 中，secrets 作为环境变量直接注入到每个 `docker compose` 步骤中：
```
# deploy.yml — secrets 来自 GitHub Secrets，绝不触碰磁盘
- name: Deploy
env:
POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
JWT_SECRET: ${{ secrets.JWT_SECRET }}
EGAOP_MASTER_ENCRYPTION_KEY: ${{ secrets.EGAOP_MASTER_ENCRYPTION_KEY }}
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
GRAFANA_PASSWORD: ${{ secrets.GRAFANA_PASSWORD }}
INTERNAL_SERVICE_TOKEN: ${{ secrets.INTERNAL_SERVICE_TOKEN }}
REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD }}
run: docker compose up -d
```
对于本地开发，将 `.env.example` 复制为 `.env`（已被 gitignored，永远不会提交）。Docker Compose 会从 `.env` 文件和 shell 环境变量中解析 `${VAR}`。
通过 `backup` Docker 服务，备份每 6 小时自动运行一次（保留 30 天）。
每条告警规则的完整手册：[`docs/runbooks/`](docs/runbooks/)。
## 已知限制
这些是针对运行中的代码库验证过的已知缺陷。不隐藏，也不是期望。
1. **CI/CD 从未在** GitHub **上执行过** —— 工作流文件（`ci.yml`，`deploy.yml`，`security-scan.yml`）存在并通过 `scripts/ci-local.ps1` 在本地验证，但从未在 GitHub runner 上触发过。需要代码库 push + 启用 GitHub Actions。**生产环境的阻碍因素。**
2. **从未运行过** Trivy **镜像扫描** —— 扫描器配置存在于 `security-scan.yml` 中，但从未执行过。没有对这 17 个容器镜像进行 CVE 审查。**生产环境的阻碍因素。**
3. **mTLS 已禁用** —— TLS 加密正常工作（流量已加密），但 `@grpc/grpc-js` v1.14.4 bug 阻止了客户端证书验证。已使用 `requestCert: false` 作为临时解决方案。**补偿性控制**：通过共享的 gRPC 拦截器，将 `x-service-token` 应用层认证接入所有 9 个服务中。
4. **未部署** Redis Sentinel —— 仅限单个 Redis 实例。代码具有条件性的 sentinel 支持，但在 `docker-compose.yml` 中未配置 sentinel 容器。
5. **评估基础设施污染** —— 19 个评估用例中约有 2 个由于 OpenRouter/llm-router 饱和而失败，而不是 agent 缺陷。如果不考虑基础设施干扰，真实的 agent 质量可能在 94% 左右。
6. **无渗透测试** —— 未执行注入测试、模糊测试或红蓝对抗演练。
## 基准测试
| 指标 | 数值 | 来源 |
|--------|-------|--------|
| P95 OPA 策略评估 | < 50ms | `tests/perf/execution-path.test.ts` |
| P99 端到端健康检查 | < 100ms | `tests/perf/performance.test.ts` |
| 并发 agent 上限 | 10 @ 100% 成功 | 负载测试（BK 轮次） |
| 最大吞吐量（单节点） | ~100+ RPM（估计） | 未进行基准测试 |
| LLM 断路器恢复 | 30秒（可配置） | opossum `resetTimeout` |
## 评估
该平台包含一个自动化评估套件（`evals/`），其中包含涵盖 7 个类别的 19 个黄金用例。
| 运行 | 日期 | 通过率 | 备注 |
|:---|:---|:---:|:---|
| RL-1 (基线) | 7月17日 | 68.4% (13/19) | 所有 6 个失败均已记录 |
| RL-2 | 7月18日 | **84.2% (16/19)** | +15.8pp, 3 个 FLIPs |
**3 个用例得到改善：** qanda-simple-math（不再为 2+2 调用 code_interpreter），code_interpreter-sum-1-to-100（在 1 次调用中完成，而不是 10 次循环），code_interpreter-csv-average（写入文件然后在 2 次调用中完成计算）。
**仍然失败（3 个）：** code_interpreter-prime-check（MAX_ITERATIONS 循环），file_write-read-greeting（`LLM call failed` —— 可能是基础设施污染），database_query-create-table（同上）。
## License
MIT
标签：AI智能体编排, API集成, DLL 劫持, gRPC, Petitpotam, Python工具, Temporal, 可观测性, 大语言模型, 搜索引擎查询, 测试用例, 用户代理, 自动化攻击, 自定义请求头, 请求拦截