AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

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

Open
#444 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
8h 51m
Merged PRs (30d)
99

Description

> 由 #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 毕业,不由本票替代。

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.