AgentScope Service 技术解读：控制面、数据面与可恢复的 Agent 运行时

​

什么是 AgentScope Service（实现视角）

1. Managed Agents：控制面持有版本化 Snapshot，数据面按 Snapshot 构建 HarnessAgent 并跑事件化 Turn；
2. BYO Agents：已有 AgentScope / LangChain / Claude 等运行时通过扩展、instrument() 或 Sidecar 接入，进入同一舰队与 Session 观测模型。

​

为什么需要这样一套平台

1. 本机脚本 / CLI：状态在本地目录，适合个人，不适合多副本与审计。
2. 业务服务内嵌 SDK：每个应用各自实现 SessionStore、HITL、租约、事件回放与权限，成本重复且标准不一。
3. 低代码编排：把 Harness 工程细节外泄给业务配置者，平台难统一升级。
4. 单一托管运行时：效果好，但跨框架舰队、客户 VPC Hands、以及团队协作状态往往另起炉灶。

• 治理问题收敛到控制面与数据面契约；
• 推理内核收敛到 AgentScope Harness；
• 工具执行边界收敛到 Environment（Hands）。

​

整体架构

┌────────────────────────────────────────────────────────────────────────────┐
│                              Agent Service                                 │
│                                                                            │
│  Web Console ──► Gateway :8080 ──┬──► aistiod :8081 （CP / RT）            │
│                                  └──► dataplane :8082 （DP Brain）         │
│                                              │                             │
│                                              ▼                             │
│                                     PostgreSQL                             │
│                              cp · rt · dp schemas                          │
│                                              ▲                             │
│                                              │                             │
│                                     scheduler :8083                        │
│                              Channel / Cron / Hands Worker                 │
└────────────────────────────────────────────────────────────────────────────┘

​

平面职责

​

数据归属

​

一次 Turn 的完整路径

1. 客户端向已有 Session 追加 user.message。
2. Dataplane 获取 Turn Lease，并把 Session 标记为 running。
3. 控制面解析已固定版本的 Agent Snapshot、Environment、Workspace、Memory 与 Vault。
4. SessionTurnRunner 执行 HarnessAgent.streamEvents。
5. agent.message、agent.tool_use、span.model_request_* 等权威事件写入 PostgreSQL；可选 Preview Delta 仅用于打字机效果，不落库。
6. Session 回到 idle、因 HITL / Tool Result 暂停，或以类型化错误终止。

GET /api/sessions/{id}/events/stream?after={seq}

​

Brain 与 Hands

​

核心能力（实现层）

UI 截图请见产品版文章；此处聚焦机制。

​

Dashboard：舰队与运行时观测

• Agent / Instance 健康与在线清单
• Session phase（如 active / idle / compressing / archived / terminated）与 Turn 时长
• Context pressure、Token delta、错误计数
• Team 成员状态、任务进度、生命周期事件

• Session：可恢复的对话线程；phase 描述线程运营态。
• Turn：一次用户请求到回复的执行单元；时长统计应落在 Turn，而不是把 Session 存活墙钟时间误当成「活跃耗时」。

​

Managed Agents：版本化定义 + 事件化 Session

1. Session 创建是静态绑定
   创建时只记录资源关系，不跑 Agent；第一条 user.message 才启动 Turn。
2. Event-native
   入站事件驱动工作，出站事件描述进度与结果。每个持久化事件有 Session 内单调递增序号，客户端可断点续传。
3. HITL 作为一等公民
   Ask Policy 工具会暂停 Turn，发出确认请求；user.tool_confirmation 继续或拒绝，同时保留完整历史。
4. 权威事件 vs Preview
   SSE 可推送 event_start / event_delta 获得即时体验，但最终以落库事件为准。UI 刷新、多端恢复、审计回放都依赖同一真相源。
5. 版本 pin
   Session 绑定 Agent 的具体版本 Snapshot，避免运行中途定义被热更新导致不可复现轨迹。需要升级时，显式创建新 Session 或走产品定义的升级路径。

​

Agent Teams：跨 Session 的协作状态机

• Lead / Member 拓扑与动态成员（数量 / 白名单约束）
• 单播与广播消息
• 共享任务、Claim / Assign、Plan Approval
• 成员 Wakeup、优雅关闭、生命周期时限、故障恢复
• 消息与任务跨进程、跨 Session 保留

​

如何接入

​

AgentScope（原生）

​

LangChain

import aistio

aistio.instrument(
    app_or_client,
    control_plane="aistiod.aistio-system:9090",
    agent_name="my-langchain-agent",
    namespace="default",
    enable_events=False,  # Level 2 事件默认关，可按需打开
)

​

Claude SDK 与 Sidecar

• 主容器继续跑原有 CLI / Agent；
• Sidecar 观察本地 Session 目录（如 ~/.claude/）与运行状态；
• 向控制面上报舰队与 Session 信息，并转发可支持的运营命令；
• 必要时把 Session 文件态同步到外部存储，以支持跨节点恢复。

​

本地启动与验收

export DASHSCOPE_API_KEY=sk-xxx
cd agentscope-service
BUILDER_REBUILD=1 scripts/dev-up.sh
# Console: http://localhost:8080
scripts/smoke.sh

1. Managed Session：投递 user.message，从事件流恢复，刷新页面后序号续传正确；
2. HITL：触发 Ask Policy，确认后续跑，历史完整；
3. self_hosted：Worker poll / ack / heartbeat / 回传 tool_result，Turn 正确恢复。

​

几个值得提前避开的实现误区

1. 把 Preview SSE 当权威日志
   打字机效果可以丢、可以重连重建；审计、复盘、计费应对齐落库事件序号。
2. 让数据面本地缓存产品 Catalog 并在控制面不可达时静默回退
   短期看起来高可用，长期会出现「跑了未知版本」的最坏故障。宁可失败可感知，也不要静默用旧定义。
3. 把 Session phase 与 Turn 时长混用
   active / idle 描述线程态；耗时应落到 Turn。否则 Dashboard「谁最忙」会被长挂起会话误导。
4. 在 BYO 适配器里发明平行指标
   舰队 KPI 必须共用语义。新框架适配优先对齐契约，再谈特化字段。
5. 把 Team 消息塞进某个成员的 Session 事件流冒充协作状态
   Session 轨迹与 Team 状态机生命周期不同；混存会导致恢复、清理和权限边界全部出错。

​

Roadmap（工程视角）

1. 适配器覆盖面
   深化 LangChain、ADK、Claude、Qoder、OpenAI Agents 等 Level-1 / Level-2 / Context 能力对齐，减少框架特化字段，保证 Dashboard KPI 同义。
2. 生产级多租户与治理
   ACL、配额、审计、灰度发布、密钥轮换与更严格的 Environment 隔离策略；Vault / Memory 的生命周期与访问边界也会继续打磨。
3. Automation
   Deployment / Cron / Webhook / Channel 从「能触发」演进到「可编排、可回放、可补偿」。自动 Turn 一旦失败，要有类型化错误、重试策略与人工接管入口。
4. 事件驱动入口
   GitHub / GitLab、钉钉、企微等：把外部事件稳定映射为 Session Turn 或 Team Task，并保留幂等与鉴权边界。外部系统重试是常态，平台侧必须防重复开工。
5. Teams 与恢复
   动态成员、计划审批、成员失联恢复、跨 Session Restart，以及 Managed / BYO 混合组队的一致性。协作状态机比单 Session 更难，因为失败域跨多个 Runtime。

​

和「只嵌入 Harness」差在哪里

• 版本化 Agent 定义与 Session pin；
• append-only 事件与游标续传；
• Turn Lease 与 HITL ticket；
• Environment 切换与 Self-hosted Work Queue；
• 舰队注册、上下文压力、压缩 / 终止命令；
• Team 任务板与跨 Session 协作状态。

​

结语

1. 控制面管期望与运行状态，数据面跑 Turn，Hands 决定工具落点；
2. 持久化事件序列才是 Session 真相，进程内对象只是可丢弃的缓存；
3. Managed 与 BYO 共用舰队契约，框架差异收敛在适配器，而不是散落在 Console。