ISOMETRY · PRODUCT REQUIREMENTS · 2026.10.26
把能力交给 Agent，
把控制留给自己。
Agent Gateway 产品需求文档 · v0.2 · 讨论稿
用户集中保管上游 API Key，向每个 Agent 签发独立的、受限的使用凭证。网关在每次调用前执行授权策略，并记录可追踪的使用结果。
交付状态：本次提供浏览器交互 Demo 与产品方案。尚未实现真实代理、密钥托管、账单、认证、并发预算或安全隔离。本文中的正式产品能力均为规划，不能视作已上线承诺。
01 / 问题与目标用户
用户把同一服务商的 Key 复制到多个 Agent、脚本和自动化工具后，难以按 Agent 撤销权限、分辨支出或限制使用范围。真实需求是“安全地委托能力”，而不仅是“存放字符串”。
首批用户：持续使用多个 Agent 的独立开发者、工作室与小型研发团队。优先服务已有模型 API 消费、愿意修改 endpoint 的用户；不以偶尔使用单一聊天产品的消费者为首发人群。
| 任务 | 期望结果 |
|---|
| 给临时研究 Agent 一周访问权限 | 限定模型、总费用和到期时间，到期自动失效 |
| 给外包开发配置模型服务 | 不用发送主 Key，项目结束可单独撤权 |
| 排查异常消耗 | 能定位到 Agent、模型、时间与授权决策 |
02 / 定位与成功标准
定位：面向多 Agent 工作流的授权与费用控制网关。价值主张是低成本接入、清晰授权、即时撤权和可核查的调用记录。
现有产品验证了方向，但不是需求规模或付费意愿的证据：LiteLLM 已支持虚拟 Key 和预算；Composio 提供 Agent 服务认证。Isometry 的差异化假设是更易用的个人／小团队授权体验，仍需访谈和真实接入验证。
试点目标（待验证，不是现状）：招募 10 位符合画像的用户，至少 5 位接入真实工作流，至少 3 位连续使用两周，至少 2 位明确接受付费试用。首次授权到成功调用中位时间目标小于 10 分钟；拒绝策略必须在自动化验收中 100% 命中；Key 不出现在客户端与日志中。
03 / MVP 范围
| 优先级 | 能力 | 边界 |
|---|
| P0 | 服务凭证保险库 | 首批 OpenAI 与 Anthropic；增加、替换、停用凭证；不支持任意目标 URL |
| P0 | Agent 独立授权 | 按服务、模型白名单、有效期、月预算和速率限制授权；凭证仅创建时展示 |
| P0 | 推理代理 | 明确支持的文本生成端点与 SSE 流式响应；发布前完成 SDK 兼容性测试 |
| P0 | 权限执行与撤销 | 所有请求在转发前校验；撤销不影响其他 Agent |
| P0 | 日志与用量 | 请求元数据、状态、费用估算、拦截原因；不默认记录提示词和输出 |
| P0 | 自托管交付 | Docker Compose、配置向导、备份恢复说明；本地默认仅监听 loopback |
| P1 | 云端工作空间 | 成员、RBAC、托管密钥、审计与订阅；P0 验证后交付 |
| 不做 | 万能 API 权限代理 | 首版不代理邮箱、GitHub 写入、数据库或支付；不宣称理解所有 API 操作语义 |
Demo 展示三家初始服务和可添加的 Mistral，仅用于交互展示，不能据此认定正式兼容性。
04 / 核心流程与界面
- 连接服务：选择支持的服务商 → 提交 Key → 后端加密存储 → 可选最小验证调用，清楚说明可能产生费用 → 返回掩码与状态。
- 授权 Agent：名称 → 服务与模型 → 预算、速率、有效期 → 生成独立凭证 → 仅展示一次 → 复制对应 SDK 配置。
- 调用：Agent 使用网关 endpoint 和虚拟凭证 → 鉴权与预算预留 → 注入上游 Key → 转发 → 结算实际用量 → 写入脱敏日志。
- 管理：从 Agent 详情调整额度、轮换或撤销；敏感动作写入审计。
- 排查：从日志筛选失败请求，区分策略拒绝、上游错误和网关故障，并查看 request_id。
| 页面 | 信息与操作 |
|---|
| 概览 | 服务数、活跃 Agent、周期费用、拦截数、用量趋势和预算摘要 |
| 密钥保险库 | 服务连接状态、掩码、关联授权数、轮换与停用 |
| Agent 授权 | 列表、策略详情、新建、调整预算、撤销、轮换 |
| 调用日志 | 筛选 Agent／结果／时间，分页，脱敏导出 |
| 授权测试 | 沙盒策略检查；正式调用必须独立显式触发并提示费用 |
| 部署与方案 | 说明本地与云端的密钥保管责任和可用性差异 |
05 / 数据与接口草案
Workspace 包含成员与部署模式；ProviderCredential 保存 provider、密文引用、掩码、版本与状态；AgentGrant 保存凭证哈希、关联服务、模型白名单、预算、有效期、速率、状态；UsageLedger 保存预留与结算流水；RequestLog 保存请求 ID、Agent、模型、决策、延迟、token 用量和费用；AuditEvent 记录策略与凭证变更。
管理接口草案：POST /credentials、POST /grants、PATCH /grants/:id、POST /grants/:id/revoke、GET /usage、GET /requests。代理使用独立前缀或域名，禁止 Agent 凭证访问管理接口。供应商兼容路径由适配器明确定义。
正式错误合同：401 无效凭证；403 已撤销／模型不允许；429 额度或速率限制；上游 429、5xx 与网关错误保持来源标记；超时给出稳定错误码与 request_id。Demo 为便于展示将所有策略拒绝统一显示为 403。
06 / 安全与费用约束
- 信任边界：本地版密钥在用户环境；云端代理必须能解密并使用 Key，因此属于受信任托管方。不可宣传“云端永远接触不到 Key”。同机 Agent 若拥有与网关相同的系统权限，单纯隐藏 Key 不能构成隔离，需要独立用户、容器或远程部署。
- 凭证：高熵随机虚拟 Token，仅存哈希；真实 Key 使用 envelope encryption，主密钥与数据库分离；云端接入 KMS，传输使用 TLS。
- 转发限制：固定供应商域名、固定允许路径与方法、禁止任意重定向、清理入站认证头，限制请求大小，防止开放代理与 SSRF。
- 日志：默认排除 Authorization、真实 Key、完整请求与响应正文；脱敏导出；云端默认保留 30 天（待成本与用户需求验证），支持删除与保留策略。
- 并发预算：转发前原子预留“输入已知成本 + 最大输出成本”，不足即拒绝；完成后结算、释放差额。流式请求需要输出上限；未知价格、无法界定费用的调用默认拒绝。不得仅在调用结束后累加支出来宣称硬额度。
- 账单：费用是依据价格版本计算的估算，供应商账单为准。断流、超时与未知结算需进入待核对状态；禁止自动重试可能重复收费的生成调用。
- 撤销：新请求在撤销成功后拒绝；已在途请求可能产生费用，界面需明确。多实例缓存必须失效，策略服务不可用时 fail closed。
07 / 验收清单
| 场景 | 预期 |
|---|
| 用合法授权请求允许模型 | 成功转发，Agent 身份、用量、费用和 request_id 可关联 |
| 请求其他模型／过期授权／撤销授权 | 转发前拒绝，不接触上游；日志含明确原因 |
| 两个并发请求争用最后一份预算 | 原子预留防止二者同时透支，无重复结算 |
| 上游限流／流式断开／网关超时 | 错误来源可区分，预留安全处理，未知费用标记待核对 |
| 轮换上游 Key | 新请求切换到新版本，Agent 凭证无需改变；旧凭证安全清理 |
| 跨工作空间访问 | 管理和日志查询均拒绝，不能枚举其他用户资源 |
| 查看浏览器存储／错误／日志 | 不出现真实 Key 或可复用的管理凭证 |
| 本次 Demo | 可新增服务、授权 Agent、调整额度、撤销、测试拒绝、筛选与导出日志；重置可恢复样例 |
08 / 开源与商业化
开源版：保持可实际使用的核心代理、授权与审计能力；建议评估 Apache-2.0 与 AGPL-3.0 对社区采用、二次托管和商业兼容的影响，许可证未定。
收费版：出售托管便利、持续在线、团队治理和服务保障；上游 API 仍由用户自己的服务商账户结算。初步测试“工作空间订阅 + 活跃 Agent 档位”，不在访谈前确定价格，不默认抽成模型费用。
云端成本需要核算每百万请求的计算、日志存储、出站流量与支持工时；以真实试点数据确定免费额度、限额和定价。
09 / 交易所与钱包扩展（Mock）
v0.2 新增 Binance、OKX 和 Ethereum 钱包，仅用于产品演示，不改变首发真实代理只覆盖模型 API 的边界。服务商字段与权限是示意，真实集成前需验证官方 API 和账户权限。
| 连接类型 | 保管对象 | 模拟权限 |
|---|
| Binance | API Key / Secret 虚构标识 | 只读，或 BTC/USDT 现货交易；提现与划转禁用 |
| OKX | API Key / Secret / Passphrase 虚构标识 | 只读，或受单笔 USDT 名义金额限制的现货交易 |
| Ethereum 钱包 | 本地签名器概念引用，无私钥材料 | 余额查询，或 Ethereum / USDC / 演示白名单收款对象的转账意图；每次需人工确认 |
费用语义：模型费用按美元累计；交易所额度为单笔订单名义金额 USDT；钱包额度为单笔转账数量 USDC。三者不相加。钱包余额是静态示例，模拟签名不改变余额。
签名流程：Agent 提交意图 → 校验权限、有效期、网络、资产、白名单和额度 → 待人工确认 → 再次校验 → 记录模拟完成。用户可以拒绝；日志区分 pending、rejected、blocked 与 simulated。
不实现：真实订单、提现、链上广播、私钥或助记词导入导出。不生成或索要真实密钥。私钥不能作为 API Header 注入；正式产品需独立签名器和交易内容校验。自托管优先隔离的本地签名器，云端密钥托管与硬件/MPC 接入尚未决定。
真实开发前门槛：验证交易所最小权限、IP 限制、签名、时间同步与订单幂等；超时先查订单状态而非盲目重试。钱包校验 chainId、合约、方法、接收人、数量、nonce 和 gas，拒绝盲签与无限 approve；撤销不回滚在途交易。
验收：可新增、修改单笔额度、撤销；只读交易、提现、非白名单交易对/收款对象、超额和无限 approve 被拦截；合规钱包意图进入人工确认，确认或拒绝写入日志；旧会话补齐新示例并保留已有授权。
10 / 分阶段交付与开放问题
- 阶段 A：验证。用本 Demo 访谈 5–10 位用户，记录现有分发流程、事故、支出规模与接入阻力，确认愿意真实迁入的工作流。
- 阶段 B：自托管 MVP。完成两家供应商适配、管理认证、隔离、预算账本和集成测试；以真实低额度账户试运行。
- 阶段 C：云端私测。完成租户隔离、KMS、备份恢复、运维告警和成本测算后邀请试点付费。
仍需决定：Isometry 现有银行／资金产品与此模块的关系；首个目标 Agent 客户端；优先支持的 SDK 与 API 端点；部署地域、数据保留政策；开源许可证；团队付费意愿。阶段排期需在技术验证后估算，不承诺未经验证的上线时间。
本 PRD 对应交互 Demo v0.2。演示状态保存在浏览器标签页的 sessionStorage；没有真实密钥、真实调用和线上账户系统。