How I built ROACLAW

The problem was never “generate another recommendation”

Paid-media operators already have dashboards, alerts, spreadsheets, and AI-written suggestions. The hard part begins after an insight: deciding whether a change is allowed, binding it to the correct tenant and campaign, preventing duplicate execution, checking the provider’s readback, and recording what actually happened.

ROACLAW started from a stricter question: what would an agent need in order to help with money-changing operations without becoming the authority over money?

The central design rule

Gemini reasons. Deterministic code authorizes. The model receives a goal and an explicitly synthetic campaign snapshot, then returns one closed recommendation contract. An exact-key parser rejects malformed output. Deterministic policy checks the action, confidence, maximum change, lead pacing, and spend guardrail before any state transition is considered.

The model has no provider secret, generic HTTP tool, generic SQL tool, approval bypass, or direct execution path. This separation made the system easier to test and the demo more truthful.

What the working build does

1. The operator defines a bounded business goal.
2. The system presents campaign evidence in an English or Arabic/RTL workflow.
3. Gemini 3.5 Flash produces a typed recommendation through the Google GenAI SDK on Vertex AI.
4. Deterministic policy accepts or rejects that recommendation.
5. The hackathon proof changes only response-local synthetic state.
6. A computed state check and response-local ledger describe the result and their exact scope.

The reviewed interface also exposes mismatch, unknown-dispatch, reconciliation, and compensation states. Those are not side cases; they are the product’s answer to provider ambiguity.

Architecture

The judged web journey is built with React, TypeScript, and Vite. A separate FastAPI proof service uses Pydantic, the Google GenAI SDK, Vertex AI, and Gemini 3.5 Flash. The web build and proof API share one Docker image built by Google Cloud Build and deployed to Cloud Run, but the fixture UI does not call the proof endpoint. They are separate judge surfaces.

A separate, security-reviewed Google Ads REST v25 pause/resume adapter exists behind a private executor boundary. OAuth test-campaign readback was not completed before the submission, so I do not claim a live advertising-account mutation.

Google Cloud proof without uncontrolled spend

The public Cloud Run revision serves the interface, /v1/health, and /v1/proof. It runs with minimum instances 0, maximum instances 1, and CPU throttling. Anonymous POST /v1/demo/run requests return HTTP 403 before invoking Gemini, preventing public traffic from creating uncontrolled Vertex AI cost.

An earlier private revision completed one authenticated Gemini invocation with HTTP 200. The public read-only revision and the private live-model proof are intentionally documented as separate pieces of evidence.

Testing the governed path

The focused submission verification covers 44 web unit/component tests, 18 Playwright desktop/mobile scenarios, and 14 Gemini SDK/API/policy tests, plus type checking and a production web build. The README includes pinned Node, pnpm, Python, and uv versions together with local, browser, API, and Docker commands.

The most valuable tests are the fail-closed ones: extra model keys, unsupported actions, low confidence, oversized changes, tenant mismatches, stale approvals, and unknown dispatch cannot silently fall through to success.

What challenged me

The hardest part was making a complex safety boundary understandable in a short product journey. It was tempting to make the demo look more “live” than the evidence supported. Instead, I kept the SIMULATED WORKSPACE label visible and treated unknown as a real outcome rather than fabricating success or retrying blindly.

Arabic/RTL parity was another architecture concern rather than a translation pass. Direction, hierarchy, evidence density, approval language, and recovery states all needed to remain equivalent across both languages.

What I learned

Agent quality is not only model quality. High-stakes agents need narrow contracts, deterministic authority, capability discovery, idempotency, exact readback, and evidence that preserves the difference between verified, mismatched, and unknown outcomes.

I also learned that honest limitations strengthen a technical demo. A clearly labeled synthetic effect is more useful than a provider mutation implied by a screenshot.

What comes next

The next milestone is a consented Google Ads test-account OAuth proof with exact mutation and rollback readback. After that: scheduled measurement ingestion, richer provider capability discovery, voice as untrusted structured input, and policy-gated sandbox operations for additional channels.