Examples

This directory contains examples demonstrating how to use the Google Antigravity Rust SDK.

Getting Started

1. Hello World Example (hello_world.rs)

A simple console application that configures the agent, launches the mock localharness server, sends a user message, streams the response, and exits cleanly.

To run this example:

cargo run --example hello_world

---

Web Integration Examples

The SDK provides two web integration patterns depending on your deployment target:

Example	Runtime	SDK Integration	Use Case
leptos_axum	Native (Tokio)	Full Agent SDK	Standard web servers (VPS, Docker, bare metal)
leptos_ssr_axum + agent_server	Spin/WASI	Full Agent SDK (via sidecar)	Edge/serverless (Akamai, SpinKube)

---

2. Leptos + Axum (Native)

Path: leptos_axum/

A full-featured chat application using Leptos (v0.8) with native Axum as the web server. The Agent runs in-process — no sidecar needed.

Prerequisites:

• localharness binary installed (./scripts/install_harness.sh)
• GEMINI_API_KEY environment variable set
• cargo-leptos installed

Run:

cd examples/leptos_axum
echo "GEMINI_API_KEY=your-key" > .env
cargo leptos serve

Open http://localhost:3000 in your browser.

Architecture:

Browser → Axum Server (native)
               ├─ Agent::chat()
               ├─ WebSocket → localharness
               └─ Gemini API

---

3. Leptos + Spin/WASI

Path: leptos_ssr_axum/

A chat application that runs as a Spin WebAssembly component (integrating Leptos with Spin via leptos-spin). Since Spin components cannot make outbound TCP/WebSocket connections (only wasi:http), this example runs in Sidecar Mode using the agent_server sidecar to get full SDK features (harness, tools, hooks, and policies).

# Terminal 1: Start the sidecar (runs full SDK + localharness)
cd examples/agent_server
GEMINI_API_KEY=your-key cargo run

# Terminal 2: Start Spin
cd examples/leptos_ssr_axum
spin build --up

Architecture:

Browser → Spin Component (WASI)
               │
               ├─ POST /chat ──→ agent_server (native sidecar)
               │                      ├─ Agent::chat()
               │                      ├─ WebSocket → localharness
               │                      └─ Gemini API
               │
               └─ KV Store (chat history)

Note: While standard Spin components are restricted to wasi:http for outbound traffic (necessitating sidecar mode), the SDK compiles directly to the wasm32-wasip1 target. In WASI environments that permit raw outbound TCP sockets, the SDK can connect directly to the host-side harness server via WebSockets using WasmConnectionStrategy.

---

4. Agent Server (Sidecar)

Path: agent_server/

A lightweight HTTP server that wraps the full antigravity-sdk-rust Agent and exposes it via REST/SSE. Designed as a companion sidecar for Spin/WASI applications that cannot use TCP/WebSocket directly.

SSE Sidecar Architecture & WASI Bridging

Standard WebAssembly components deployed to edge environments like Spin or SpinKube are compiled to target WASI. Because standard WASI runtimes do not currently support raw outbound TCP/WebSocket sockets (supporting only outbound HTTP requests via wasi:http), a native WebAssembly guest cannot establish the WebSocket connection required to communicate with localharness.

To bridge this runtime limitation:

1. Host-Side Sidecar: The agent_server runs as a native host-side process alongside the WASI sandbox. It manages the full Rust SDK agent lifecycle, starts the localharness subprocess, and handles raw bidirectional WebSocket traffic.
2. Server-Sent Events (SSE) Proxy: The sidecar exposes an HTTP/SSE interface. The WASI guest makes outbound HTTP requests to the sidecar, which proxies commands to the agent and streams updates back using SSE events.

Browser ──[HTTP/SSE]──→ Spin Component (WASI) ──[HTTP/SSE]──→ agent_server (native sidecar)
                                                                 ├─ Agent::chat()
                                                                 ├─ WebSocket → localharness
                                                                 └─ Gemini API

Endpoints

Method	Path	Description
GET	/chat/stream	Initiates an SSE (Server-Sent Events) chat stream for a session. Query parameters: session_id, message.
POST	/halt	Halts/terminates a running chat stream. Request body: {"session_id": "..."}.
POST	/answer	Answers/replies to an interactive question. Request body: {"session_id": "...", "trajectory_id": "...", "step_index": 0, "responses": [{"selected_option_ids": ["..."], "freeform_response": "...", "skipped": false}], "cancelled": false}.
POST	/confirm	Approves or denies a pending tool execution confirmation hook request. Request body: {"session_id": "...", "trajectory_id": "...", "step_index": 0, "accepted": true, "allow_for_session": false, "tool_name": "RUN_COMMAND"}.
GET/POST	/workspace	Gets or sets the workspace directory for the session.
GET	/resolve/folder	Resolves details about a folder in the workspace.
GET	/health	Health check.

Environment Variables

Variable	Default	Description
GEMINI_API_KEY	(required)	Your Gemini API key
AGENT_SERVER_PORT	8080	Port the sidecar listens on
GEMINI_MODEL	gemini-3.5-flash	Model to use
ANTIGRAVITY_HARNESS_PATH	bin/localharness	Path to localharness binary

Note: The agent_server automatically enables Google Search grounding and URL context resolution (enable_google_search: true, enable_url_context: true) in its GeminiConfig setup.

Run

cd examples/agent_server
GEMINI_API_KEY=your-key cargo run

Test with curl (Stream)

curl -N "http://127.0.0.1:8080/chat/stream?session_id=sess_test&message=hello"