Google 开源 Agent Substrate：大规模 Agent 运行时

注意：这不是 Google 官方支持的产品。本项目不符合 Google 开源软件漏洞奖励计划的资格。

什么是 Agent Substrate？

Agent Substrate 为大规模 Agent 部署提供了一个高性能、高密度的运行时环境。Agent Substrate 控制平面提供完整的生命周期管理，包括 Agent 沙箱的创建、暂停、恢复等操作，支持在亚秒级时间内完成 Agent 的挂起与恢复，并允许将大量 Agent 复用到同一套计算基础设施上。它支持多种沙箱技术，包括 microVM 和 gVisor，为所有沙箱类型提供一致的生命周期操作。

Agent Substrate 的核心思想是将一组较大的“角色”（Actor，即应用程序，如 Agent）映射到一组较少的就绪“工作器”（Worker）上。之所以能实现高密度复用，是因为类似 Agent 的应用程序大部分时间处于空闲状态。Agent Substrate 提供了管理角色生命周期（例如创建/销毁、挂起/恢复）、实时将角色分配给工作器，以及将传入流量路由到对应角色的功能。

Agent Substrate 被设计为一个低介入（low-opinion）系统。它管理的 workloads 不必非得是真正的 AI Agent，但 Agent 正是其设计目标的最佳体现。Agent Substrate 不是用于构建 Agent 的 SDK，而是用于大规模运行 Agent 的系统。

Agent Substrate 借助 Kubernetes 进行基础设施配置和工作器生命周期管理（Kubernetes Pods）。它构建在 Kubernetes 的 Pod 和 Pod 自动扩缩容等功能之上，同时 Agent Substrate 提供了 Agent 特有的调度和控制能力，以实现更低的延迟。使用 Kubernetes 作为底层系统，使得在整个端到端 Agent 部署所需的所有 workload 类型中实现一致的基础设施管理成为可能，并允许对跨越 Agent、推理和训练周期的 RL 场景进行整体基础设施优化。

观看 Agent Substrate 集群在仅 8 个物理 Pod 上复用约 250 个有状态角色的演示。

本演示重点介绍 Substrate 的核心开发者体验和"Agentic Infrastructure"能力：

即时角色迁移（Instant Actor Teleport）：将角色高性能地挂起和恢复到着色器池中任何可用的工作器上，激活时间在亚秒级。

状态持久化（State Persistence）：通过完整状态快照，在休眠周期之间完美保留持久化的工作内存（易失性 RAM）和文件系统状态。

Agent 集群复用（Agent Swarm Multiplexing）：通过将大量有状态角色"杂耍"到一小批共享物理 Pod 上，展示 30 倍以上的过量订阅（oversubscription）。

如需在自己的集群中复现此演示，请参阅 Counter Demo 中的详细演练。

更多视频和演练，请访问我们的 YouTube 频道：agent-substrate。

框架无关与兼容性

Agent Substrate 被设计为框架和 Agent harness 无关的系统。由于它通过 gVisor 在内核级别管理标准 OCI 容器，因此可以托管在任何技术栈上构建的 Agent。

Agent Development Kit（ADK）：原生支持 ADK 兼容的角色标识和持久化工作内存。

LangChain：适合长时间运行、有状态的 LangChain Agent 以及沙箱化工具调用的理想执行环境。

Claude Code 和 CodeX：支持高密度、有状态的编码环境，在不同会话之间保留终端和文件系统状态。

Model Context Protocol（MCP）：将安全的沙箱化 MCP 服务器部署为 Substrate Actor，为任何 LLM 提供持久化工具。

Agent Executor：一个分布式 Agent 运行时，演示如何在 Agent Substrate 上构建安全、超大规模可扩展的 Agent harness（参见公告博客和集成指南）。

状态与兼容性

Agent Substrate 目前处于早期开发阶段，尚未准备好用于生产，API 几乎肯定会发生变化。我们目前不提供任何向后兼容性的保证，本项目中的任何内容都可能发生变化。

支持的 Kubernetes 版本

目前我们的目标是支持最新的稳定版 Kubernetes 以及前一个次要版本。

如需 announcements、技术讨论和社区支持，请加入 ate-dev Google Group。

我们每周四上午 10:00 至 11:00（太平洋时间）举办社区会议。

视频通话链接：https://meet.google.com/uhq-cxvn-dhy

或拨打电话：（美国）+1 253-289-6971 PIN：787 664 574 59#

更多电话号码：https://tel.meet/uhq-cxvn-dhy?pin=9044088223662

我们也在 CNCF Slack 上有频道；如果您还没有访问权限，请在此处申请。

使用 #substrate-users 讨论使用 Substrate。 使用 #substrate-dev 讨论开发 Substrate。

请参阅 CONTRIBUTING.md 了解为项目做贡献的指南。我们欢迎各种形式的贡献，但项目还非常年轻。我们目前的重点是构建核心系统和演示，所以近期可能无法审查或合并与这些目标不一致的贡献。

快速入门（开发环境）

快速设置完整环境：

确保您的开发机器上已安装并配置好 Go、kubectl 和 docker。我们将通过 Go 自动管理其他依赖项，包括 kind。

运行以下步骤：

# create cluster and local registry (IPv4; IP_FAMILY=dual|ipv6 overrides)
hack/create-kind-cluster.sh

# install ate, valkey, rustfs
hack/install-ate-kind.sh --deploy-ate-system

# install counter demo
hack/install-ate-kind.sh --deploy-demo-counter

# install kubectl-ate
go install ./cmd/kubectl-ate

# create an atespace (required before creating actors), then a counter actor in it
kubectl ate create atespace demo
kubectl ate create actor my-counter-1 -a demo --template=ate-demo-counter/counter

# port-forward the network router to bind to local port `8000`
kubectl port-forward -n ate-system svc/atenet-router 8000:80

在另一个终端中，发送 HTTP 请求来递增计数器：

curl -X POST -H "Host: my-counter-1.demo.actors.resources.substrate.ate.dev" -i http://localhost:8000/

GKE 快速入门（开发环境）

创建并配置您的环境文件：

cp hack/ate-dev-env.sh.example .ate-dev-env.sh

# Edit .ate-dev-env.sh to match your project and preferences, then source it:
source .ate-dev-env.sh

为 gcloud 启用应用程序默认凭据：

gcloud auth application-default login --project=${PROJECT_ID}

配置所需的 GCP 资源（GKE 集群、Redis、GCS 和 IAM 绑定）：

go run ./tools/setup-gcp bootstrap

将 Agent Substrate 系统部署到您的集群：

./hack/install-ate.sh --deploy-ate-system

然后您可以部署示例应用程序。详细的演练请参阅 demos/counter/README.md 或 demos/sandbox/README.md。

./hack/install-ate.sh --deploy-demo-counter

您可以根据需要运行单独的设置步骤来创建 GCP 资源。参见 go run ./tools/setup-gcp --help 了解可用选项。例如：

go run ./tools/setup-gcp create cluster
go run ./tools/setup-gcp create bucket

同样，您可以使用安装脚本部署或清理特定的 Agent Substrate 组件。参见 ./hack/install-ate.sh --help 了解所有选项。

# Re-deploy only ate-apiserver of the ATE system
./hack/install-ate.sh --deploy-ate-apiserver

# Delete everything (core system and all demos)
./hack/install-ate.sh --delete-all

如果您需要删除 setup 脚本创建的资源，可以使用提供的脚本 hack/teardown.sh。此脚本按创建的反向顺序删除资源，并能优雅地处理部分失败。

./hack/teardown.sh --all

或根据需要运行单独的拆除步骤（请参阅 ./hack/teardown.sh 了解可用选项）。

如果您需要删除本地 kind 集群及其注册表（如果是由 hack/create-kind-cluster.sh 创建的）：

./hack/delete-kind-cluster.sh

示例应用程序

我们提供了多个展示 Agent Substrate 能力的示例应用程序：

Counter Demo：一个有状态的 Go HTTP 服务器，演示在挂起/恢复之间的状态保留以及动态 CRD 路由。

Sandbox Demo（Antigravity）：一个安全的沙箱化执行环境（运行 Alpine Linux），允许任意 shell 执行，并在不同会话之间保留文件系统状态。

Claude Code Multiplex：演示通过将多个 Claude Code Agent 复用到有限的工作器池上来过量订阅物理硬件。

Multi-Template：两个运行不同二进制文件的 ActorTemplate 共享一个 WorkerPool，跨越三个命名空间。

Request Parking：一个过量订阅的池，路由器在其中保持入站请求直到工作器释放，而不是返回 503。

Autoscaled WorkerPool：根据分配的工作器数量扩展 WorkerPool，使用由 prometheus-adapter 供料的 HPA。

文档与指南

架构：控制平面、节点监管器和网络堆栈如何协同工作。

API 配置指南：配置 WorkerPools、ActorTemplates、Secrets 和 Volumes 的详细参考。

完整 CLI 文档：kubectl-ate 的安装和使用。

术语表：核心术语（Actor、Atespace、ActorTemplate、WorkerPool、Worker、ate-api-server、atenet、atelet、ateom）及其相互关系。

集成仓库：集成所在位置、仓库命名方式以及修复如何流回核心。

可观测性指南：角色日志、指标和分布式追踪指南。

认证指南：配置可信 JWT 提供商和人工凭据。

Request Parking：路由器如何通过短暂的工作器池饱和来停放请求。

威胁模型：信任边界、假设和已知风险。

路线图：当前限制和下一步计划。

基准测试指南：基于 Locust 的负载测试、监控堆栈和编排基准测试工具。

核心组件

cmd/ateapi：核心控制平面 API 服务器，暴露 gRPC 端点以管理角色和工作器生命周期。

cmd/atelet：节点级 DaemonSet，监管物理工作器 Pod、协调快照和管理状态传输。

cmd/atecontroller：Kubernetes 控制器，协调 WorkerPool 和 ActorTemplate 自定义资源。

cmd/atenet：组合网络控制器，提供 DNS、Envoy 路由和代理 sidecar。

cmd/ateom-gvisor：运行在沙箱化工作器 Pod 内部的内部 Pod 辅助程序，执行 runsc checkpoint 和 restore 命令。

cmd/ateom-microvm：ateom-gvisor 的 microVM 对应物，将角色作为 cloud-hypervisor VM 运行。

cmd/podcertcontroller：一个"polyfill"，提供最终将在上游 Kubernetes 中提供的 Pod Certificate 签名者（名称不同）。

cmd/kubectl-ate：用于管理 Agent Substrate 资源的 CLI 工具。参见其 README。

cmd/benchmarking：负载测试使用的合成工作负载，包括 glutton，可按需消耗 RAM、磁盘和文件描述符。

tools/setup-gcp：配置工具，用于设置必要的 GCP 基础设施资源（GKE、GCS、IAM）。

demos/：展示 Agent Substrate 能力的示例应用程序。