Agent Substrate 架构解析

Tags:

Agent Substrate 不是用来开发 Agent 的框架，而是用来安全、高密度地运行 Agent 和 Sandbox 的基础设施运行时。

项目地址：agent-substrate/substrate（GitHub）

它主要解决一个问题：如果一个平台要为大量用户分别创建独立的 AI Agent 执行环境，如何同时实现安全隔离、状态持久化、快速唤醒和资源复用？

结合 Kubernetes 的视角，可以把它理解为：在 Pod 和容器之上，为有状态、间歇性运行的 Agent 增加一层专用的调度与执行管理系统。

1. 为什么需要 Agent Substrate？

传统 Kubernetes 部署通常是一个应用对应一个或多个 Pod。但 AI Agent 的工作模式有些特殊：

  • 用户发起任务后，Agent 执行推理、调用工具或运行代码。

  • 调用大模型、等待用户输入时，Agent 可能长时间处于空闲状态。

  • Agent 往往需要保留运行时内存、文件系统和会话状态。

  • Agent 执行的代码可能不可信，需要严格的安全隔离。

如果每个用户的 Agent 都长期占用一个独立的 Pod，就可能浪费大量资源；如果任务到来时才创建 Pod，又可能引入调度和启动延迟。

1.1. 核心思路：Actor 与 Worker 解耦

这里最重要的是两个概念：

  • Actor：逻辑上的一个 Agent 实例，具有自己的身份、状态和生命周期。

  • Worker：实际承载 Actor 的执行资源，通常由预先启动的 Kubernetes Pod 提供。

多个 Actor 可以共享一组 Worker 的计算资源，但同一时刻实际执行的 Actor 仍然需要相应的执行容量。空闲 Actor 可以被挂起并保存状态，需要继续执行时再恢复。

这与传统的“一份 Agent 对应一个长期运行的 Pod”是不同的资源管理模型。

1.2. 核心组件与 Kubernetes 对应关系

从源码和架构文档来看，Agent Substrate 的主要组件可以这样理解。

组件 / 概念 作用 Kubernetes 视角
ActorTemplate 定义 Actor 的运行镜像、资源及运行参数 类似工作负载模板，但不是 Deployment
Actor 一个具体的、有状态的运行实例 不等于 Pod，生命周期独立于 Worker
WorkerPool 管理可用于执行 Actor 的 Worker 容量 类似执行资源池
Worker 真正承载沙箱执行环境 通常由 Kubernetes Pod 承载
Atespace Actor 的租户与命名空间边界 类似逻辑租户隔离，不能简单等同于 Namespace
ate-api-server 处理 Actor、Worker 生命周期等控制请求 专用控制面
atelet 节点级监督、快照和状态迁移 类似节点 Agent / DaemonSet
atenet 负责网络路由与代理等功能 类似专用数据面与网络控制组件
kubectl-ate 通过命令行管理 Substrate 资源 类似 kubectl 的扩展工具

注意：这些是帮助理解的类比，不代表它们与 Kubernetes 原生资源一一对应。

可以把它理解为：

  • ActorTemplate 决定“这个 Sandbox 运行什么”。

  • Actor 决定“这是哪个用户或任务的独立运行实例”。

  • WorkerPool 决定“实际执行资源从哪里来”。

  • SandboxConfig 决定“使用哪个沙箱运行时版本”。

  • Snapshot 决定“挂起后如何保留和恢复状态”。

2. Substrate的部署架构

从部署视角看，可以分成五层：

层次 主要组件 作用
API 与控制面 ate-api-server Actor 生命周期、调度、快照编排
Kubernetes 管理层 atecontroller、CRD 将 WorkerPool 等资源转换成实际 Kubernetes 工作负载
节点管理层 atelet 节点上的 Worker 管理、镜像准备、快照传输
Sandbox 执行层 Worker Pod、ateworker/ateom、gVisor 或 MicroVM 真正运行 Actor
网络与存储层 atenet、atunnel、PostgreSQL、对象存储 请求转发、身份认证、状态和快照持久化

2.1. 部署的k8s 工作负载

下面是按组件整理的部署清单。具体 Pod 数量、容器组合和名称会随版本、安装选项变化。

工作负载 K8s 类型 部署位置
ate-api-server Deployment ate-system
atecontroller Deployment ate-system
atelet DaemonSet ate-system
atenet Deployment / 相关代理工作负载 ate-system
podcertcontroller Deployment 证书控制器命名空间
ate-idp-server Deployment ate-system
PostgreSQL StatefulSet 或外部数据库 ate-system 或外部
Worker Deployment 管理的 Pod Worker 节点
ateom / ateworker Worker 内部容器 Worker Pod
atunnel Worker 内部网络服务 Worker Pod
Object Store Plugin Sidecar 相关组件 Pod

这里有个容易误解的地方：ateom、atunnel 不一定是独立的 Kubernetes Deployment，它们属于 Worker 内部的运行组件。Object Store Plugin 也可能以 Sidecar 方式运行，而不是单独部署一个集群级服务。

2.2. 外部基础设施依赖

除了 Substrate 自身组件，还需要准备外部基础设施。

依赖 作用 是否必要
Kubernetes 承载所有组件和 Worker Pod 必须
PostgreSQL 保存 Actor、Worker 等控制面状态 必须
对象存储（GCS/S3） 保存 Actor 快照、模板快照 持久化快照场景必须
节点本地存储 缓存运行时资源、快照文件 需要
gVisor 或 MicroVM 环境 提供 Sandbox 隔离运行时 必须至少选择一种
Pod 证书能力 提供内部身份认证和 mTLS 按部署版本和配置要求
凭据提供服务 为 Actor 的出站请求注入受控凭据 按功能配置

这里尤其要区分 PostgreSQL 和对象存储：

  • PostgreSQL 保存的是 Actor 的元数据和状态，不是 Actor 的完整内存。

  • 对象存储保存的是 Actor 的快照文件。

  • atelet 负责节点与对象存储之间的快照传输。

官方架构还包含 Object Store Plugin，用来为快照上传、下载和资源缓存提供统一的对象存储接口。

2.3. 实际部署顺序

从零部署时，我建议按以下依赖顺序理解。

  1. 准备 Kubernetes 集群

    准备节点、网络、存储、证书 API，以及 Worker 所需的运行时能力。

  2. 准备外部基础设施

    部署 PostgreSQL、对象存储、IAM / Workload Identity 等。

  3. 部署 Kubernetes 扩展能力

    安装 Substrate CRD、证书相关组件、podcertcontroller。

  4. 部署控制面

    安装 ate-api-server、atecontroller。

  5. 部署节点管理组件

    安装 atelet DaemonSet。

  6. 部署网络组件

    安装 atenet、Router、相关隧道和代理能力。

  7. 创建 WorkerPool

    选择 gVisor 或 MicroVM，配置 Worker 数量和资源。

  8. 创建 ActorTemplate

    配置 Actor 镜像、资源限制、快照存储位置等。

  9. 创建 Actor 并验证

    创建 Actor，验证启动、访问、Suspend、Resume。

3. 核心组件及功能

2.1 控制面组件【ate-api-server】

这是 Substrate 的核心控制面，主要负责：

  • 提供 gRPC API，供 CLI、上层 Agent 平台调用。

  • 创建、删除和管理 Actor。

  • 管理 ActorTemplate、Atespace、Tag 等资源。

  • 维护 Actor 与 Worker 的映射关系。

  • 选择可用 Worker，完成 Actor 调度。

  • 编排 Actor 的 Suspend、Resume、Checkpoint、Restore。

  • 进行 API 身份认证和权限校验。

它的内部主要包含三个逻辑部分：

内部模块 功能
State Store 保存 Actor、Worker 状态及映射关系
Scheduler 选择可用 Worker
Workflow Engine 编排 Actor 暂停、恢复等多步骤操作

部署形态： Kubernetes Deployment。

它不直接运行 Agent，也不直接操作底层 Sandbox，而是通过节点管理组件协调执行。

2.2 Kubernetes Controller【atecontroller】

这是 Substrate 与 Kubernetes 之间的桥梁。

主要负责：

  • Watch Substrate 定义的 Kubernetes CRD。

  • 监听 WorkerPool 的创建、修改和删除。

  • 根据 WorkerPool 配置创建或更新 Kubernetes Deployment。

  • 维护 Worker Pod 的期望状态。

例如，创建一个 WorkerPool：

apiVersion: ate.dev/v1alpha1
kind: WorkerPool
metadata:
  name: gvisor-pool
spec:
  replicas: 10

Controller 负责将它转换为实际运行的 Worker Pod。

部署形态： Kubernetes Deployment。

注意：ActorTemplate 并不是 Kubernetes CRD，它通过 Substrate API 管理；WorkerPool 才是 Kubernetes 侧管理的资源。

2.3 节点管理组件【atelet】

atelet 是运行在 Kubernetes Node 上的节点级管理进程。

它主要负责：

  1. 监听和管理当前节点上的 Worker。

  2. 准备 Sandbox 需要的镜像和运行时资源。

  3. 组装 OCI Bundle。

  4. 调用 Worker 内部的管理进程执行 Sandbox 启动。

  5. 协调 Actor 的 Checkpoint 和 Restore。

  6. 将快照上传到对象存储，或从对象存储下载快照。

  7. 管理节点本地的 Sandbox Asset Cache。

它是整个数据面的重要执行协调者。

部署形态： Kubernetes DaemonSet。

也就是说，符合调度条件的每个 Node 都会运行一个 atelet。

2.4 Worker 内部管理组件【ateom / ateworker】

这是运行在 Worker Pod 内部的 Sandbox 管理进程。

不同版本和文档中使用过 ateworker、ateom 这些名称。当前架构文档使用 ateom 描述这一层的职责。

它主要负责：

  • 接收 atelet 下发的操作。

  • 创建和管理 Actor 对应的 Sandbox。

  • 调用底层 Sandbox Runtime。

  • 执行 RunWorkload、CheckpointWorkload、RestoreWorkload。

  • 管理 Actor 的网络连接。

  • 通过内部网络服务 atunnel 转发 Actor 流量。

它与 atelet 的关系是：

组件 所在位置 主要职责
atelet Kubernetes Node 管理节点上的 Worker，协调生命周期和快照
ateom Worker Pod 内 具体操作 Sandbox，驱动运行时
atunnel Worker 内部网络服务 接收经过认证的流量并转发给 Actor

部署形态： Worker Pod 内的容器或管理进程，具体由 WorkerPool 选择的 Sandbox 类型决定。

2.5 Sandbox Runtime

Substrate 需要真正提供隔离执行环境的底层 Runtime。

目前主要有两种运行时实现：

2.5.1. gVisor

  • 使用用户态内核提供系统调用隔离。

  • 由 runsc 执行 Sandbox 的创建、Checkpoint 和 Restore。

  • 相比完整虚拟机，运行开销通常更低。

  • 是 Substrate 默认使用的隔离运行时之一。

2.5.2. MicroVM

  • 使用轻量级虚拟机提供隔离。

  • 当前实现使用 Cloud Hypervisor。

  • Worker 需要具备相应虚拟化能力。

  • 适合需要更强虚拟化隔离边界的场景。

MicroVMs

对应的 Worker 管理程序包括：

  • ateworker-gvisor

  • ateworker-microvm

注意：不能直接把普通 runc 容器当作 Substrate 已支持的 Sandbox Runtime。Substrate 的设计依赖运行时支持的 Checkpoint/Restore 能力。

2.6 网络组件【atenet】

atenet 是 Substrate 的网络组件集合，负责 Actor 流量入口、路由和网络隔离。

主要包括：

组件 功能
atenet-controller 管理网络相关配置和代理工作负载
atenet-router Envoy 网关，接收 Actor 请求并进行路由
atunnel Worker 内部隧道服务，将请求转发到 Actor

其中 atenet-router 是一个非常重要的组件。

例如，上层 Agent 平台访问某个 Actor：

POST /execute HTTP/1.1
Host: agent.example.com
ate-target-actor: demo/my-agent

路由过程：

  1. Router 识别请求中的 Actor 标识。

  2. 调用 ate-api-server 查询 Actor 状态。

  3. 如果 Actor 已暂停，则触发 Resume。

  4. Control Plane 分配 Worker。

  5. atelet 和 Worker 内部管理进程恢复 Actor。

  6. Router 与 Worker 的 atunnel 建立认证隧道。

  7. atunnel 将请求转发到 Actor。

这样，上层应用不需要知道 Actor 当前在哪个 Worker 上。

2.7 身份认证组件【podcertcontroller】

这是 Kubernetes Pod 证书签发控制器。

主要负责：

  • 为 Substrate 组件提供短期证书。

  • 为组件提供可验证的身份。

  • 支持内部服务之间的 mTLS 通信。

  • 为 Actor 运行环境提供身份认证基础。

部署形态： Kubernetes Deployment 或相应控制器工作负载。

此外，还有：

ate-idp-server

负责提供 OpenID Connect Discovery 文档和 JWKS 公钥信息，供依赖方验证 Actor JWT。

它与 podcertcontroller 不是同一个东西：

  • podcertcontroller：解决 Pod 及内部组件的证书身份问题。

  • ate-idp-server：提供 JWT 验证所需的身份提供方元数据。