Skip to content

feat(sandbox-adapter): add Google Cloud Agent Platform provider - #396

Draft
NathanFlurry wants to merge 1 commit into
mainfrom
task-20261114-130155-96f64422-gcp
Draft

NathanFlurry wants to merge 1 commit into
mainfrom
task-20261114-130155-96f64422-gcp

Conversation

@NathanFlurry

@NathanFlurry NathanFlurry commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Adds a Gemini Enterprise Agent Platform shell sandbox provider at @rivet-dev/sandbox-adapter/agent-platform. Agent Platform was formerly Vertex AI Agent Engine, and its shell sandboxes went GA on 2026-09-09.

sandbox: agentPlatformProvider({
	template: "projects/p/locations/us-central1/reasoningEngines/ENGINE/sandboxEnvironmentTemplates/TEMPLATE",
	create: { ttl: "86400s" },
}),

Why this product: Agent Compute Engine was announced on 2026-10-22, but it has only a preview sign-up form and no API yet. Cloud Run sandboxes are an in-service CLI, not a remote API. GKE Agent Sandbox is CRDs on your own cluster. That leaves Agent Platform's reasoningEngines.sandboxEnvironments as the hosted sandbox API on GCP.

Lifecycle

Event REST call (https://{location}-aiplatform.googleapis.com/v1)
First tool use POST {engine}/sandboxEnvironments with the template, then poll the operation. The sandbox's full resource name is the id. create can be a function of the Actor context.
Wake GET {id}. STATE_PAUSED gets :resume. Provisioning, pausing, and resuming states are waited on. A 404 or a stopping, deprovisioning, terminated, or deleted sandbox returns undefined.
Sleep :pause. 404 and FAILED_PRECONDITION are ignored.
Destroy DELETE {id}. 404 is ignored.

google-auth-library is an optional peer dependency. It is imported only when no auth is passed. Any { getAccessToken() } works.

Commands and files

:execute is a proxy. Its chunks address the shell server at /exec on port 8080, the same request Google's Python execute_bash sends. The shell server has these limits, and the provider handles each one:

Shell server limit Provider behavior
No env field Variables are exported before the command. Names are validated.
No streaming onData gets stdout and then stderr once the command ends. This is like Daytona.
No kill API Abort ends only the wait, and the command runs until its timeout. This is also like Daytona.
timeout in whole seconds. A timed-out command fails the request with DEADLINE_EXCEEDED and returns no output. That error becomes timedOut: true with a null exit code and empty output.
No file API for shell sandboxes File operations run as shell commands. readFile uses base64. writeFile sends 48 KiB chunks so each base64 argument stays under Linux's 128 KiB argument limit. Larger files are assembled in a temp file and moved into place.

Tests

tests/agent-platform.test.ts runs against a fake Agent Platform REST server. Its :execute handler runs each command in a real local bash -c, so the file scripts, quoting, env export, and the chunk size meet a real shell and the real argument limit. The suite covers:

  • template validation
  • create and operation polling
  • pause, resume, and delete
  • exit code, cwd, env with quotes, and onData
  • invalid env names
  • timeouts and abort
  • file operations on names with quotes and spaces
  • a 200 KiB chunked write

All 38 package tests pass.

On-demand live test

cd packages/sandbox-adapter
AGENT_PLATFORM_TEST_PROJECT=my-project pnpm test:live agent-platform

This runs tests/agent-platform.live.test.ts against a real shell sandbox with Application Default Credentials. It first creates a temporary Agent Engine and shell template in the project (AGENT_PLATFORM_TEST_LOCATION, default us-central1) and deletes them afterwards. The project needs aiplatform.googleapis.com enabled. Set AGENT_PLATFORM_TEST_TEMPLATE to reuse an existing template. Without either variable, the test fails with a message instead of using gcloud's default project. A full run takes about 2 minutes.

CI never runs it. vitest.config.ts excludes *.live.test.ts, and only vitest.live.config.ts, used by pnpm test:live, includes it. These two configs are identical to the ones in #395.

Live run (us-central1)

All 6 live tests pass. Creating the engine took seconds and the template about 2.5 minutes. The tests cover:

  • exec with the exit code, cwd, and env with quotes
  • timeouts
  • file operations on names with quotes and spaces
  • a 150 KiB chunked write
  • pause, then connect resuming the sandbox with its files kept (about 10 s)
  • delete

A command takes about 250 ms.

Confirmed:

  • The {name}:execute path works.
  • NUL bytes survive in /exec's JSON stdout, so readdir works.
  • Resource names come back with the project number.

Fixed from the live run:

  • Timeouts. A command that reaches its timeout does not return a result. The request fails with HTTP 400 FAILED_PRECONDITION: DEADLINE_EXCEEDED ... {"detail":"command exceeded 3s and was killed"}. The provider now reports this as timedOut: true. The fake server returns the same error.
  • Docs. They now enable aiplatform.googleapis.com, explain how to poll the template's operation for its name, and say that a timed-out command returns no output.

Still unverified:

  • The sandbox's default command time limit.
  • The default and maximum ttl.

Package and docs

  • scripts/test-packed.mjs checks that dist/agent-platform.js is packed.
  • The Sandboxes guide has a providers table row and a Google Cloud Agent Platform section with options, one-time engine and template setup, permissions, network, command behavior, and lifetime.
  • The Sandbox Adapter guide's table and output notes, and the docs index card, list it.
  • The example is examples/docs/sandboxes/agent-platform.ts.
  • This touches the same docs lines as feat(sandbox-adapter): add AWS Lambda MicroVMs provider #395, the AWS Lambda MicroVMs provider. Whichever merges second needs a small rebase.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

📟 Pip-Boy · 25f938d

📦 Packages · fresh npm install resolve, no lockfile · this PR vs base

No notable install size, dependency, or entrypoint changes across 10 packages.

All 10 packages · linux-x64-gnu
package (linux-x64-gnu) @latest base this PR Δ vs base packages
@rivet-dev/pi 392.5 MB 392.5 MB 392.6 MB +27.7 KB (+0.0%) 220 (0)
@rivet-dev/sandbox-adapter 114.5 KB 114.5 KB 142.2 KB +27.7 KB (+24.2%) 1 (0)
@sandbox-agent/cli-shared 27.2 KB 27.2 KB 27.2 KB 0 1 (0)
@sandbox-agent/persist-indexeddb 12.4 KB 12.4 KB 12.4 KB 0 1 (0)
@sandbox-agent/persist-postgres 12.3 KB 12.3 KB 12.3 KB 0 1 (0)
@sandbox-agent/persist-rivet 12.2 KB 12.2 KB 12.2 KB 0 1 (0)
@sandbox-agent/persist-sqlite 12.3 KB 12.3 KB 12.3 KB 0 1 (0)
@sandbox-agent/react 41.6 MB 41.9 MB 41.9 MB 0 15 (0)
acp-http-client 6.7 MB 6.7 MB 6.7 MB 0 3 (0)
sandbox-agent 31.0 MB 31.0 MB 31.0 MB 0 8 (0)

🧹 Rust dependencies

Skipped: this PR doesn't change any Rust code or dependencies.

🦀 Binaries

Skipped: this PR doesn't change any Rust code.

⏱ Timing

job wall time slowest step
changes 16s checkout · 13s
zizmor 16s checkout · 10s
footprint 2m12s Pack the base · 34s
⏭ self-test — skipped
⏭ native · ${{ matrix.platform }} — skipped
⏭ hygiene — skipped
report 28s setup-node · 11s
🔭 Full CI trace for this commit

One OpenTelemetry trace of CI and Pip-Boy for 25f938d: every job and step, with the sizes above attached. Run after CI finishes.

pnpm install --frozen-lockfile --filter 'pipboy...'
pnpm --filter pipboy pipboy trace --sha 25f938d18e272fd092aa73bc187613940c633152

Add --otlp <url> to send it to any OTLP/HTTP collector.

Agent instruction: From a rivet-dev/agents checkout, run the commands above, then read the trace file the last command prints. List the slowest jobs and steps and explain where CI time went.

@NathanFlurry
NathanFlurry force-pushed the task-20261114-130155-96f64422-gcp branch 2 times, most recently from 13cc4c6 to 0f27518 Compare November 15, 2026 19:53
Add @rivet-dev/sandbox-adapter/agent-platform. Each Actor gets one
Gemini Enterprise Agent Platform shell sandbox, created from a shell
template, paused while the Actor sleeps and deleted when it is
destroyed.

The REST API is called directly with google-auth-library, an optional
peer dependency loaded only when no auth is passed. Commands go through
the sandbox's :execute proxy to its /exec server, which returns output
when a command ends and cannot stop one. Shell sandboxes have no file
API, so file operations run as shell commands, with large writes sent
in chunks and moved into place.

`pnpm test:live` runs tests/agent-platform.live.test.ts against a real
shell sandbox. It creates a temporary Agent Engine and template in
AGENT_PLATFORM_TEST_PROJECT and deletes them afterwards, unless
AGENT_PLATFORM_TEST_TEMPLATE names an existing template. CI never runs
it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@NathanFlurry
NathanFlurry force-pushed the task-20261114-130155-96f64422-gcp branch from 0f27518 to 25f938d Compare November 15, 2026 19:54

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant