-
-
spire adk
Inspiration
Small businesses face a difficult Google Ads problem: they need expert-level campaign management, but often cannot afford a dedicated specialist. Existing AI tools can summarize reports or generate ad copy, yet most stop at recommendations. The operator still has to interpret the advice, find the correct settings, make the changes, verify them, and continue monitoring the account.
I encountered this gap while working with real Google Ads accounts. I wanted an agent that could complete the operational workflow—not just talk about it—while remaining unable to invent permissions, change an unapproved payload, or hide an uncertain result. That became Spire.
What it does
Spire is an autonomous Google Ads Search operator for small businesses and solo entrepreneurs. It supports two common starting points:
- New accounts: Spire gathers the business objective, detects missing information, evaluates readiness, builds a complete Search campaign, validates it, requests approval, and creates it in a paused state.
- Accounts with history: Spire analyzes campaigns, keywords, search terms, ads, measurement, and performance evidence. It then recommends a grounded action, validates the exact change, requests approval, applies it, verifies the result, and schedules outcome monitoring.
Its lifecycle is:
Understand → Assess → Investigate → Decide → Validate → Approve → Execute → Verify → Observe → Learn
Spire can work asynchronously, but autonomy always operates inside explicit boundaries. Every mutation uses a frozen payload, an exact hash, a single-use approval, freshness checks, idempotency, and semantic read-back from Google Ads.
If a request fails before being sent, it can be retried safely. If the result is ambiguous after transmission, Spire does not retry blindly—it reconciles the live account state first.
How we built it
For this project, I am rebuilding Spire from scratch using the Google agent ecosystem. A separate laboratory project is used only as a source of proven capabilities, tests, and sanitized data; the new application has no runtime dependency on it.
The architecture separates reasoning from operational authority:
- Gemini 3.5 Flash and Google ADK act as the agent host. They interpret goals, ask clarifying questions, select workflows, and explain decisions.
- An Application/Macrotool Facade exposes a small set of stable business tools for account assessment, campaign analysis, optimization, validation, execution, and reconciliation.
- The Spire Control Plane owns identity, policies, evidence, readiness, decisions, approvals, execution state, verification, incidents, and outcomes.
- The Google Ads API provides account data, remote
validate_onlychecks, mutations, and live read-back. - Cloud Run hosts the agent, API, UI, and workers.
- Firestore is the authoritative operational store from the first write.
- Cloud Storage stores sanitized evidence bundles and larger analytical artifacts.
- Pub/Sub and Cloud Scheduler support background checks, reconciliation, and outcome reviews.
- Secret Manager protects credentials, while Cloud Logging, Trace, and OpenTelemetry provide auditability.
The UI consumes the same facade as the ADK agent. It never calls Google Ads directly, and its buttons are generated from next_legal_actions, so it cannot offer an operation that the control plane considers illegal.
Challenges we ran into
The central challenge is connecting probabilistic reasoning to financial side effects. A language model is useful for interpreting business goals and explaining evidence, but identity, money, permissions, hashes, retries, and mutations must remain deterministic.
Other important challenges include:
- Supporting an empty account without forcing a historical extraction workflow.
- Distinguishing a configured account from one with mature evidence.
- Separating serving readiness from conversion-optimization readiness.
- Handling Google Ads policy delays and eventual consistency.
- Preventing duplicate mutations after crashes, timeouts, or repeated events.
- Ensuring that a successful API response is not treated as verified until live read-back matches the approved payload.
- Keeping the agent’s tool surface small without losing the deeper capabilities of the system.
Accomplishments that we're proud of
A separate laboratory prototype already validated the underlying mechanics for reading Google Ads data, creating paused Search campaigns, adding ad groups and negatives, modifying URLs and bidding settings, using single-use approvals, performing semantic read-back, and reconciling uncertain operations.
For the hackathon version, the main architectural accomplishment is turning those lessons into a focused, agent-native product rather than copying the laboratory:
- One governed lifecycle for every side effect.
- A clear boundary between the ADK agent host and the deterministic control plane.
- Independent artifacts for decisions, changes, approvals, executions, verification, and outcomes.
- Explicit
PRODUCTION,DEMO_SANDBOX, andREPLAYexecution modes. - A small business-oriented tool surface instead of exposing internal commands.
- A replayable demo that can prove behavior without requiring live credentials.
- Honest states such as
APPLIED_UNVERIFIEDandUNKNOWN_RECONCILIATION_REQUIREDinstead of presenting every response as success.
What we learned
The most important lesson is that an autonomous agent is not simply a prompt with access to many tools. Reliable autonomy requires durable state, constrained capabilities, explicit authority, idempotency, verification, and a safe way to resume after the conversation disappears.
I also learned that:
- More tools do not automatically create a better agent; stable business workflows are more valuable.
- A successful mutation response is not the same as a verified business change.
- Readiness must be evaluated for each action instead of reducing an account to one global status.
- The agent’s memory cannot be the source of truth for financial operations.
- Human approval does not eliminate autonomy—it defines the boundary within which the agent can safely complete the work.
- An agent should be able to conclude
WAITorNO_ACTIONwhen the evidence is insufficient.
What's next for Spire: Autonomous Google Ads Operator
The immediate goal is to complete and deploy two end-to-end vertical workflows:
- Turn an empty Google Ads account into a validated, human-approved, paused Search campaign.
- Analyze an account with history and apply an evidence-backed negative keyword through the complete validation, approval, execution, verification, and monitoring lifecycle.
After that, I will expand the mutation catalog, strengthen ADK trajectory evaluations, add longer-term outcome learning, improve multimodal business onboarding, and support additional Google Ads campaign types—all while preserving the same governed control plane.
