# Agent Substrate

> A performant, high-density open-source runtime environment for large-scale AI agent deployments on Kubernetes, enabling sub-second suspend/resume and heavy multiplexing of agents onto shared infrastructure.

Agent Substrate is an open-source project (Apache 2.0) that delivers a high-density runtime environment for deploying AI agents at scale on Kubernetes. The README notes it is not an officially supported Google product and is currently in early development, not yet ready for production use. It is written in Go and hosted under the `agent-substrate` GitHub organization, with a weekly community meeting and CNCF Slack channels for discussion.

## What It Is

Agent Substrate is a Kubernetes-native control plane for managing large numbers of stateful agent "actors" on a smaller pool of shared physical "workers." It solves the core infrastructure problem of running many concurrent AI agents efficiently by exploiting the fact that agent-like workloads are idle most of the time. The system provides full lifecycle management — create, destroy, suspend, and resume — for agent sandboxes, with sub-second activation latency. It is explicitly not an SDK for building agents; it is a system for running them at scale.

## How the Multiplexing Architecture Works

At its core, Agent Substrate maps a large set of actors (agent processes) onto a smaller set of ready workers using a control plane that handles scheduling, state transfer, and traffic routing:

- **Actors** are the logical agent instances; **Workers** are the physical Kubernetes Pods that execute them.
- When an actor is not actively processing a request, it can be suspended and its full state (RAM and filesystem) snapshotted, freeing the worker for another actor.
- Incoming traffic is routed to the correct actor via an Envoy-based networking layer (`atenet`), which can also "park" requests while a worker frees up rather than returning a 503.
- The demo in the README shows approximately 250 stateful actors multiplexed across just 8 physical pods, demonstrating 30x+ oversubscription.

## Sandbox Technologies and Framework Compatibility

Agent Substrate manages standard OCI containers at the kernel level and supports multiple sandbox backends:

- **gVisor** — provides strong isolation for sandboxed workloads via `runsc` checkpoint/restore.
- **microVMs** — runs actors as cloud-hypervisor VMs for an alternative isolation model.

Because it operates at the container/VM level, it is framework-agnostic. The README lists native or compatible support for Google's Agent Development Kit (ADK), LangChain, Claude Code, CodeX, and Model Context Protocol (MCP) servers deployed as Substrate Actors.

## Kubernetes Integration and Infrastructure Model

Agent Substrate builds on top of Kubernetes rather than replacing it:

- Uses Kubernetes Pods and Pod autoscaling (HPA) for worker lifecycle management.
- Introduces custom resources: `WorkerPool`, `ActorTemplate`, and `Atespace`.
- Adds agent-specific scheduling and lower-latency control on top of standard Kubernetes primitives.
- Supports GKE (Google Kubernetes Engine) as a primary cloud target, with provisioning tooling (`tools/setup-gcp`) for GKE clusters, GCS buckets, and IAM bindings.
- Integrates with Prometheus for metrics and supports distributed tracing via an observability guide.

## Ecosystem and Related Projects

The README references the **Agent Executor** (`github.com/google/ax`) as a distributed agent runtime built on top of Agent Substrate, with an associated Google Cloud blog announcement. MCP servers can be deployed as Substrate Actors to provide durable, sandboxed tools for any LLM. The project participates in the CNCF ecosystem via Slack channels (`#substrate-users` and `#substrate-dev`).

## Current Status: Early Development

The README explicitly states that Agent Substrate is in early development, APIs are subject to breaking changes, and backward compatibility is not guaranteed. The latest GitHub release is tagged `v0.0.0 - initial commit` (published May 2026), and the repository was created in May 2026 with active pushes as recently as August 2026. The project welcomes contributions but notes it may not be able to review contributions that don't align with its near-term focus on core system and demo development.

## Features
- Sub-second actor suspend and resume operations
- Full-state snapshots preserving RAM and filesystem across hibernation
- Heavy multiplexing of agents onto shared Kubernetes pods (30x+ oversubscription demonstrated)
- Support for gVisor and microVM sandbox technologies
- Kubernetes-native control plane with custom resources (WorkerPool, ActorTemplate, Atespace)
- Envoy-based traffic routing with DNS and proxy sidecars
- Request parking during worker pool saturation
- HPA-based WorkerPool autoscaling via Prometheus adapter
- Framework-agnostic OCI container management
- Native support for ADK, LangChain, Claude Code, CodeX, and MCP servers
- kubectl-ate CLI for managing Substrate resources
- Observability via actor logging, metrics, and distributed tracing
- JWT-based authentication with trusted provider configuration
- GCP provisioning tooling for GKE, GCS, and IAM

## Integrations
Kubernetes, gVisor, cloud-hypervisor (microVMs), Envoy, Prometheus, Google Kubernetes Engine (GKE), Google Cloud Storage (GCS), Agent Development Kit (ADK), LangChain, Claude Code, CodeX, Model Context Protocol (MCP), Agent Executor (google/ax), PostgreSQL, kind (local Kubernetes)

## Platforms
CLI, API, LINUX

## Pricing
Open Source

## Version
v0.0.0

## Links
- Website: https://github.com/agent-substrate/substrate
- Documentation: https://github.com/agent-substrate/substrate/blob/main/docs/architecture.md
- Repository: https://github.com/agent-substrate/substrate
- EveryDev.ai: https://www.everydev.ai/tools/agent-substrate