5.4 Ray on Agent Platform for Distributed Python Workloads
Key Takeaways
- Ray on Agent Platform provides a managed Ray cluster of head and worker nodes for distributed Python and ML workloads, with autoscaling or manual scaling per worker pool.
- A Ray cluster persists until explicitly deleted, unlike a custom training job whose resources are released at completion — which makes forgotten clusters an expensive failure mode.
- Ray suits workloads that are not naturally a DAG: hyperparameter sweeps, reinforcement learning, distributed Python data processing, and large-scale batch inference.
- The Ray on Agent Platform SDK bundles the Ray client, a BigQuery connector, cluster management, and integration with Agent Platform Inference.
- Choose Pipelines for ordered, reproducible, scheduled workflows and Ray for interactive or embarrassingly parallel distributed Python.
5.4 Ray on Agent Platform for Distributed Python Workloads
Blueprint reference: Section 5.1, "Building and orchestrating pipelines using managed or unmanaged services and from templates or custom solutions (e.g., Agent Platform Pipelines, Managed Service for Apache Airflow, and Ray on Gemini Enterprise Agent Platform)."
Ray is the newest of the three named options and the one least covered by pre-2026 study material, which makes it worth knowing precisely.
What a Managed Ray Cluster Is
Ray is an open-source framework for scaling Python and AI applications across a cluster. Ray on Agent Platform is a managed Ray cluster: Google provisions and operates the head node and worker pools, and you connect to it with ordinary Ray code.
Structure:
- A head node coordinating the cluster.
- One or more worker pools, each with its own machine type and optional accelerators.
- Autoscaling or manual scaling per worker pool.
- Connectivity from a notebook, a script, or another Google Cloud service through the Ray client.
The headline property, and the one that shows up in exam questions: a Ray cluster remains available until you delete it. A custom training job releases its resources when the job finishes. A Ray cluster does not. That is exactly what makes it good for interactive distributed development — you attach, experiment, detach, and reattach without waiting for provisioning — and exactly what makes a forgotten cluster an expensive incident.
The Ray Libraries That Matter for ML
| Library | Purpose |
|---|---|
| Ray Core | Tasks and actors — the general distributed Python primitives |
| Ray Tune | Distributed hyperparameter search, including early stopping schedulers |
| Ray Train | Distributed training wrappers for PyTorch, TensorFlow, and others |
| Ray Data | Distributed data loading and preprocessing across the cluster |
| Ray Serve | Model serving, including multi-model composition |
| RLlib | Reinforcement learning at scale |
Ray Tune and RLlib are the two that most often decide a question. Reinforcement learning in particular is a workload that fits Ray naturally and fits a DAG-based pipeline poorly, because the loop between agent and environment is not a sequence of discrete stages.
Integration Points
The Ray on Agent Platform SDK is the Agent Platform SDK extended with the Ray client, cluster management, a BigQuery connector for reading and writing warehouse data directly from Ray workers, and integration with Agent Platform Inference so a model trained on the cluster can be deployed without leaving the workflow.
import ray, vertex_ray
from google.cloud import aiplatform
aiplatform.init(project=PROJECT, location=REGION)
ray.init(address=vertex_ray.get_ray_cluster(CLUSTER_ID).dashboard_address)
# Workers read directly from BigQuery, no export step
ds = ray.data.read_bigquery(project_id=PROJECT, dataset="analytics", table="events")
Ray Versus Pipelines Versus Airflow
All three appear in the same blueprint bullet, so the distinctions matter.
| Agent Platform Pipelines | Managed Service for Apache Airflow | Ray on Agent Platform | |
|---|---|---|---|
| Model | Serverless ML DAG execution | Managed Airflow for general workflow orchestration | Managed distributed Python compute cluster |
| Unit of work | Containerized component | Operator task | Python task or actor |
| Best at | Reproducible, versioned ML workflows with lineage | Cross-system scheduling and dependencies | Parallel or interactive distributed Python |
| Resource lifetime | Per run; nothing between runs | Environment runs continuously | Cluster persists until deleted |
| Cost when idle | None | Environment cost | Full cluster cost |
| Weak at | Non-DAG workloads | ML lineage and artifact typing | Reproducible scheduled workflows |
Two clean signals:
- "Reproducible, scheduled, with lineage and artifact tracking" → Pipelines.
- "Distribute this Python workload across many machines", especially hyperparameter sweeps, RL, or large-scale Python batch inference → Ray.
Airflow is the answer when orchestration spans systems beyond ML — waiting on a warehouse load, triggering a downstream ETL, coordinating with non-ML jobs. Note the naming: Cloud Composer was renamed Managed Service for Apache Airflow in 2026, while the API, gcloud commands, and IAM roles still say composer.
They also compose. A pipeline step can submit work to a Ray cluster, and an Airflow DAG can trigger a pipeline run.
Operating a Ray Cluster Responsibly
- Delete clusters when finished. The single most important habit; there is no automatic release at job completion.
- Size worker pools to the workload and use autoscaling so idle workers are removed even while the cluster lives.
- Keep the head node small. It coordinates; it does not need accelerators.
- Use accelerator worker pools only for the stages that need them. A sweep whose trials are CPU-bound should not run on GPU workers.
- Checkpoint long runs to Cloud Storage as with any other long training workload.
Exam Traps
- Assuming a Ray cluster releases resources like a job. It persists until deleted.
- Choosing Ray for a scheduled, reproducible ML workflow. That is Pipelines.
- Choosing Pipelines for reinforcement learning. Not a DAG-shaped workload.
- Expecting Airflow to provide ML artifact lineage. It schedules; it does not type artifacts.
- Forgetting the 2026 Composer rename when reading current documentation.
A research team runs reinforcement learning experiments requiring thousands of parallel environment simulations coordinated with a central learner, and wants to attach and detach interactively over several weeks. Which option fits best?
A team provisions a Ray cluster with GPU worker pools for a two-day experiment, completes the work, and moves on. A month later finance reports substantial ongoing charges. What is the cause?
A platform team needs a nightly ML workflow with typed artifact passing, execution caching, and full lineage recorded for audit, running on a schedule with no cluster to operate. Which option should they choose?
An engineer reading 2024 documentation cannot find "Cloud Composer" in the current console or docs. What happened?