Incident Ledger

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Incident Ledger

Inspiration

Operational incidents compress time and increase uncertainty. Many AI assistants produce polished conclusions without making it clear which statements came from evidence, inference, or assumption. We built Incident Ledger to explore a stricter pattern: agents may accelerate investigation, but evidence and human authority must remain visible.

What it does

Incident Ledger investigates a fully synthetic operational incident with three specialist agents running in sequence: a signal analyst, an evidence verifier, and a runbook planner. A fourth agent synthesizes their reports.

The initial Google ADK message contains only a synthetic:// manifest URI. The specialists receive two explicit read-only tools that list and retrieve validated synthetic telemetry; non-synthetic and unknown URIs are rejected.

The service returns structured agent reports, evidence-ledger verdicts, cited evidence IDs, and advisory proposals. It has no production mutation tool. Read-only checks may be PROPOSED, while every state-changing proposal is returned as REQUIRES_HUMAN_APPROVAL.

How we built it

• FastAPI on Google Cloud Run validates the synthetic incident and creates an isolated telemetry store.
• Google ADK SequentialAgent runs three specialist LlmAgents followed by a fourth synthesis agent.
• Gemini 3.5 Flash runs through Vertex AI in JSON mode. The generated JSON is parsed and strictly validated with Pydantic before it can become an API response.
• A post-generation safety guard removes unknown evidence references, redacts non-synthetic targets, and forces state-changing proposals behind human approval.
• Both the ADK and deterministic modes return the same strict AnalysisResult API contract, although they reach it through different internal validation paths.
• Firestore stores application-level, create-only audit events. Events are sequenced and SHA-256 linked within each analysis; Firestore transactions also enforce shared public-demo run limits.
• Next.js, React, TypeScript, and OpenAI Sites provide the judge-facing workspace.

Challenges we ran into

The hardest problem was preserving the same visible safety semantics across a live model-backed run and a no-credential fallback.

We changed the specialist workflow from parallel execution to a bounded sequence to avoid burst concurrency while preserving role separation. We also replaced a complex Vertex response schema with Gemini JSON mode followed by local SynthesisPayload validation. This kept the provider request compatible without weakening the final contract.

Another challenge was making fallback behavior honest. A result is labeled google_adk only after required telemetry access succeeds and the synthesized payload validates. If the public API, provider, or run allowance is unavailable, the interface switches to an explicitly labeled browser-only deterministic replay.

Accomplishments that we're proud of

• Three role-separated specialists and a fourth synthesis agent run through a real Google ADK workflow.
• The model never receives the incident JSON directly; telemetry remains behind explicit read-only tools.
• Unknown and non-synthetic telemetry URIs are rejected.
• Evidence-ledger entries expose verdicts and evidence IDs, while unknown references are removed before an ADK result is returned.
• The public demo is connected to a cost-capped Cloud Run and Vertex AI deployment without requiring judges to provide credentials.
• The interface preserves the actual google_adk or deterministic_demo execution mode.
• Firestore records create-only, per-analysis hash-linked audit events.
• No private operational data or production-changing tools are included.

Data sources and project provenance

The only incident data is synthetic telemetry committed to the public repository and exposed to the agents through allowlisted synthetic:// read-only tools. This project and repository were created during the contest submission period. It uses the open-source dependencies listed in the repository; OpenAI Codex was used as an allowed AI coding assistant for implementation support and review.

What we learned

Human-in-the-loop is not a confirmation button added at the end. It affects tool design, output contracts, audit structure, and what the interface must communicate before any decision.

The browser's "review evidence" control is deliberately local and non-persistent: it creates no approval, authorization, audit event, or production action. This distinction proved as important as the model workflow itself.

We also learned that reliable structured AI systems need both provider-level formatting and application-level validation. JSON mode improves generation consistency; strict local validation and safety enforcement establish the actual boundary.

What's next

The next step would add tenant-authorized, read-only operational connectors, persistent approval workflows, incident replay evaluations, and signed or externally anchored audit records. Any state-changing connector would remain a separate, explicitly authorized system boundary rather than being added to the investigation agents.

Built With

• docker
• fastapi
• firestore
• gemini-3-5-flash
• github-actions
• google-adk
• google-cloud-build
• google-cloud-run
• next-js
• openai-sites
• pydantic
• python
• react
• typescript
• vertex-ai