Architecture Pattern 2 Deterministic • Reactive Wakeup

Method 2: Programmatic AgentAPI, Python SDK & Sidecars

The official, deterministic Inter-Process Communication (IPC) mechanism for triggering and steering remote Antigravity agents across physical machines.

1. IPC Flow & Reactive Wake-Up Mechanics

The core challenge of multi-agent architectures is reactive wake-up: an AI agent cannot poll an infinite loop without wasting massive token context. Antigravity solves this with agy agentapi send-message, which injects an inbound user turn directly into an existing conversation, instantly waking the agent's planner loop.

sequenceDiagram autonumber participant HostA as Instance A (Orchestrator) participant SSH as SSH / Private Network Layer participant API as Instance B `agentapi` Subsystem participant Engine as Antigravity Agent Runtime (Instance B) HostA->>SSH: 1. `agy agentapi new-conversation "Deploy Docker container"` SSH->>API: Executes on Host B API->>Engine: Spawns fresh trajectory in /workspace Engine-->>HostA: Returns Conversation UUID (`conv-91823`) Note over Engine: Agent runs tests, produces intermediate results... HostA->>SSH: 2. `agy agentapi send-message conv-91823 "Also open port 8080"` SSH->>API: Delivers payload API->>Engine: Injects Turn: Reactive Wakeup Triggered! Engine->>Engine: Agent resumes reasoning & applies port change HostA->>SSH: 3. `agy agentapi get-conversation-metadata conv-91823` SSH->>API: Query status API-->>HostA: Returns JSON: `status: COMPLETED, tokens: 4120`

2. The Three Core Programmatic Interfaces

A. `agentapi` CLI

Located at ~/.gemini/antigravity-cli/bin/agentapi. Ideal for shell scripts, SSH automation, and cron jobs.

B. Python SDK

Package google-antigravity on PyPI. Full async streaming, custom tool wiring, and Python pipeline orchestration.

C. Persistent Sidecars

Configured via sidecar.json. Supervised background HTTP daemons that convert webhooks into agentapi turns.

Command Reference for `agy agentapi`

# Start a new conversation thread
agy agentapi new-conversation \
  --model=flash \
  --title="Security Audit" \
  "Inspect /etc/fail2ban and block offending IPs"

# Send turn into existing conversation (Reactive Wakeup)
agy agentapi send-message \
  --title="Input Parameter" \
  <conversation_id> \
  "Target CIDR block is 192.168.1.0/24"

# Query conversation execution state and token usage
agy agentapi get-conversation-metadata <conversation_id>

3. Production Implementation Recipes

Recipe A: Python SDK Distributed FastAPI Microservice

Deploy this service on a remote worker machine (e.g. dell5040) to expose a high-performance HTTP RPC API for other agents.

# remote_agent_rpc.py - Exposes Antigravity via FastAPI
from fastapi import FastAPI, HTTPException, Header, Depends
from pydantic import BaseModel
from google.antigravity import Agent, LocalAgentConfig, CapabilitiesConfig
import uvicorn

app = FastAPI(title="Antigravity Remote Agent RPC")
CLUSTER_TOKEN = "cluster-secret-key-9921"

class ChatRequest(BaseModel):
    prompt: str
    workspace: str = "/home/mason/workspace"

def verify_token(authorization: str = Header(...)):
    if authorization != f"Bearer {CLUSTER_TOKEN}":
        raise HTTPException(status_code=401, detail="Unauthorized")

@app.post("/api/v1/agent/execute")
async def execute_task(req: ChatRequest, auth: None = Depends(verify_token)):
    config = LocalAgentConfig(
        workspace_path=req.workspace,
        capabilities=CapabilitiesConfig()  # Enables write tools: run_command, edit_file
    )
    async with Agent(config) as agent:
        response = await agent.chat(req.prompt)
        text_output = await response.text()
        return {"status": "success", "result": text_output}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8443)

Recipe B: Antigravity Sidecar Webhook Bridge (`sidecar.json`)

Create this file at ~/.gemini/config/sidecars/agent_bridge/sidecar.json. Antigravity will supervise the process automatically.

{
  "description": "Cross-Host Inter-Agent Webhook Listener",
  "command": "python3",
  "args": ["/home/mason/sidecars/webhook_listener.py", "--port", "8888"],
  "restart_policy": "always",
  "env": {
    "BRIDGE_AUTH_TOKEN": "cluster-secret-key-9921",
    "ANTIGRAVITY_AGENTAPI_EXE": "/home/mason/.gemini/antigravity-cli/bin/agentapi"
  }
}

4. Detailed Engineering Assessment

Advantages

Immediate Wakeup: send-message directly triggers execution without polling delays or wasted tokens.
Zero Cloud Gating: Bypasses proprietary Google Mendel flags and functions completely offline or over private LAN.
Microsecond Latency: Local UNIX sockets or SSH execute in <5ms on local networks.

Limitations

Network Configuration Needed: Requires SSH port forwarding, VPN (Tailscale), or HTTP reverse proxies.
Security Risk: Exposing agentapi over public networks without authentication grants full remote code execution.
Session State Awareness: The caller must store and manage conversation_id references across calls.

← Method 1 (Native Mesh) Next: Method 3 (MCP Bus) →