docs: fixed language describing project goals and relationship to Kubernetes

README.md

@@ -7,28 +7,14 @@ eligible for the [Google Open Source Software Vulnerability Rewards Program](htt
 
 ## What is Agent Substrate?
 
-Agent Substrate is a system built on top of Kubernetes which manages agent-like
-workloads to achieve higher scale and efficiency than Kubernetes alone can
-offer, with lower latency.  It builds on top of Kubernetes features like
-Pods and Pod autoscaling, but takes the Kubernetes control-plane out of the
-critical path to achieve lower latency.
-
-It can run on any Kubernetes cluster and does not inhibit “regular” use of
-Kubernetes in any way. Kubernetes provides the infrastructure provisioning and
-management for all types of workloads, while Agent Substrate provides
-agent-specific scheduling and control.
-
-At its core, Agent Substrate maps a larger set of “actors” (applications such
-as agents) onto a smaller set of ready “workers” (Kubernetes Pods), relying on
-the fact that agent-like applications tend to be idle most of the time to
-achieve heavy multiplexing.  It provides functionality to manage an actor’s
-lifecycle (e.g. create/destroy, suspend/resume), to assign actors to workers in real
-time, and to route incoming traffic to them.
-
-Agent Substrate is intended to be a low-opinion system.  The workloads it
-manages don't have to be literal AI agents, but those are the best example of
-the kind of applications it is designed for.  It is not an SDK for building
-agents, but rather a system for running them at scale.
+Agent Substrate delivers a performant, high density runtime environment for large scale agent deployments. The agent substrate control plane provides full lifecycle management for agent sandboxes, delivering sub-second agent resume/suspend operations, and allows heavy multiplexing of agents onto the same computer infrastructure. It supports multiple sandbox technologies including microVMs and gVisor, enabling consistent lifecycle operations for all sandbox types.
+
+At its core, Agent Substrate maps a larger set of “actors” (applications such as agents) onto a smaller set of ready “workers”, relying on the fact that agent-like applications tend to be idle most of the time to achieve heavy multiplexing.  It provides functionality to manage an actor’s lifecycle (e.g. create/destroy, suspend/resume), to assign actors to workers in real time, and to route incoming traffic to them.
+
+Agent Substrate is intended to be a low-opinion system.  The workloads it manages don't have to be literal AI agents, but those are the best example of the kind of applications it is designed for.  It is not an SDK for building agents, but rather a system for running them at scale.
+
+Agent Substrate leverages Kubernetes for the infrastructure provisioning and worker lifecycle management (Kubernetes Pods). It builds on top of Kubernetes features like Pods and Pod autoscaling, while Agent Substrate provides agent-specific scheduling and control to achieve lower latency. Using Kubernetes as the underlying system enables consistent infrastructure management across all workloads types that are required for end to end agentic deployments and allows holistic infrastructure optimizations for RL scenarios that span agentic, inference and training cycles.
+
 
 ## Demo
 
@@ -61,7 +47,7 @@ Agent Substrate is designed to be **framework and agent harness agnostic**. Beca
 
 ## Status and compatibility
 
-Agent Substrate is currently in VERY early development.  It is not ready for
+Agent Substrate is currently in early development.  It is not ready for
 production use, and the APIs are almost guaranteed to change.  We are not
 making any guarantees about backward compatibility at this stage, and
 everything in this project may be changed.

docs/architecture.md

@@ -4,72 +4,40 @@ NOTE: Much of this architecture is aspirational, and is not yet implemented!
 
 ## Overview
 
-Agent Substrate is a system built on top of Kubernetes which manages agent-like
-workloads to achieve high workload density and scale.  It builds on top of
-Kubernetes, but takes the Kubernetes control-plane out of the critical path to
-achieve lower latency. Kubernetes provides the infrastructure provisioning and
-management, while Agent Substrate provides agent-specific scheduling and
-control.
+Agent Substrate delivers a performant, high density runtime environment for large scale agent deployments. The agent substrate control plane provides full lifecycle management for agent sandboxes, delivering sub-second agent resume/suspend operations, and allows heavy multiplexing of agents onto the same computer infrastructure. It supports multiple sandbox technologies including microVMs and gVisor, enabling consistent lifecycle operations for all sandbox types.
 
-## Problem Statement
+At its core, Agent Substrate maps a larger set of “actors” (applications such
+as agents) onto a smaller set of ready “workers”, relying on
+the fact that agent-like applications tend to be idle most of the time to
+achieve heavy multiplexing.  It provides functionality to manage an actor’s
+lifecycle (e.g. create/destroy, suspend/resume), to assign actors to workers in real
+time, and to route incoming traffic to them.
 
-Kubernetes is the industry standard platform for running modern workloads.  It
-is built to support a wide array of workloads, and it can scale to very large
-clusters.  Kubernetes is designed to handle tens- or hundreds-of-thousands of
-relatively long-running workloads, but running agents at scale presents new
-challenges.
 
+## Problem Statement
 Agents and "agent-like" workloads are generally very bursty, spending most of
 their time waiting for input or events, then handling those events, then going
 back to waiting.  The time they spend actually doing work is often very short,
 and the time they spend waiting can be unbounded.  Because they often run
 untrusted logic, they are often run in sandboxes, which means they are usually
 single-tenant instances, and there are a great many of them.
 
-Running these on Kubernetes presents a number of challenges:
-  * Idle Pods still consume resources.  While Kubernetes is very scalable,
-    compute capacity is finite and has real costs.  Whether we're talking about
-    CPU time, memory space, or just the number of Pods per node, agent-like
-    workloads are terrible for efficiency.
-  * The Kubernetes API server is not designed to handle millions of resources.
-    It excels at reconciling resources asynchronously across many controllers,
-    but it is not so good at storing very large numbers of discrete resources,
-    or for handling a huge volume of write traffic.
-  * Scheduling a workload on Kubernetes requires several asynchronous processes
-    to converge, plus several network hops, plus image pulling and other steps,
-    which can add up.  Getting a Pod running in a couple of seconds is great
-    when that Pod will run for hours or days, but for a workload that will run
-    for milliseconds to low-digit seconds, that latency is unacceptable.
-  * State management is difficult.  Kubernetes provides an API for managing
-    state (PersistentVolumes), but it is not designed for millions of volumes,
-    with widely varying amounts of data, being attached and detached at high
-    speed.
-
 ## Core Concepts and Approaches
 
-Standard Kubernetes Pods are simply too heavy for many agentic workloads.
-
 ### Terminology: "Actor"
 
 Agent Substrate seeks to solve these problems for "agent-like" workloads.
 Often we simply say "agents", but it's important to clarify that "agent-like"
 workloads are not necessarily literally AI agents.  In most of the docs we
 instead use the term "actor" to refer to an instance of an agent-like workload.
 
-### Decoupling the Actor Lifecycle from Pods
-
-The obvious way to solve the problem of many idle Pods consuming resources is
-to not have idle Pods - we need to get rid of them when they are idle, and
-bring them back when they are needed.  Suspend and resume is not a concept in
-Kubernetes (yet!), but even if it was, the obvious way to implement it would
-still run through the Kubernetes API server and scheduling subsystem, which is
-(for now) too slow for our needs.
+### Decoupling the Actor Lifecycle from Workers (Kubernetes Pods)
 
 Since many agents run untrusted code, we need to run them in sandboxes of some
-sort.  There are a number of sandboxing technologies available, notably
+sort. Agent Substrate is designed to support multiple sandbox technologies with
 [gVisor](http://gvisor.dev) and micro-VMs such as
-[Kata Containers](https://katacontainers.io/) are both popular options.  Both
-of those happen to support some notion of suspend and resume.
+[Kata Containers](https://katacontainers.io/) being popular options. Both
+of those happen to support a notion of suspend and resume which is core for the Agent Substrate functionality.
 
 Agent Substrate starts with suspend and resume.  When an actor is idle, we
 suspend it, which frees up the resources it was consuming.  When an event comes
@@ -83,12 +51,8 @@ latency.
 
 ### A Focused Control Plane
 
-That doesn't solve the problem of the Kubernetes API server not being ready to
-handle millions of resources.  Unfortunately, there is no magic solution to
-that.  Instead of storing every actor, whether active or idle, as a Kubernetes
-object, Agent Substrate includes a small, focused control-plane component which
-is focused on high scale and QPS.  It does not need the generality of the
-Kubernetes API, which should allow it to be more effective for this use-case.
+Agent Substrate includes a small, focused control-plane component which
+focuses on high scale, QPS and low-latency suspend/resume operations for actors (Agent Sandboxes). It relies on the Kubernetes control plane for infrastructure and worker (Pods) provisioning which are low-frequency operations that align well with Kubernetes' strength in the infrastructure lifecycle management and workload resource isolation.
 
 ### Agent-Aware Routing
 
@@ -181,6 +145,32 @@ There are a few different personas that interact with the system:
      Agent Substrate as a building block. They should not need to be aware that
      they are using Kubernetes at all.
 
+## Relationship to Kubernetes
+
+Kubernetes is the industry standard platform for running modern workloads.  It
+is built to support a wide array of workloads, and it can scale to very large
+clusters. Agent Substrate leverages Kubernetes for infrastructure provisioning and worker lifecycle management (Kubernetes Pods). It builds on top of Kubernetes features like Pods and Pod autoscaling, while Agent Substrate provides agent-specific scheduling and control to achieve lower latency. Using Kubernetes as the underlying system enables consistent infrastructure management across all workloads types that are required for end to end agentic deployments and allows holistic infrastructure optimizations for RL scenarios that span agentic, inference and training cycles.
+
+### Why do we need a specialized control plane for Agent Substrate?
+ * Idle Pods still consume resources.  While Kubernetes is very scalable,
+   compute capacity is finite and has real costs.  Whether we're talking about
+   CPU time, memory space, or just the number of Pods per node, agent-like
+   workloads are terrible for efficiency.
+ * The Kubernetes API server is not designed to handle millions of resources.
+   It excels at reconciling resources asynchronously across many controllers,
+   but it is not so good at storing very large numbers of discrete resources,
+   or for handling a huge volume of write traffic.
+ * Scheduling a workload on Kubernetes requires several asynchronous processes
+   to converge, plus several network hops, plus image pulling and other steps,
+   which can add up.  Getting a Pod running in a couple of seconds is great
+   when that Pod will run for hours or days, but for a workload that will run
+   for milliseconds to low-digit seconds, that latency is unacceptable.
+ * State management is difficult.  Kubernetes provides an API for managing
+   state (PersistentVolumes), but it is not designed for millions of volumes,
+   with widely varying amounts of data, being attached and detached at high
+   Speed.
+Using a specialized Agent Substrate control plane for Actor allows us to achieve high scale and low latency control. We still rely on Kubernetes for infrastructure provisioning, such as worker pods, and workload isolation, which is what Kubernetes excels at.
+
 ## High-Level Design
 
 A substrate admin deploys the Agent Substrate into a Kubernetes cluster.  They

docs/roadmap.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Agent Substrate is a Kubernetes-based system for building multitenant applications based on independent, stateful container instances. Substrate builds on sandboxed, snapshottable Pods by adding the ability to update running containers in the Pod without invoking the Kubernetes scheduler. Substrate enables these containers to rapidly cycle between active and inactive lifecycle phases with fast suspend and resume from snapshots in inexpensive cloud object storage, without losing in-memory or filesystem state. This is especially critical for agentic workloads, which frequently oscillate between active (handling user input) and idle (waiting for LLMs or tool calls to complete). With Substrate, resources can be reclaimed during these idle moments for use by other workloads. This enables both greater efficiency and greater scale than using Pods alone, while still leveraging Kubernetes to provision capacity, configure networking and storage, and manage Substrate itself.
+Agent Substrate delivers a performant, high density runtime environment for large scale agent deployments. The agent substrate control plane provides full lifecycle management for agent sandboxes, delivering sub-second agent resume/suspend operations, and allows heavy multiplexing of agents onto the same computer infrastructure. It supports multiple sandbox technologies including microVMs and gVisor. Substrate builds on sandboxed, snapshottable Pods by adding the ability to update running containers in the Pod leveraging the high scale and low latency Agent Substrate control plane. Substrate enables these containers to rapidly cycle between active and inactive lifecycle phases with fast suspend and resume from snapshots in inexpensive cloud object storage, without losing in-memory or filesystem state. This is especially critical for agentic workloads, which frequently oscillate between active (handling user input) and idle (waiting for LLMs or tool calls to complete). With Substrate, resources can be reclaimed during these idle moments for use by other workloads. This enables both greater efficiency and greater scale than using Pods alone, while still leveraging Kubernetes to provision capacity, configure networking and storage, and manage Substrate itself.
 
 This project is trying to move very quickly to find the right set of capabilities for the ever-changing agentic workloads market. Below are our priorities. Any efforts which are not aligned with these priorities should probably be deferred.