agent-substrate/substrate
GitHub: agent-substrate/substrate
Agent Substrate 是一个基于 Kubernetes 的 agent 工作负载调度系统，通过将有状态 actor 高度多路复用到少量 worker 上，实现大规模 agent 会话的低延迟管理与高资源利用率。
Stars: 839 | Forks: 144
# Agent Substrate
[](https://opensource.org/licenses/Apache-2.0)
注意：这不是官方支持的 Google 产品。本项目不符合
[Google 开源软件漏洞奖励计划](https://bughunters.google.com/open-source-security) 的参与资格。
## 什么是 Agent Substrate？
Agent Substrate 是一个构建于 Kubernetes 之上的系统，它管理类 agent 工作负载，以实现比单纯使用 Kubernetes 更高的规模和效率，以及更低的延迟。它基于 Kubernetes 的 Pods 和 Pod 自动扩缩容等功能构建，但将 Kubernetes 控制平面移出关键路径，从而实现更低的延迟。
它可以运行在任何 Kubernetes 集群上，并且绝不会以任何方式阻碍 Kubernetes 的“常规”使用。Kubernetes 为所有类型的工作负载提供基础设施的置备和管理，而 Agent Substrate 提供特定于 agent 的调度和控制。
其核心在于，Agent Substrate 将更大规模的“actors”（如 agent 等应用程序）映射到较少数量的就绪“workers”（Kubernetes Pods）上，利用类 agent 应用程序在大部分时间内往往处于空闲状态这一特性，来实现重度多路复用。它提供了管理 actor 生命周期（例如创建/销毁、挂起/恢复）、实时将 actors 分配给 workers 以及将传入流量路由给它们的功能。
## 演示
[](https://www.youtube.com/watch?v=ZEzkCFJkzjY)
*观看 Agent Substrate 集群如何仅通过 8 个物理 pod 实现约 250 个有状态 actor 会话的多路复用。*
此演示突出了 Substrate 的核心开发者体验和“Agentic Infrastructure”能力：
1. **即时会话传送：** 在池中的任何可用 worker 上高性能地挂起和恢复 actor，实现亚秒级激活。
2. **状态持久化：** 通过全状态快照，在休眠周期中完美保留持久的工作内存（易失性 RAM）和文件系统状态。
3. **Agent 群集多路复用：** 通过将大量有状态 actor “杂耍”般地映射到一小部分共享的物理 pod 池上，演示了 30 倍以上的超额认购。
要在您自己的集群中重现此演示，请参阅 **[Counter Demo](demos/counter/README.md)** 和 **[Secret Agent Demo](demos/agent-secret/README.md)** 中的详细演练。
如需更多视频和演练，请访问我们的 YouTube 频道：**[agent-substrate](https://www.youtube.com/channel/UCN9PPqlTtVxlcpbQ-NWpfZQ)**。
## 框架无关性与兼容性
Agent Substrate 旨在实现**与框架和 agent 框架无关**。由于它在内核级别（通过 gVisor）管理标准 OCI 容器，因此可以托管基于任何技术栈构建的 agent。
## 生态系统与示例
* **[Agent Executor](https://github.com/google/ax):** 一个分布式 agent 运行时，演示了如何在 Agent Substrate 上构建安全、超高可扩展性的 agent 框架（参阅[发布博客](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 版本
## 开发说明
## 快速开始（开发）
要快速设置完整环境：
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. 运行以下步骤：
```
# 创建 cluster 和本地 registry
hack/create-kind-cluster.sh
# 安装 ate, valkey, rustfs
hack/install-ate-kind.sh --deploy-ate-system
# 安装 counter demo
hack/install-ate-kind.sh --deploy-demo-counter
# 安装 kubectl-ate
go install ./cmd/kubectl-ate
# 创建 atespace（创建 actors 前必需），然后在其中创建一个 counter actor
kubectl ate create atespace demo
kubectl ate create actor my-counter-1 -a demo --template ate-demo-counter/counter
# port-forward network router 以绑定到本地端口 `8000`
kubectl port-forward -n ate-system svc/atenet-router 8000:80
```
3. 在**另一个终端**中，发送 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
# 编辑 .ate-dev-env.sh 以匹配您的项目和偏好，然后加载它：
source .ate-dev-env.sh
2. 启用 gcloud 的应用默认凭证：
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/counter/README.md) 或 [demos/sandbox/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`。
```
# 仅重新部署 ATE 系统的 ate-apiserver
./hack/install-ate.sh --deploy-ate-apiserver
# 删除所有内容（核心系统和所有 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](demos/counter/README.md)**：一个有状态的 Go HTTP 服务器，演示了跨挂起/恢复的状态保留，以及动态 CRD 路由。
2. **[Sandbox Demo (Antigravity)](demos/sandbox/README.md)**：一个安全的沙盒执行环境（运行 Alpine Linux），允许任意 shell 执行，同时在会话之间保留文件系统状态。
3. **[Claude Code Multiplex](demos/claude-code-multiplex/README.md)**：通过将多个 Claude Code agent 多路复用到有限的 worker 池上，演示了物理硬件的超额认购。
4. **[Secret Agent](demos/agent-secret/README.md)**：突出了 Substrate 对易失性进程内存的“零空闲”自挂起和重新唤醒功能。
### 文档与指南
* [API 配置指南](docs/api-guide.md)：配置 WorkerPool、ActorTemplate、Secrets 和 Volumes 的详细参考。
* [完整 CLI 文档](cmd/kubectl-ate/README.md)：`kubectl-ate` 的安装和使用说明。
* [术语表](docs/glossary.md)：核心术语（Actor、ActorTemplate、WorkerPool、Worker、ate-api-server、atenet、atelet、ateom）及其相互关系。
* [可观测性指南](docs/observability.md)：actor 日志记录、指标和分布式追踪指南。
* [基准测试指南](benchmarking/README.md)：基于 Locust 的负载测试、监控堆栈和编排式基准测试工具。
## 导览
### 命令
* `cmd/ateapi`：核心控制平面 API 服务器，暴露 gRPC 端点以管理 actor 和 worker 的生命周期。
* `cmd/atelet`：节点级别的 DaemonSet，负责监督物理 worker pod、协调快照并管理状态传输。
* `cmd/atecontroller`：一个 Kubernetes 控制器，负责协调 WorkerPool 和 ActorTemplate 自定义资源。
* `cmd/atenet`：一个组合式网络控制器，提供 DNS、Envoy 路由和代理 sidecar。
* `cmd/ateom-gvisor`：在沙盒化的 worker pod 内部运行的内部 pod 辅助程序，用于执行 `runsc` 检查点和恢复命令。
* `cmd/podcertcontroller`：一个提供 Pod 证书签名者的“polyfill”，这些签名者
最终将随上游 Kubernetes 一起发布（使用不同的名称）。
* `cmd/kubectl-ate`：用于管理 Agent Substrate 资源的 CLI 工具。参见其 [README](cmd/kubectl-ate/README.md)。
* `tools/setup-gcp`：一个置备实用程序，用于设置必要的 GCP 基础设施资源（GKE、GCS、IAM）。
* `demos/`：演示 Agent Substrate 功能的示例应用程序。
标签：EVTX分析, Python工具, 子域名突变, 日志审计, 生命周期管理, 请求拦截, 调度系统