GitHub 仓库：https://t.co/s3LFYZX4mP

agent-substrate/substrate

来源：https://github.com/agent-substrate/substrate

Agent Substrate

许可证（https://opensource.org/licenses/Apache-2.0）

注意：这不是谷歌官方支持的产品。本项目不符合 谷歌开源软件漏洞奖励计划（https://bughunters.google.com/open-source-security）的资格。

什么是 Agent Substrate？

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

Agent Substrate 的核心思想是将一大组“执行体“（actor，即智能体等应用）映射到一小组合就绪的“工作节点“（worker）上，其依据是智能体类应用大多数时间处于空闲状态，从而实现高密度复用。它提供管理执行体生命周期（例如创建/销毁、挂起/恢复）、实时将执行体分配给工作节点，以及将传入流量路由到相应执行体的功能。

Agent Substrate 旨在成为一个低主观意见（low-opinion）的系统。它管理的工作负载不一定是真正的 AI 智能体，但智能体正是它设计所针对的最佳应用类型。它不是用于构建智能体的 SDK，而是一个用于大规模运行智能体的系统。

Agent Substrate 利用 Kubernetes 进行基础设施资源供给和工作节点生命周期管理（Kubernetes Pod）。它构建在 Kubernetes 的 Pod 和 Pod 自动扩缩容等功能之上，同时 Agent Substrate 提供面向智能体（agent）的专用调度和控制，以实现更低的延迟。以 Kubernetes 作为底层系统，可以为端到端智能体部署所需的所有工作负载类型提供一致的基础设施管理，并支持对涵盖智能体、推理和训练周期的强化学习（RL）场景进行整体基础设施优化。

演示

Agent Substrate 演示（https://www.youtube.com/watch?v=ZEzkCFJkzjY）

观看 Agent Substrate 集群如何将约 250 个有状态执行体复用到仅 8 个物理 Pod 上。

此演示重点展示了 Substrate 的核心开发者体验和“智能体基础设施“能力：

1. 执行体即时迁移（Instant Actor Teleport）： 高性能的挂起和恢复操作，可将执行体恢复到池中任意可用工作节点上，激活时间亚秒级。
2. 状态持久化： 通过全量状态快照，在休眠周期之间完美保留持久工作内存（易失性 RAM）和文件系统状态。
3. 智能体集群复用： 通过将大量有状态执行体“调度“到一小部分共享物理 Pod 上，演示了 30 倍以上的超额订阅。

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

更多视频和演练，请访问我们的 YouTube 频道：agent-substrate（https://www.youtube.com/channel/UCN9PPqlTtVxlcpbQ-NWpfZQ）。

框架无关与兼容性

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

• Agent Development Kit（ADK）： 原生支持与 ADK 兼容的执行体身份标识和持久工作内存。
• LangChain： 非常适合作为长时间运行、有状态的 LangChain 智能体以及沙箱化工具调用的执行环境。
• Claude Code 和 CodeX： 支持高密度、有状态的编码环境，跨会话保留终端和文件系统状态。
• Model Context Protocol（MCP）： 将安全、沙箱化的 MCP 服务器作为 Substrate 执行体部署，为任何 LLM 提供持久化的工具。

生态系统与示例

• Agent Executor（https://github.com/google/ax）： 一个分布式智能体运行时，演示了如何在 Agent Substrate 上构建安全、超大规模可扩展的智能体框架（参见公告博客（https://cloud.google.com/blog/products/ai-machine-learning/agent-executor-googles-distributed-agent-runtime）和集成指南（https://github.com/google/ax/blob/main/manifests/README.md））。

状态与兼容性

Agent Substrate 目前处于早期开发阶段。它尚不适合 生产环境使用，并且 API 几乎肯定会发生变化。在此阶段，我们不 对向后兼容性做任何保证，本项目中的一切内容都可能被更改。

支持的 Kubernetes 版本

目前，我们的目标是支持 Kubernetes 的最新稳定版本（https://kubernetes.io/releases/）及上一个次要版本。

社区

如需公告、技术讨论和社区支持，请加入 ate-dev（https://groups.google.com/g/ate-dev） Google 群组。

我们每周四上午 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 中也有频道；如果您没有访问权限，请在此处请求邀请（https://slack.cncf.io/）。

• #substrate-users（https://cloud-native.slack.com/archives/C0B6RCAJULW）用于讨论如何使用 substrate。
• #substrate-dev（https://cloud-native.slack.com/archives/C0B6M3E2J3D）用于讨论开发 substrate。

开发

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

快速入门（开发环境）

要快速搭建完整环境：

1. 确保您的开发机器上已安装并配置好 Go（https://go.dev/doc/install）、kubectl（https://kubernetes.io/docs/tasks/tools/）和 docker（https://www.docker.com/）。我们将通过 Go 自动管理其他依赖项，包括 kind（https://kind.sigs.k8s.io/）。

2. 运行以下步骤： ``shell

创建集群和本地镜像仓库

hack/create-kind-cluster.sh

安装 ate、valkey、rustfs

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

安装 counter 演示

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

安装 kubectl-ate

go install ./cmd/kubectl-ate

创建一个 atespace（创建执行体之前必需），然后在其内创建一个 counter 执行体

kubectl ate create atespace demo kubectl ate create actor my-counter-1 -a demo –template=ate-demo-counter/counter

将网络路由器端口转发到本地端口 8000

kubectl port-forward -n ate-system svc/atenet-router 8000:80 ``

3. 在另一个终端中，发送 HTTP 请求来递增计数器： shell curl -X POST -H "Host: my-counter-1.demo.actors.resources.substrate.ate.dev" -i http://localhost:8000/

GKE 快速入门（开发环境）

1. 创建并配置您的环境文件： ``bash cp hack/ate-dev-env.sh.example .ate-dev-env.sh

   编辑 .ate-dev-env.sh 以匹配您的项目和偏好，然后引入它：

   source .ate-dev-env.sh ``

2. 为 gcloud 启用应用默认凭据： bash gcloud auth application-default login --project=${PROJECT_ID}

3. 配置所需的 GCP 资源（GKE 集群、Redis、GCS 和 IAM 绑定）： bash go run ./tools/setup-gcp bootstrap

4. 将 Agent Substrate 系统部署到您的集群： bash ./hack/install-ate.sh --deploy-ate-system

5. 然后您可以部署示例应用程序。有关详细演练，请参阅 demos/counter/README.md 或 demos/sandbox/README.md。 bash ./hack/install-ate.sh --deploy-demo-counter

自定义设置与部署

您可以按需运行单独的设置步骤来创建 GCP 资源。可用选项请参阅 go run ./tools/setup-gcp --help。例如： bash go run ./tools/setup-gcp create cluster go run ./tools/setup-gcp create bucket

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

仅重新部署 ATE 系统的 ate-apiserver

./hack/install-ate.sh –deploy-ate-apiserver

删除所有内容（核心系统和所有演示）

./hack/install-ate.sh –delete-all ``

清理资源（GCP）

如果您需要删除设置脚本创建的资源，可以使用提供的脚本 hack/teardown.sh。该脚本将按照与创建时相反的顺序删除资源，并能优雅地处理部分失败情况。

bash ./hack/teardown.sh --all

或者根据需要运行单独的清理步骤（可用选项请参阅 ./hack/teardown.sh）。

清理本地 kind 资源

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

bash ./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 智能体复用到有限的工作节点池上，演示物理硬件的超额订阅。
4. Multi-Template：两个运行不同二进制文件的 ActorTemplate 在三个命名空间中共享一个 WorkerPool。
5. Request Parking：一个超额订阅的池，路由器在其中保持入站请求，直到有工作节点释放出来，而不是返回 503。
6. Autoscaled WorkerPool：使用由 prometheus-adapter 驱动的 HPA，根据已分配的工作节点数量对 WorkerPool 进行扩缩容。

文档与指南

• 架构：控制平面、节点监督程序（supervisor）和网络栈如何协同工作。
• API 配置指南：配置 WorkerPool、ActorTemplate、Secret 和 Volume 的详细参考。
• 完整 CLI 文档：kubectl-ate 的安装和使用方法。
• 术语表：核心术语（Actor、Atespace、ActorTemplate、WorkerPool、Worker、ate-api-server、atenet、atelet、ateom）及其相互关系。
• 可观测性指南：执行体日志、指标和分布式追踪指南。
• Request Parking：路由器如何在瞬时工作节点池饱和期间停放（park）请求。
• 威胁模型：信任边界、假设和已知风险。
• 路线图：当前的限制和下一步计划。
• 基准测试指南：基于 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 的 micro-VM 对应版本，将执行体作为 cloud-hypervisor VM 运行。
• cmd/podcertcontroller：一个“填充“（polyfill）组件，提供最终将在上游 Kubernetes 中以不同名称发布的 Pod 证书签发器。
• cmd/kubectl-ate：用于管理 Agent Substrate 资源的 CLI 工具。请参阅其 README。
• cmd/benchmarking：负载测试使用的合成工作负载，包括按需消耗 RAM、磁盘和文件描述符的 glutton。
• tools/setup-gcp：用于配置所需 GCP 基础设施资源（GKE、GCS、IAM）的资源供给工具。
• demos/：演示 Agent Substrate 能力的示例应用程序。