# AgentPaaS: Agent 平台即服务 ## 定位 **lambdagent** 是 agent 的形式化 DSL 与执行引擎(计算内核)。 **AgentPaaS** 是将 lambdagent 包装为生产级 PaaS 平台的服务层。 类比:lambdagent 之于 AgentPaaS,如同 V8 之于 Node.js,如同 CPython 之于 Django。 ``` 用户/开发者 │ ▼ ┌─────────────────────────────────┐ │ AgentPaaS (平台服务层) │ ← 本项目 │ API Gateway / Dashboard / CLI │ │ 调度 · 隔离 · 监控 · 计费 │ ├─────────────────────────────────┤ │ lambdagent (计算内核) │ ← 已有项目 │ DSL · β-归约 · ReAct · MCP │ └─────────────────────────────────┘ ``` --- ## 核心功能模块 ### 1. Agent Serving(服务化) 将 YAML 定义的 agent 暴露为 HTTP/WebSocket API。 - **REST API**: `POST /v1/agents/{id}/run` — 同步执行 - **Async API**: `POST /v1/agents/{id}/jobs` — 异步提交,返回 job_id - **Streaming**: `POST /v1/agents/{id}/stream` — SSE 流式输出 - **WebSocket**: `/v1/agents/{id}/ws` — 双向交互(适合多轮对话 agent) - 每个 agent 配置独立 endpoint,支持版本路由 (`/v1/agents/{id}@v2/run`) ### 2. Agent Registry(注册中心) Agent 的全生命周期管理。 - **CRUD**: 创建、更新、删除、查询 agent 定义 - **版本控制**: 每次更新自动生成版本号,支持回滚 - **标签与搜索**: 按标签、能力、模型类型检索 agent - **依赖图**: 自动解析 agent 间的组合依赖(Compose、Route 引用) - **A2A 发现**: 集成 lambdagent 的 A2A 协议,agent 可被外部系统发现 ### 3. Execution Engine(执行引擎) 对 lambdagent β-归约引擎的生产级封装。 - **Job Queue**: 基于 Redis/PostgreSQL 的任务队列,支持优先级 - **并发控制**: 每个 agent / 租户的并发上限 - **超时管理**: 可配置的 agent 执行超时、单步 LLM 调用超时 - **重试策略**: 指数退避 + 断路器,防止 LLM API 雪崩 - **资源隔离**: 每个 agent 执行在独立沙箱(进程/容器),限制 CPU/内存 - **Checkpoint 恢复**: 利用 lambdagent 的 checkpoint 模块,长任务中断后可恢复 ### 4. Multi-Tenancy(多租户) - **租户隔离**: 数据、配置、执行环境完全隔离 - **API Key 管理**: 每个租户可创建多个 API Key,支持 scope 限定 - **RBAC**: 角色权限(Admin / Developer / Viewer) - **配额管理**: 按租户设置 token 用量上限、并发上限、存储上限 - **团队协作**: 同一租户内多成员共享 agent ### 5. Observability(可观测性) - **Trace**: 集成 OpenTelemetry,每次 β-归约步骤生成 span - **Metrics**: Prometheus 指标 — 请求量、延迟、token 消耗、错误率 - **Logging**: 结构化日志(JSON),支持 ELK/Loki - **Dashboard**: 内置 Web 面板,展示 agent 执行轨迹、性能趋势、成本分析 - **Alerting**: 基于规则的告警(错误率突增、token 消耗异常、延迟劣化) ### 6. Secret & Config Management(密钥与配置) - **Secret Store**: 加密存储 LLM API Key、MCP Server 凭证、外部服务密钥 - **Environment Binding**: 每个 agent 可绑定不同环境变量集(dev / staging / prod) - **Hot Reload**: 配置变更无需重启,动态生效 - **Audit Trail**: 所有密钥访问和配置变更留有审计记录 ### 7. Gateway & Traffic(网关与流量) - **Rate Limiting**: 令牌桶限流,按租户 / API Key / agent 粒度 - **Authentication**: API Key + JWT + OAuth 2.0 - **Load Balancing**: 多 worker 负载均衡 - **Canary Deploy**: 支持灰度发布(将 10% 流量路由到新版 agent) - **Request Validation**: 输入 schema 校验,防止恶意输入 ### 8. Billing & Metering(计费与计量) - **Token 计量**: 精确记录每次执行的 input/output token 消耗 - **Cost Attribution**: 按 agent、租户、模型维度归因成本 - **Usage Report**: 日/周/月用量报告 - **Budget Alert**: 预算告警(接近配额时通知) --- ## 技术选型(初步) | 层次 | 选型 | 理由 | |------|------|------| | API Framework | FastAPI | 原生 async、自动 OpenAPI 文档、与 Python 生态契合 | | Task Queue | Celery + Redis | 成熟稳定,支持优先级、重试、结果后端 | | Database | PostgreSQL | Agent 注册、执行历史、租户数据 | | Cache | Redis | Session、限流计数器、热点配置 | | Observability | OpenTelemetry + Prometheus | 业界标准,生态丰富 | | Container | Docker + K8s | Agent 沙箱隔离、弹性伸缩 | | Auth | OAuth 2.0 / JWT | 标准化,支持第三方身份提供者 | --- ## 项目结构(规划) ``` agentpaas/ ├── api/ # FastAPI 路由 │ ├── v1/ │ │ ├── agents.py # Agent CRUD + 执行 │ │ ├── jobs.py # 异步任务管理 │ │ ├── auth.py # 认证端点 │ │ └── admin.py # 管理端点 │ └── middleware/ │ ├── auth.py # JWT/API Key 验证 │ ├── rate_limit.py # 限流 │ └── tenant.py # 租户上下文注入 ├── engine/ # 执行引擎 │ ├── scheduler.py # 任务调度 │ ├── sandbox.py # 沙箱隔离 │ ├── worker.py # Celery worker │ └── stream.py # SSE/WebSocket 流式 ├── registry/ # Agent 注册中心 │ ├── store.py # Agent 持久化 │ ├── version.py # 版本管理 │ └── discovery.py # A2A 服务发现 ├── tenant/ # 多租户 │ ├── models.py # 租户/用户/角色模型 │ ├── isolation.py # 数据隔离 │ └── quota.py # 配额管理 ├── observability/ # 可观测性 │ ├── tracing.py # OpenTelemetry 集成 │ ├── metrics.py # Prometheus 指标 │ └── logging.py # 结构化日志 ├── secrets/ # 密钥管理 │ ├── vault.py # 加密存储 │ └── env.py # 环境变量绑定 ├── billing/ # 计费 │ ├── metering.py # Token 计量 │ └── report.py # 用量报告 ├── dashboard/ # Web UI(可选,后期) │ └── ... ├── cli/ # 管理 CLI │ └── main.py ├── config.py # 全局配置 ├── models.py # SQLAlchemy/Pydantic 模型 ├── pyproject.toml ├── Dockerfile ├── docker-compose.yml └── README.md ``` --- ## 与 lambdagent 的集成方式 AgentPaaS 将 lambdagent 作为 **核心依赖**,不修改其代码: ```python # agentpaas 调用 lambdagent 的方式 from lambdagent import from_config, Runtime, Context # 1. 从注册中心加载 agent YAML agent_yaml = registry.get_agent(agent_id, version) # 2. 编译为 Lambda Term term = from_config(agent_yaml) # 3. 构建执行上下文(注入租户密钥、配额限制等) ctx = Context() ctx.set("api_key", secrets.get(tenant_id, "openai_key")) ctx.set("max_tokens", quota.remaining(tenant_id)) # 4. 在沙箱中执行 β-归约 result = await sandbox.run(Runtime().reduce, term, ctx) # 5. 记录 trace、metrics、billing tracing.record(ctx.trace) metrics.record_tokens(ctx.total_tokens) billing.record(tenant_id, ctx.total_tokens, model) ``` --- ## MVP 路线图 ### Phase 1: 最小可用(2 周) - [ ] FastAPI 骨架 + Agent CRUD API - [ ] 同步执行端点(直接调用 lambdagent) - [ ] API Key 认证 - [ ] PostgreSQL 持久化 - [ ] 基础日志 ### Phase 2: 生产可用(4 周) - [ ] 异步任务队列(Celery) - [ ] SSE 流式输出 - [ ] 多租户隔离 - [ ] Rate Limiting - [ ] OpenTelemetry tracing - [ ] Prometheus metrics ### Phase 3: 平台化(8 周) - [ ] Web Dashboard - [ ] Agent 版本管理 + 灰度发布 - [ ] 计费系统 - [ ] K8s 部署 + 自动伸缩 - [ ] A2A 服务发现集成 --- ## 设计原则 1. **lambdagent 零侵入**: AgentPaaS 只包装,不修改 lambdagent 内核 2. **API First**: 所有功能通过 API 暴露,Dashboard 和 CLI 都是 API 的消费者 3. **渐进式复杂度**: 单机 SQLite 可跑,生产上 PostgreSQL + Redis + K8s 4. **形式化可追溯**: 保留 lambdagent 的 β-归约 trace,上层增加分布式 trace 5. **开放集成**: 支持 MCP、A2A 等开放协议,不锁定用户 --- ## 实现进度(v0.1.0) ### 已完成 ✅ - **API 层**: FastAPI 28 个端点,Agent CRUD + 执行 + 认证 + 管理 - **Engine 层**: Job Queue (内存/Redis) + Sandbox (L0/L1) + Dispatcher + Worker + 重试/熔断 - **Registry**: Agent 版本管理 + 回滚 + Canary 流量路由 + A2A 发现 - **Tenant**: 多租户隔离 + Token 配额 + 并发限制 + RBAC (admin/dev/viewer) - **Observability**: 结构化日志 + Prometheus 指标 + lambdagent Trace 桥接 - **Secrets**: AES-256-GCM 加密存储 + 执行时注入 - **Billing**: Token 计量 + 6 模型定价 + 月度报告 - **CLI**: Provider 管理(7 内置 LLM 提供商 + 自定义接入) - **Tests**: 70 个单元测试,全通过 - **CI/CD**: GitHub Actions (Python 3.10-3.12) - **Docs**: MkDocs Material 文档站 ### 待实现 ⬜ - L2 容器级沙箱 (Docker-in-Docker) - Web Dashboard (React + React Flow) - K8s Helm Chart - Webhook 通知 - 完整 RBAC 中间件强制执行