SubroGate

Inspiration

Freight subrogation is a slow, manual reconciliation problem disguised as a paperwork problem. When cargo arrives damaged, the evidence needed to prove liability already exists — a gate receipt here, a temperature sensor log there — but it lives in disconnected formats nobody cross-checks in time. Adjusters end up eyeballing a PDF next to a spreadsheet and guessing at a timeline, while carriers default to boilerplate defenses because nobody called their bluff with hard numbers. We kept coming back to the same question: what if an agent could actually reconstruct the incident from raw evidence and tell you, with math, who's liable — instead of just helping someone type up the claim faster?

What it does

SubroGate ingests fragmented physical custody evidence (Equipment Interchange Receipts, Bills of Lading) alongside raw IoT sensor telemetry (temperature, shock, GPS), and fuses them into a single UTC timeline to determine exactly which party had custody of the cargo when it was damaged.

• A Document Intelligence Agent OCRs scanned receipts, validates container IDs with ISO 6346 checksums, and fingerprints every piece of evidence with SHA-256 for chain-of-custody integrity.
• A deterministic timeline engine — not an LLM guess — computes the overlap between custody handoffs and the earliest recorded sensor breach.
• An Investigator Agent synthesizes that into a liability assessment citing the Carmack Amendment (49 U.S.C. § 14706), with its reasoning attached, not hidden.
• Nothing reaches a carrier without a human adjuster reviewing and signing off with a cryptographic approval token.
• A Settlement Agent drafts a demand letter and anticipates the carrier's likely defenses, with every outbound draft screened by a Security Gate for PII, secrets, and prompt injection before it goes out.
• Every agent publishes itself to a versioned Agent Registry, so the whole fleet is discoverable and governable, not a black box.

How we built it

The backend is Python/FastAPI, using the Google GenAI SDK to call Gemini 3.5 Flash for extraction, synthesis, and drafting, while keeping the actual liability math — the custody/breach overlap calculation — deterministic Python, separate from the model. A registry of declarative, ADK-schema- compatible tools binds those deterministic functions to Gemini's function- calling, so the model can invoke exact statute lookups and checksum validation rather than generating them. Firestore is the memory bank for case and job state with optimistic locking; an in-process async worker handles long-running investigations so the UI doesn't block on multi-agent runs; and every request is traced end-to-end with OpenTelemetry into Cloud Trace. The frontend is React 19/TypeScript, and everything runs on Cloud Run as a single deployable service. The security screening layer can run entirely locally as a deterministic rule engine or route through the live Google Cloud Model Armor API when configured — same guardrail coverage either way, different backing engine.

Challenges we ran into

The hardest architectural decision was refusing to let the LLM decide liability directly. It's tempting to just hand the model the timeline and ask "who's at fault," but that's not defensible evidence — so we forced a split where the timestamp math is deterministic Python and the model's job is extraction and explanation, not judgment. We also learned partway through that naming things after a specific framework doesn't make the integration real: our tool registry is genuinely wired into every agent's function-calling and fully tested, but it's a custom implementation compatible with ADK's schema conventions, not the google-adk package itself — a distinction worth being precise about rather than blurring, even under deadline pressure.

Accomplishments that we're proud of

• A liability determination pipeline where the actual legal/evidentiary calculation is deterministic and auditable, with the LLM doing extraction and narrative synthesis around it — not the other way around.
• A mandatory human sign-off gate baked into the architecture from the start: no agent output reaches an external party without a logged human approval token.
• A security screening layer that catches sensitive content in outbound drafts before they leave the system, with a real fallback path between a local rule engine and live Google Cloud Model Armor.
• 120 automated tests across the agent, service, tool-registry, and API layers, giving us the confidence to keep refining the architecture right up against the deadline without breaking what already worked.

What we learned

That the differentiated, defensible part of this problem isn't "automate the claim filing" — several tools already do that — it's "establish who's actually liable, with evidence." Building for that meant resisting the urge to let the model do more than it should, and being deliberate about which parts of the pipeline need to be deterministic versus generative. We also learned to describe our own architecture precisely: it's easy to reach for a well-known framework's name because it signals credibility, but being exact about what's actually integrated versus what's schema-compatible matters more, especially to anyone who reads the code.

What's next for SubroGate

Moving the async investigation worker from an in-process thread pool to Cloud Tasks or Pub/Sub, so long-running jobs survive a Cloud Run scale-to-zero event rather than being tied to a single instance's lifetime. Fronting the service with a managed API gateway (Cloud API Gateway or Apigee) as the deployment grows past a single FastAPI ingress. And extending the Investigator Agent's citation set beyond the Carmack Amendment to cover international carriage regimes (e.g. the Hague-Visby Rules) so SubroGate can reason about cross-border freight disputes, not just domestic U.S. shipments.

Built With

• cloud-run
• cloud-trace
• fastapi
• firestore
• freight
• gemini
• gemini-3.5-flash
• google-cloud
• google-genai-sdk
• insurance-claims
• iot
• llm-agents
• logistics
• model-armor
• opentelemetry
• pydantic
• python
• react
• subrogation
• supply-chain
• typescript
• vertex-ai