# 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 中间件强制执行
