substrate

Agent Substrate

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

Agent Substrate 是什么？

Agent Substrate 为大规模 agent 部署提供了高性能、高密度的运行时环境。agent substrate 控制面为 agent 沙箱提供全生命周期管理，实现亚秒级的 agent 恢复/挂起操作，并允许将大量 agent 复用到同一套计算机基础设施上。它支持多种沙箱技术，包括 microVM 和 gVisor，从而为所有沙箱类型提供一致的生命周期操作。

Agent Substrate 的核心思想是：将较大集合的“actor”（agent 等应用程序）映射到较小集合的就绪“worker”上，利用类 agent 应用大多时间处于空闲这一特点，实现高密度复用。它提供的功能包括：管理 actor 的生命周期（例如创建/销毁、挂起/恢复）、实时将 actor 分配给 worker，以及将入站流量路由到这些 actor。

Agent Substrate 是一个低主观性（low-opinion）的系统。它管理的工作负载不一定是真正的 AI agent，但这些正是它设计所面向的最佳示例应用。它不是用于构建 agent 的 SDK，而是一个用于大规模运行 agent 的系统。

Agent Substrate 利用 Kubernetes 进行基础设施 provisioning 和 worker 生命周期管理（Kubernetes Pods）。它构建在 Pods 和 Pod 自动扩缩容等 Kubernetes 功能之上，同时 Agent Substrate 提供面向 agent 的调度和控制，以实现更低的延迟。以 Kubernetes 作为底层系统，可以在端到端 agent 部署所需的各类工作负载之间保持一致的基础设施管理，并为覆盖 agent、推理和训练循环的 RL 场景实现整体性的基础设施优化。

演示

观看 Agent Substrate 集群如何在仅 8 个物理 pod 上复用约 250 个有状态 actor。

本演示重点展示了 Substrate 的核心开发者体验和“Agentic Infrastructure”能力：

1. 即时 Actor 传送： 对 actor 执行高性能的挂起和恢复，可将其分配到池中的任意可用 worker，且激活时间在亚秒级。
2. 状态持久化： 通过完整状态快照，在休眠周期中精准保留持久工作内存（易失性 RAM）和文件系统状态。
3. Agent 群集复用： 通过将大量有状态 actor“杂耍式”地分配到一小批共享物理 pod 上，展示 30 倍以上的超量订阅。

要在自己的集群中重现此演示，请参阅 Counter Demo 中的详细说明。

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

框架无关与兼容性

Agent Substrate 被设计为与框架和 agent harness 无关。由于它在内核层面（通过 gVisor）管理标准 OCI 容器，因此可以承载基于任意技术栈构建的 agent。

• Agent Development Kit (ADK)： 原生支持 ADK 兼容的 actor 身份标识和持久工作内存。
• LangChain： 适合运行长时间运行、有状态的 LangChain agent，以及沙箱化工具调用的理想执行环境。
• Claude Code 与 CodeX： 支持高密度、有状态的编码环境，在会话之间保留终端和文件系统状态。
• Model Context Protocol (MCP)： 将安全、沙箱化的 MCP server 部署为 Substrate actor，为任意 LLM 提供持久工具。

生态与示例

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

状态与兼容性

Agent Substrate 目前处于早期开发阶段。它还不可用于生产环境，API 几乎肯定会发生变更。现阶段我们不提供任何向后兼容性保证，本项目中的一切内容都可能发生变化。

支持的 Kubernetes 版本

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

社区

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

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

• 视频通话链接：https://meet.google.com/uhq-cxvn-dhy
• 或拨打电话：(US) +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 了解为项目做贡献的指南。我们欢迎各种形式的贡献，但项目还非常年轻。我们目前的重心是构建核心系统和演示，因此短期内可能无法审查或合并不符合这些目标的贡献。

快速开始（开发）

要快速搭建完整环境，请按以下步骤操作：

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

2. 执行以下步骤：

# 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

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

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

GKE 快速开始（开发）

1. 创建并配置你的环境文件：

   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
   

2. 为 gcloud 启用 application-default 凭据：

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

3. 创建所需的 GCP 资源（GKE 集群、Redis、GCS 和 IAM 绑定）：

   go run ./tools/setup-gcp bootstrap
   

4. 将 Agent Substrate 系统部署到你的集群：

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

5. 然后可以部署示例应用。详细步骤请参阅 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

销毁资源（GCP）

如果需要删除安装脚本创建的资源，可以使用提供的脚本 hack/teardown.sh。该脚本会按创建顺序的逆序删除资源，并能优雅处理部分失败。

./hack/teardown.sh --all

或者按需单独执行销毁步骤（查看 ./hack/teardown.sh 了解可用选项）。

销毁本地 kind 资源

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

./hack/delete-kind-cluster.sh

示例

我们提供了几个示例应用，用于演示 Agent Substrate 的能力：

1. Counter Demo：一个有状态的 Go HTTP 服务，演示挂起/恢复期间的状态保留以及基于 CRD 的动态路由。
2. Sandbox Demo (Antigravity)：一个安全的沙箱执行环境（运行 Alpine Linux），允许任意 shell 执行，同时在会话之间保留文件系统状态。
3. Claude Code Multiplex：演示通过将多个 Claude Code agent 复用到有限的 worker 池中，对物理硬件实现超量订阅。
4. Multi-Template：两个运行不同二进制的 ActorTemplate 在三个命名空间中共享一个 WorkerPool。
5. Request Parking：一个超量订阅的 worker 池，路由器会先持有入站请求直到有 worker 空闲，而不是返回 503。
6. Autoscaled WorkerPool：基于已分配 worker 数量，使用由 prometheus-adapter 提供指标的 HPA 对 WorkerPool 进行扩缩容。

文档与指南

• 架构：控制面、节点 supervisor 和网络栈如何协同工作。
• API 配置指南：配置 WorkerPool、ActorTemplate、Secret 和 Volume 的详细参考。
• 完整 CLI 文档：kubectl-ate 的安装与使用。
• 术语表：核心术语（Actor、Atespace、ActorTemplate、WorkerPool、Worker、ate-api-server、atenet、atelet、ateom）及其相互关系。
• 集成仓库：集成代码所在位置、仓库命名方式，以及修复如何回流到核心。
• 可观测性指南：actor 日志、指标和分布式追踪指南。
• 认证指南：配置受信任的 JWT provider 和人工凭据。
• Request Parking：路由器如何在 worker 池瞬时饱和期间停放请求。
• 威胁模型：信任边界、假设和已知风险。
• 路线图：当前限制和后续计划。
• 基准测试指南：基于 Locust 的负载测试、监控栈和编排式基准测试工具。

导览

命令

• cmd/ateapi：核心控制面 API server，提供 gRPC 端点以管理 actor 和 worker 生命周期。
• cmd/atelet：节点级 DaemonSet，负责监督物理 worker pod、协调快照以及管理状态传输。
• cmd/atecontroller：Kubernetes controller，负责协调 WorkerPool 和 ActorTemplate 自定义资源。
• cmd/atenet：组合式网络 controller，提供 DNS、Envoy 路由和 proxy sidecar。
• cmd/ateom-gvisor：pod 内部辅助进程，运行在沙箱化 worker pod 中，用于执行 runsc checkpoint 和 restore 命令。
• cmd/ateom-microvm：ateom-gvisor 的 micro-VM 对应实现，将 actor 作为 cloud-hypervisor VM 运行。
• cmd/podcertcontroller：一个“polyfill”，提供最终将在上游 Kubernetes 中发布（但名称不同）的 Pod Certificate signer。
• cmd/kubectl-ate：用于管理 Agent Substrate 资源的 CLI 工具。参见其 README。
• cmd/benchmarking：用于负载测试的合成工作负载，包括按需消耗 RAM、磁盘和文件描述符的 glutton。
• tools/setup-gcp：用于创建所需 GCP 基础设施资源（GKE、GCS、IAM）的 provisioning 工具。
• demos/：演示 Agent Substrate 能力的示例应用。