AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(custom-agent): deliver identity routes, ACP admission, and E2E

Abierto
#444 2 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

> 由 #150 毕业的后续实施票,不进入 #144 本轮冻结执行 snapshot;本次仅建档,不启动实现。DRI 容量、真实身份/Registry/Kubernetes 资源与评审窗口尚未确定,Start/Target 留空。

## Problem

当前 main 已具备自定义镜像 Tag-to-Digest/Runtime Manifest 准入(#188)、Custom Agent 配置与身份责任保存、Owner Web 表单、升级时模式和身份责任保持(#313),并已定义三类 Workload route contract;但尚无 Auth Gateway 实现,`platform-worker` 的真实 Kubernetes 调谐仍由 #190 交付,Generic ACP 核心 Driver 仍由 #438 交付。现有 Web 只展示 `self-managed + self-managed identity` 的直接入口,不能证明平台身份入口、实际路由、`platform-adapter` ACP 准入、升级保持或两种模式的真实 E2E。若只依赖字段、Fake、健康检查或 OpenCode 的 Generic ACP 核心测试,M1 自定义 Agent 仍不可验收。

## Scope

- 在现有 Platform、Identity 和部署访问路由边界内实现自有交互入口的 Auth Gateway,不新增身份目录、独立产品权威或新的部署单元。定义所需的版本化签名上下文 Schema、生成产物、部署绑定 Port/Fake 和消费方 contract tests;上下文只包含工程 Spec 要求的稳定用户、Agent、issuer、audience、签发/过期时间、唯一 context ID 与 key version 等最小绑定。
- `self-managed + platform-managed identity` 的每次请求先通过部署 IdentityAdapter 解析当前账号和组织关系,再按 Agent 当前可用范围校验;Gateway 移除或覆盖调用方身份 Header,签发短期上下文并只转发到该 Agent 的内部 Service。自定义 Agent 服务端必须校验签名、issuer、audience、有效期、key version 和 Agent 绑定。权限撤销后新请求立即拒绝;长连接按短期上下文到期或受控关闭。
- `self-managed + self-managed identity` 只发布 Owner 自有身份路由,不经过 Auth Gateway,也不注入平台 IdentityContext、Execution Grant 或撤权上下文。提供受控样例服务,在服务端拒绝匿名、伪造身份字段及 Owner 身份体系中无权限的请求;平台不把该结果解释为公司账号或 Agent 可用范围已执行。
- 复用 #190 的 StatefulSet/Service/NetworkPolicy/路由调谐与升级状态机,补齐 Custom Agent 的最终装配:每个 `self-managed` Agent 根据 Platform DB 中保存的身份责任只产生一条用户路由,Service/Pod 地址和未选入口不可达;候选修订/路由切换并重新调谐后旧路由被删除,升级仍保持原身份责任。不得在本票实现第二套 Kubernetes reconciler。
- 复用 #188 的 Manifest 结果和 #438 的唯一 Generic ACP Driver,将 `platform-adapter + protocol=acp` 候选 Workload 接入现有 RuntimeHost。本票消费 #438 的模型发现/当前选择/设置映射,健康检查通过后执行 ACP 核心探测,只有核心探测通过才开放平台 Web 入口;有效 capability 取 Manifest 声明与实际探测交集。模式不匹配、未知协议、核心探测失败或 `self-managed` capability 声明均不能开放 Platform Conversation、模型、文件或 Connection 能力。
- 提供一个受控 `self-managed` 样例镜像和一个受控 Generic ACP `platform-adapter` 样例镜像,并通过部署批准的 Registry 以不可变 Digest 使用。至少一个获准样例不继承 M1 Base Image,以证明 Base Image 只是推荐方式;镜像仍必须独立满足 #188 准入和部署政策。
- 补齐 Web/投影的入口行为:两种 `self-managed` 身份责任均只展示服务端投影的对应 HTTPS 入口;`platform-adapter` 只进入平台对话页,不显示自有入口。浏览器不能提交或拼接 Service/Pod 地址、Agent 身份、身份 Header 或路由选择。
- 对 Custom Agent 创建和 Owner 发起的 A-to-B 升级做完整装配验证。升级必须保持原 `interactionMode` 和 `identityResponsibility`;候选模式不一致、健康检查或 ACP 核心探测失败时拒绝 C,C 不接收流量,旧 Digest、唯一旧路由和平台历史继续可用或被恢复。
- 本票只验收文本和可选 Runtime 模型选择。附件、结果文件与 ObjectStorage 实现由 #150 的独立文件票负责;Connection 集成和最终完整 M1 验收仍由 #150 负责;平台托管企微文本由 #440 负责。本票不得复制这些实现,未交付能力保持不展示/不可用。

- 本票负责把 #438 的原生模型发现接到平台可用入口:先对齐 Runtime HLD/工程 Spec 中必要的 Host/Worker/Web 契约并完成消费方评审,再实现当前列表/当前选项的读取、提交前重新确认与失效拒绝。当前 Driver/Host 没有模型列表操作,不能只补布尔 capability 或硬编码 Web 列表;原生协议对象与 ID 的封装沿用 Host 边界。
- 自定义 Agent 的模型配置、endpoint/credential 与可选项由 Runtime/Owner 管理,不消费或扩展 #436/#437 的标准模板 ModelCatalog。直接复用 #438 的 ACP transport 和映射,不新增 ACP 分叉,也不继承上游自动授权或模型回退默认值。

## Acceptance criteria

- [ ] **AC-1:** `self-managed` 两种身份责任各自只生成一条可用 HTTPS 用户路由;Agent Service、Pod 地址和未选入口不可达。停止、重启、停用、Worker 重启和重新调谐后路由与当前配置修订一致,不出现双路由或绕过路径。
- [ ] **AC-2:** 自有身份入口由样例服务端拒绝匿名、伪造调用方身份和无权限请求,合法身份按 Owner 身份体系成功;该入口不获得平台 IdentityContext、Execution Grant、Agent 可用范围或撤权上下文,历史不进入 Platform DB。
- [ ] **AC-3:** 平台身份入口每次请求执行当前账号/组织/Agent 范围校验,覆盖调用方身份 Header,并传递短期签名上下文。Gateway 拒绝已撤权或无当前权限的入口请求;样例服务端对缺失、篡改、过期或错误 issuer/audience/key version/Agent 绑定的上下文,在应用副作用前拒绝。合法请求到达样例服务,调用方身份 Header 被覆盖且不能改变最终身份。
- [ ] **AC-4:** 获准的 `platform-adapter + ACP` 镜像只有在实际 Workload 健康且 #438 Generic ACP 核心探测通过后才进入平台 Web 对话;模式不匹配、未知协议、核心探测失败或失败候选均无用户流量。不能以 Manifest 声明、Fake Driver 或 OpenCode 模板成功替代自定义镜像探测。
- [ ] **AC-5:** `platform-adapter` 的模型选项来自 Runtime 当前返回值,选择在提交前重新确认并原样转发;失效选择明确拒绝且不静默换模型。Manifest capability 与探测结果的交集唯一决定入口能力;`self-managed` 声明 capability 不产生平台能力。列表/当前选择能经实际 Host/Worker/Web 链路回读;列表在展示后变化时提交重新确认;选项被移除或失效时在 Turn 副作用前拒绝且不自动选第一项。自定义模型配置保持 Runtime/Owner 归属。
- [ ] **AC-6:** A-to-B 升级保留 `interactionMode`、`identityResponsibility`、唯一入口和适用的平台历史;模式不一致或无效候选 C 不接收流量并保留/恢复 B。测试直接消费 #313 的保持规则和 #190 的升级结果,不在路由、Web 或 Adapter 重写第二套策略。
- [ ] **AC-7:** 浏览器只使用服务端返回的安全 HTTPS 入口或平台 Conversation route;伪造 Agent ID、路由模式、Service/Pod 地址和另一 Agent 的入口按资源不存在或稳定拒绝处理;调用方身份 Header 被移除/覆盖且不能改变可信主体,且日志、错误、审计和证据不泄露签名上下文、密钥、内部地址或普通会话正文。
- [ ] **AC-8:** 两个实际样例镜像均绑定 source SHA、不可变 Digest、Manifest、扫描/准入记录和 Runtime 版本;其中至少一个不继承 M1 Base Image 仍可正常准入。实际 Kubernetes、IdentityAdapter、Auth Gateway、浏览器和 Runtime 的正负 E2E 通过;实际 Generic ACP 自定义样例的两个有效用户分别通过正向任务,并验证 Conversation/Session、工作区、个人记忆和 Runtime 上下文在并行及重启后保持隔离,不能用 OpenCode 模板或仅历史查询测试替代。证据绑定配置修订、Workload UID/generation、唯一 route ref 和探测结果;附件隔离由后续文件整装票承担。
- [ ] **AC-9:** 附件、结果文件、Connection 和企微未被本票伪装成已交付;对应 capability/入口在依赖未完成时不展示或明确不可用。本票完成只证明 Custom Agent 的两类文本入口与升级闭环,不证明完整 M1 上线。

## Validation

- 运行 Auth Gateway Schema/Fake/部署 Adapter conformance,覆盖身份 Header 覆盖、签名、issuer、audience、时间、context ID、key version、Agent 绑定、账号/组织/范围变化、依赖不可用和长连接失效;身份授权失败和非法签名上下文在应用副作用前 fail closed;仅伪造调用方身份 Header 时验证覆盖后的正确主体,不能把覆盖语义误写成一律拒绝。
- 运行 #190 的实际 Kubernetes 集成矩阵,覆盖三种 route contract、单路由、内部 Service/Pod 隔离、停止/重启/停用、Worker 崩溃、stale revision、升级候选、失败清理和旧路由删除。不得用 contract fixture 代替实际资源及网络可达性证据。
- 对受控 `self-managed` 样例执行自有身份和平台身份两组实际 HTTP/长连接正负测试;对受控 `platform-adapter` 镜像执行真实 Generic ACP 核心、文本、模型选项、失效选择及 capability 探测。样例按部署批准 Registry 的 Digest 部署,不使用本地 image ID 或 Fake Registry 冒充。
- 使用 Playwright 从申请、审批、创建到 Agent 详情/平台对话执行两类入口;覆盖无权限用户、账号禁用、组织变化、伪造 Header/URL、A-to-B 升级、候选 C 拒绝和浏览器重载。分别断言自有入口历史不进入平台;对实际 platform-adapter 样例以两个有效用户完成正向任务,核对独立 Conversation/Session、文本历史、工作区、个人记忆和上下文,覆盖并行与重启后的隔离。文件访问仍由后续文件整装票验证。
- 回读 source SHA、两个镜像 Digest、Registry 准入、配置/Workload 修订、Workload UID/generation、route ref、IdentityAdapter/Auth Gateway 版本和 Generic ACP Runtime/探测证据;秘密与普通会话正文只保留脱敏摘要。真实资源缺失时保持对应 AC 未验收,不以 Fake、healthz 或旧版本证据替代。
- 执行 `AGENTS.md` 完整仓库验证序列及 current-head Standards/Spec/consumer Review。涉及 Connection、ObjectStorage/files 或企微的场景仅验证保持关闭,不执行其运行测试。

- 对实际 ACP 自定义样例验证模型列表/当前选择的读取、提交前列表变化/选项撤销、能力缺失及跨 Agent/Conversation 访问;验证模型配置不经标准 ModelCatalog,原生映射复用 #438。

## Blocked by

- #190
- #192
- #438

## Authority

- Agent Platform PRD §§5、7、14;工程 Spec §§10、14.3、19、24;Runtime HLD §§3、4、9、11。正式依据为 `main@f0e8aa58ca90dec2583459818c1167781979235f`。
- #188 是 OCI/Digest/Manifest 准入的唯一实现,#313 是升级时模式和身份责任保持的唯一领域策略,#190 是 Kubernetes 调谐/路由/升级的唯一实现,#438 是 Generic ACP Driver 的唯一核心实现。本票只完成这些产物与 Auth Gateway、样例和 E2E 的最终装配。
- #440 独立交付平台托管企微文本;ObjectStorage/files 草稿另行处理;Connection 合约冲突 #432 解除前不实施任何 Connection 路线。最终完整 M1 验收仍由 #150 毕业,不由本票替代。

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.