适合谁读：想把 Agent 交给业务系统去调、正在纠结「包个接口还是上个平台」的后端同学；系列前三篇读过更好，没读也能跟上。预计阅读：主线 14 分钟（3 张按需查阅的表不算在内）。

从五个容器和一个小意外说起

写这篇的实测从拉镜像开始。按官方文档，init-env.sh 生成密钥、docker compose pull、up -d --wait，三步。镜像放在阿里云杭州的 registry，匿名就能拉——但本机 Docker 配了 daocloud 加速器，其中一个底层 blob 连续三次 EOF，第四轮重试才续传成功。这种毛边先记下，正文实测段还有它。

栈起来之后是这样的：postgres、control、data、scheduler、gateway，五个容器。我照着 compose 文件核对各容器健康检查时注意到一处不对劲：其他四个平面查的都是 curl /actuator/health（Spring Boot 的标准姿势），唯独 control 容器是一句 /service-controlplane --healthcheck——一个二进制在自检。再翻 service-controlplane/ 目录：一个 go.mod、551 个 Go 文件、Java 文件为零。一个叫 AgentScope Java 的项目，平台的账房中枢是 Go 写的——这是本篇第一个、也是我卡得最久的一个认知更新。

系列前三篇读的都是「一个 Agent 的内部」：中间件怎么摞（第 1 篇）、记忆怎么存（第 2 篇）、技能怎么转正（第 3 篇）。这篇读最外层：这些内部件怎么被组装成一个给别人调用的服务。也是完结篇，最后一节会把四篇串回一张图。

这层在解决什么问题

选型-11（《AgentScope Java vs Spring AI：塞进 Spring 应用，还是独立成平台》）留了一个尾巴：AgentScope 选了「独立成平台」，那平台长什么样？agentscope-service 就是答案的实体。

没有这一层时，你把一个 HarnessAgent 交给业务方，至少要自己补四件事：谁来鉴权（业务系统的凭证怎么发、怎么轮换）；谁来做审计（哪次调用、花了多少 token、产出了什么文件）；人怎么介入（Agent 要删库时谁按暂停）；结果怎么交付（跑完的产物怎么变成业务系统里可验收的东西）。README 第一句——An Agent as a Service platform——就把定位说完了：submit work through APIs, stay involved, and retrieve reviewable results——提交、盯着、拿回可审查的结果。

所以这个模块真正交付的不是「Agent 的 HTTP 化」，是一套执行账本：发布物（Endpoint）、执行实例（Invocation）、事件流、审批位、产物库。下面按这个顺序拆。

四个平面怎么分工

生产部署形态就是 compose 里那五个容器的关系（下图）。每个平面都有明确的两张清单——管什么、不管什么。README 里那张「owns / does not own」表是我见过最省事的架构文档写法，直接抄意：

图 1 · 四个平面 + 三种执行器 + Invocation 状态机（v2.1.0-BETA1）

「不管」那一列比「管」更有信息量：控制面不做推理、数据面不读目录、调度器不碰循环——每条都是一次边界决策。

网关薄到什么程度？GatewayApp.java 连注释带 license 一共 44 行，就是一个 SpringApplication.run。全部个性在 application.yml 的路由表里，有三处我标了记号：

1. 内部接口在门口就掐死：/api/internal/** 匹配即 SetStatus=404（order -1，优先于一切）。平面之间的内部调用根本不走公网网关，万一有人从外面探测，得到的不是 403 而是 404——不承认它的存在。
2. 客户端伪造的内部头一律剥掉：default-filters 里两条 RemoveRequestHeader=X-Builder-Internal-Token / X-Builder-Internal-User。注释原话：绝不把客户端自带的内部鉴权头转发进去。
3. SSE 长连接超时放到 1 小时（response-timeout: 1h），注释写明是为了事件流不被默认超时掐断——事件流是这个平台的「返回值」，掐断等于把函数调用的 return 丢了。

路由的优先级也讲了故事：会话事件（/api/sessions/*/events/**）和数据面工作队列 order 0 先判，因为它们和控制面的 /api/sessions/** 命名空间重叠；/api/outbound/** order 5 必须压过控制面的渠道 CRUD，否则 IM 回调会被路由到错误的家。

为什么这样设计

控制面用 Go、数据面用 Java，是「账本」和「引擎」的分工。 控制面管的是产品资源、发布、调用记录——无状态偏多的 CRUD 和协调逻辑，Go 单二进制部署、镜像小、启动快，还能顺手复用 Kubernetes 的 controller-runtime（CRD 调谐器，本地开发用 CONTROL_PLANE_ENABLE_KUBERNETES=false 关掉）。数据面则必须长在 HarnessAgent 身上——SessionTurnRunner 的 import 列表就是证据：io.agentscope.core.session.*、io.agentscope.harness.agent.HarnessAgent，全是系列第 1 篇读过的那些类。让 Java 写业务、Go 管账，比「全栈一门语言」的教条诚实。

数据面不读目录表，执行材料一律由控制面 resolve 结果带过来。HarnessAgentBuildService 的 javadoc 写得很硬：托管会话的 Agent 实例只从控制面 resolveSession 返回的快照构建（agentSnapshot、workspacePath、definitionFiles），「没有 JPA 目录回退，resolve 必须成功且快照非空」。也就是说数据面没有自己的「事实来源」，只是执行者。好处是多副本数据面天然无目录竞争，坏处是控制面成了单点依赖——它用 DataPlaneSelfRegistration（默认关，builder.dataplane.register-enabled=true 才开）加 15 秒心跳的自愿注册来补发现问题。

发布即追加，而不是原地改。Endpoint 是对外的稳定承诺（slug、输入输出 Schema、超时、限流），EndpointRelease 是每次部署/回滚追加的一条不可变记录（Number 递增、带 Reason 和 ActivatedAt）。要灰度要回滚，都是激活另一条 Release，公开 slug 和契约不动。调用方集成的稳定性不是靠「大家小心别改接口」，是靠数据结构不许改。

一轮对话一把租约，事件入箱出箱。SessionTurnRunner.runTurnAsync（L272 起）的开场是一把 TurnLeaseService.acquireOrConflictFenced——带围栏令牌的排他租约，fenceToken 形如 run:{runId}，中断请求必须带上匹配的令牌才生效，「陈旧的中断信号永远不能打断新一轮」。拿到租约后先 beginManagedExecution 向控制面立账，再起一个 10 秒一次的心跳（L397-407），跑完 endManagedExecution 销账。事件侧配 ManagedEventOutbox：事件必须在源事务内入箱（不在事务里直接抛 IllegalStateException），由后台任务 at-least-once 地投递到控制面；每个 attempt 有围栏，sealed 之后「永久封条」，晚到的旧事件想改账会被拒。

跟我读源码：四个入口和三张表

必读文件按顺序（Java 侧在 agentscope-service/ 下，Go 侧在 service-controlplane/ 下）。第一次读只精读下面第一张表，其余两张按需查阅：

表 1（核心，必读）：Endpoint——对外服务的全部承诺（agent_endpoint.go L54-79）

表 2（按需查阅）：EndpointInvocation 状态机（L128-137）

accepted → dispatching → running → waiting / cancel_requested，终态五个：completed / partial_succeeded / failed / cancelled / timed_out（contract.go 的 Terminal() L103-105 圈定）。waiting 就是等人审批的暂停态；partial_succeeded 这个终态值得注意——多 Agent 协作里「跑了一半、部分成功」被当成一等公民，而不是硬凑成成功或失败。

表 3（按需查阅）：EndpointCredential（同文件）

应用方凭证：KeyPrefix（可展示的前缀）+ SecretHash（只存哈希）+ SecretCiphertext（AES-GCM 落库加密，仅供授权 reveal，正常响应里不序列化）+ RotatedFrom（轮换链）+ 状态三值 active/revoked/expired。凭证不亮明文、可轮换可吊销，这是给业务系统发钥匙的标准做法。

另有三处小而硬的细节：invocation/contract.go 编译 JSON Schema 时把外部 $ref 直接禁掉（LoadURL 返回错误："Service contracts cannot cause server-side network requests through $ref"——契约文件不能驱动服务端发网络请求，防 SSRF）；EndpointRelease.Contract 字段标了 json:"-"，契约内容不随响应外泄；helm values 里 workspaces 卷必须 ReadWriteMany（控制、数据、调度三个 pod 共享同一工作区），这是四平面共享文件的前提。

一次完整调用走一遍（带实测输出）

实测环境：Windows 11 + Docker 28.3.0，官方镜像 sca-registry.cn-hangzhou.cr.aliyuncs.com/agentscope/as-{controlplane,dataplane,scheduler,gateway}:2.1.0-BETA1，init-env.sh 生成的随机密钥，docker compose up -d --wait。

然后走一遍最小链路：登录拿 token → 建托管 Agent → 建会话 → 发一条消息 → 看结果。

turn 被受理后返回一张回执：turn id、事件流地址（SSE）、快照地址。之后一路代码是这样走的：网关把 /api/v1/agent-sessions 转给控制面（Go）记账、建会话；数据面 SessionTurnRunner.runTurnAsync 先做已删会话护栏检查，拿 TurnLease（围栏令牌），beginManagedExecution 立账，状态置 RUNNING；HarnessAgentBuildService 用控制面 resolve 来的快照现场拼一个 HarnessAgent（实例 ID 前缀 dpa-，缓存在 ConcurrentHashMap）；然后才是第 1 篇读过的那摞中间件跑推理循环，每 10 秒一次心跳上报，事件在源事务里进 ManagedEventOutbox 再异步镜像给控制面。

我这条消息故意没配模型 key，想看平台在「跑不起来」时怎么表现。8 秒后查快照：

两处细节值得停一下。stopReason.code 是 turn_failed——正是 SessionTurnRunner L439 failTurn(session, ex, "turn_failed", ...) 里那个字符串，日志的类名也对得上，一条调用链从源码读到了实物。更值得注意的是 "status": "active"：会话没废，失败被记在账上，配上 key 发下一条消息即可复用同一个会话——执行失败被当成账目而不是灾难，这是「账本」设计的直接好处。

最后，因为没配模型、也没接沙箱，HITL 分支这次实测没触发到——waiting 状态和审批回调链路（resumeDurableTurnAsync 处理 kind:"confirmation" 的回答，L221-266）我只读了代码没跑通，这条标记为待核实，等补了模型 key 再验。另一个没验到的：SSE 事件流（/events/stream）在这次失败场景下我没消费到条目（快照里账是齐的，事件镜像为什么没到列表没查清），同样标待核实。

调试断点放哪

怎么扩展

最值得抄走的设计

「不管什么」清单和代码一样重要。 这个仓库每个平面的职责都配了明确的 does-not-own 列表。多数架构文档只写「负责什么」，不写「明确不负责什么」——后者才是防止边界腐烂的机制。抄走：给你的每个服务写两张清单。

发布即追加（append-only release）。 对外契约的每次变更都是一条不可变记录，回滚是「激活旧记录」而不是「改回去」。这招不新鲜（数据库 migration、基础设施即代码都这么干），但用在「Agent 服务发布」上刚刚好，因为 Agent 的行为定义是软的、易变的，更需要一个硬的发布史来兜底。

围栏令牌（fence token）。 TurnLease 不只是「我有锁」，而是「我的锁带编号，中断信号必须报出编号才生效」。分布式系统里最难的一类 bug 是「旧信号打断新任务」，fence 是教科书解法，这里是我在 Java Agent 框架里见到的最完整的落地（租约 + 心跳 + 围栏 + 事件封条四件套）。

BETA 期的诚实标注。 README 写明「项目尚未发布、v4 故意替换旧执行 schema」；helm Chart 明说单副本、Recreate 更新、「不承诺零停机升级和 HA」；本地开发栈的演示账号标了「仅限本地」。把边界写在明处，和第 3 篇扫描器 javadoc 自认「不是安全边界」一脉相承——这套仓库的文档纪律值得单独学。

没覆盖的部分：Console 前端（frontend/）、Kubernetes CRD 调谐器（internal/controller，本地栈关掉了）、ASDP gRPC 接入协议、Team/Workflow 编排——前两个没有 K8s 环境，后两个没跑通真实场景，我不想凭静态阅读硬写；想看的留言，v2.1.0 stable 出来后我补一篇升级实测。

系列四篇，串成一句话

建议的阅读顺序

先 gateway 的 application.yml（十分钟建立全局地图），再 agent_endpoint.go 的三个模型（对外契约），然后精读 SessionTurnRunner.runTurnAsync（执行生命周期的全部难点），最后 HarnessAgentBuildService（快照到实例）。Go 侧 internal/invocation/ 三个文件放第二遍；scheduler 除非你要接 IM 渠道，可以最后看。

读完后你该带走什么

为什么需要它（把执行变成可交付、可审计、可接管的账本）、它怎么跑（四平面分工 + 一轮一租约一心跳 + 事件出箱）、你该改哪（provider 和渠道是留好的口子，Release 不可变和内部 API 边界是命门）。以及一个可以带走的判断：评估任何「Agent 平台」类产品，先看它有没有这五样——发布契约、执行状态机、事件流、审批位、凭证管理。缺哪样，哪样的成本最终会转嫁到接入方头上。

#agentscopejava #agent

聊聊：你们的 Agent 现在是怎么交给业务方的——直接包个 HTTP 接口、塞进现有系统、还是也上了类似平台？踩过「演示能跑、一上线就废」的坑吗？想深聊的同学：三种执行器（托管 Harness / 接外部应用 / 纳管 Claude Code 这类 CLI），你会先上哪种、为什么？