VENDOR CLEARANCE AGENT

• 

  some of the criteria

• 

  evaluation

• 

  the power of policy foudry

• 

  procesión

Inspiration

I've spent years building infrastructure around one idea: that AI systems should never be the sole source of truth about what actually happened. Decisions, memory, evidence — those need to be deterministic and verifiable, even when the reasoning layer on top of them is a probabilistic model. When Google opened this hackathon around Gemini and autonomous agents, it felt like the right moment to take that philosophy out of my private projects and build something clean, from scratch, that anyone could inspect: an agent that gets to use a real LLM for judgment, without ever letting that LLM become the record of what it did.

Vendor proposal review was the perfect testbed. It's a genuinely messy, real chore — a business user gets a contract, asks "can we proceed?", and today either a human burns an hour cross-checking clauses against policy, or a chatbot confidently approves something it never actually verified. I wanted an agent that does the heavy lifting and is honest about the difference between "I checked this against policy" and "I don't have enough information to say."

What it does

Vendor Clearance Agent takes a vendor proposal — budget, SLA, data jurisdiction, contract terms — and runs it end-to-end through an autonomous clearance pipeline built on Gemini 3.5 Flash.

It checks the proposal against procurement policy. If everything fits, it clears the vendor and moves on with no human involved. If something doesn't fit — say, a 60-day auto-renewal notice window against a 30-day policy standard — the agent doesn't guess and doesn't force an answer. It abstains (has_answer = False), generates a specific clarification question through Gemini, and pauses only that one task, while the rest of the system stays free.

A human responds through a signed, single-use token — no chat app required. The moment that response comes back, the agent resumes automatically, re-verifies its own memory before doing anything external, and issues a final decision: approved, approved with a documented exception, or rejected.

Every step — ingestion, policy check, clarification, human response, final decision — is written to an append-only ledger, each entry cryptographically chained to the one before it with SHA-256. Before the agent takes any action with real consequences, a fail-closed execution gate recomputes that entire chain. If even one byte has been altered anywhere in the history, the agent halts immediately and refuses to proceed — it doesn't matter how confident the reasoning behind the pending action looks.

Every completed task exports a portable .eco evidence bundle, and a standalone HTML verifier (pure JavaScript, browser-native WebCrypto, no backend required) lets anyone — a judge, an auditor, a teammate — independently recompute every hash and confirm the bundle wasn't tampered with, without trusting my server at all.

On top of that core loop, three lightweight skills reuse the same evidence trail: a Policy Drift Analyzer that spots recurring friction and suggests policy adjustments, a Vendor Remediation Coach that turns a rejection into a concrete guide for the vendor to fix and resubmit, and an SLA Watchdog that checks real post-clearance performance against what was actually signed.

How we built it

The backend is Python/FastAPI with a SQLite (WAL mode) ledger locally, containerized with Docker and shipped with a Cloud Run service manifest and Firestore security rules for the production path. Gemini 3.5 Flash is called through Google's official google-genai SDK for two things only — generating the clarification question and synthesizing the executive audit summary — with a deterministic fallback template if no API key is present, so the pipeline is never blocked on network access. A minimal HTML dashboard exercises the whole flow, and the standalone verifier does full hash-chain validation client-side.

I built it working with an AI coding agent from the terminal, in deliberately small, testable phases: first a thin vertical slice of the entire pipeline running locally with mocked pieces, then hardening each part with real integrations, then the live tamper-attack demo, then the automated test suite, and only then polish. Nothing moved to the next phase until the previous one worked end-to-end and reproducibly.

Challenges we ran into

The honest ones, not the polished ones: getting a fresh Google Cloud project approved to issue a Gemini API key took longer than writing the execution gate, because new-account project creation got flagged by Google's own anti-abuse checks — the fix was creating the project through Cloud Console directly instead of the AI Studio shortcut. Reusing an API key from an older project of mine while I waited on that seemed harmless, until it burned through the Gemini free-tier's 20-requests-a-day limit in the middle of testing, and an ambient GOOGLE_API_KEY in my shell silently overrode the key I thought I was using — a reminder that verifiable systems still live inside very ordinary, very leaky environments.

On the code itself, the two bugs I'm gladest I caught were subtle: a Python falsy-string issue where explicitly passing an empty API key to force offline mode was silently ignored in favor of the real environment key, and a case where I generalized the policy check to flag multiple kinds of deviations at once but forgot to update the final decision summary — so an approval for a budget exception could still print a completely unrelated sentence about auto-renewal windows. Neither broke a single test. Both only showed up when I actually ran adversarial cases by hand instead of trusting green checkmarks.

Accomplishments that we're proud of

The tamper simulation is the one I keep coming back to: adulterate one field in the SQLite ledger, ask the agent to proceed, and watch it detect the exact byte that changed and refuse to move — every single time, deterministically, no matter what the reasoning layer thinks it should do. That, plus a browser verifier that trusts nothing but math to confirm an evidence bundle is genuine, is the whole thesis of the project made physically demonstrable in under a minute.

I'm also proud that the abstention logic actually resists the temptation to please — when the auto-renewal clause or the budget line doesn't fit, the agent asks instead of assuming, every time, and the fix for the one case where a human rejection quietly turned into an approval is baked into a permanent regression test now, not just a promise.

What we learned

The core lesson generalizes past this one hackathon: a probabilistic model and a trustworthy audit trail aren't in tension if you're disciplined about which one owns which job. The LLM gets to reason, phrase, and synthesize — it never gets to be the ledger. Once that boundary is enforced by code rather than by prompt instructions, you can let the model be genuinely useful without inheriting its unreliability.

The less glamorous lesson: cloud account setup, API quotas, and stray environment variables will eat as much of your hackathon time as your architecture will, and neither test suites nor self-generated status reports are a substitute for actually running the adversarial case yourself.

What's next for Vendor Clearance Agent

Wiring the clarification step to real email delivery instead of a bare API token, so a human can approve or reject an exception from their inbox with a single click. Getting a live, verified deployment on Cloud Run with the Gemini connection confirmed end-to-end under real billing (not the free tier). And, if there's time, letting the agent accept an actual contract PDF and use Gemini's multimodal capability to extract the structured proposal itself, instead of requiring clean JSON up front — turning this from "review a proposal someone already typed up" into "hand me the real, messy document and I'll take it from there."

Built With

• 3.11+
• python