A cikk egy gyakorlati útmutatót ismertet, amelyben egy hangalapú első kárbejelentés (FNOL, first notice of loss) alkalmazást építenek. A cél: a kárbejelentő természetes módon elmondja a történetet, a rendszer pedig élőben összegyűjti a strukturált adatokat, megjeleníti a leiratot, kigyűjti a hiányzó tételeket, osztályozza a bejelentést, és egy kárfelvevő-átadáshoz alkalmas Markdown csomagot generál.
A technikai hátteret Google ADK adja a munkafolyamat-graph kezeléséhez, Gemini Live szolgáltatja a valós idejű hangcsatornát, a döntési szabályokat determinisztikus Python függvények valósítják meg, és Pydantic sémák rögzítik az adatkontraktusokat.
Mit építünk
Az alkalmazás fő jellemzői:
- A bejelentő beszélhet vagy gépelhet.
- A válaszok valós időben, Gemini Live-on keresztül hangban is visszaáramlanak.
- A rendszer Pydantic sémákba kinyeri a strukturált káradatokat.
- A bejelentés típusa és súlyossága automatikusan osztályozódik.
- Determinisztikus szabályok jelzik a hiányzó mezőket, kötelező dokumentumokat, csalás- és biztonsági kockázatokat.
- A hívás közben Markdown formátumú, kárfelvevőnek szánt átadócsomag épül.
- Az alkalmazás nem ígér fedezetet, kifizetést vagy felelősséget.
Hogyan működik (röviden)
Minden bejelentői szöveg- vagy hangfordulatnál a háttérben a következő lépések történnek:
- Hallgatás: a hang leiratolódik és a szöveg bemenetként érkezik.
- Feldolgozás: Gemini elemzi a teljes eddigi beszélgetést, és kinyeri a strukturált tényeket (név, kötvényszám, dátum, hely, mi történt, bizonyítékok, sérülések).
- Osztályozás: Gemini meghatározza a kár típusát és a várható súlyosságot.
- Szabályalkalmazás: Python függvények ellenőrzik a kötelező mezőket, szükséges dokumentumokat, csalás- és biztonsági jeleket.
- Routing döntés: a rendszer egy négy irány egyikébe sorolja az ügyet: ready_for_adjuster, needs_docs, special_investigation vagy emergency_escalation; sérülés vagy veszély mindig felülírja a többit.
- Csomagépítés: létrejön a Markdown átadócsomag és a következő, kárbejelentőnek szánt mondat.
- UI frissítése: a mezők, idővonal és csomag a böngészőben frissül; az ügynök visszaszól.
Az ötlet lényege a munkamegosztás: Gemini kezeli a szabad, kaotikus emberi nyelvet; Python a determinisztikus, ismételhető döntéseket.
Követelmények
A leírás szerint előkészítésként szükségesek:
- Telepített Python (ajánlott: 3.12).
- Gemini API kulcs (Google AI Studio).
- Kódszerkesztő, alapvető Python/FastAPI/async ismeret.
- Böngésző mikrofon-hozzáféréssel.
Forráskód és projektfelépítés
A projekt klónozható az example repository-ból:
git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
A releváns mappa:
awesome-llm-apps/voice_ai_agents/insurance_claim_live_agent_team
Fájlok és szerepük:
- init.py — exportálja a root_agentet az ADK CLI-nek.
- agent.py — az ADK graph és a run_claim_workflow híd.
- schemas.py — Pydantic adatkontraktusok (például ClaimNarrative).
- policies.py — determinisztikus biztosítási szabályok.
- examples.py — demo bejelentői példák.
- live_demo/ — FastAPI szerver és egyszerű frontend (server.py, index.html, styles.css, app.js).
- requirements.txt, .env.example, README.md
A frontend statikus, három végpontot és egy WebSocketet használ: /api/message, /api/audio és /ws/live. Ezeket bármi mással helyettesíthetjük, ha a három interfészt megtartjuk.
Fontos részletek a sémákról és szabályokról
A ClaimNarrative Pydantic modell például tartalmaz olyan mezőket, mint policyholder_name, policy_number, contact_method, date_of_loss, loss_location, loss_description, estimated_loss_usd, injuries_or_safety_concerns, evidence_available és documents_mentioned.
A policies.py fájl öt nyilvános függvényt tartalmaz, amelyek bemeneti strukturált objektumokra épülnek és strukturált kimenetet adnak vissza: validate_required_claim_fields, apply_coverage_and_evidence_rules, generate_document_checklist, fraud_signal_and_safety_gate és build_claim_intake_packet. A TYPE_REQUIRED_DOCS egyértelműen mappázza a szükséges dokumentumokat kártípusonként (például home_water_damage, auto_collision stb.). A fraud_signal_and_safety_gate kiemelten kezeli a sérülésre vagy veszélyre utaló említéseket: ilyenkor emergency_escalation a routing.
ADK graph és a munkafolyamat
A munkafolyamat egy SequentialAgent, hét lépéses: LLM és Python csomópontok váltakoznak. Az LlmAgent csomópontok Pydantic output_schema-t használnak (ez biztosítja a strukturált LLM-kimenetet), a Python csomópontok FunctionNode-ok, amelyek a policies.py függvényeit hívják. A graphot a root_agent exportálja.
A run_claim_workflow függvény kis felületen keresztül indítja el a munkát: session létrehozása InMemorySessionService-szel, Runner inicializálása, és az aszinkron futtatás, miközben a bejelentői leiratot üzenetként átadja. A végső státuszt a session.state-ból olvassa vissza és Pydantic-validálja.
FastAPI szerver és valós idejű hang
A live_demo/server.py a frontend kiszolgálásáért, a session-kezelésért és a bemenetek továbbításáért felel. A híd (_process_with_adk_graph) meghívja a run_claim_workflow-ot; ha kell, a session.transcript-hez hozzáadja az ügynök kérdését a claim_intake_packet.claimant_next_message mezőből.
A /ws/live WebSocket esetén a graph futása külön aszinkron feladatban zajlik (asyncio.create_task), így az audio folyamatosan streamelhető vissza Gemini Live-on, miközben a strukturált csomag később aktualizálódik.
Példák és tesztelés
Az examples.py öt mintát ad: pinceáradás, baleset sérüléssel, eltűnt laptop rendőrségi jelentés nélkül, utazás-lemondás és egy szándékosan homályos bejelentés. Ezek hasznosak az adk web és a szabályok ellenőrzésére.
Indítási lépések (lokális futtatás)
- Telepítse a dependency-ket: pip install -r requirements.txt
- Másolja a .env fájlt és töltse ki a GOOGLE_API_KEY-t illetve a Gemini kulcsot: cp .env.example .env
- Indítsa a backendet és frontendet egy parancsból:
python -m uvicorn live_demo.server:app --reload --host 127.0.0.1 --port 4177
- Nyissa meg: http://127.0.0.1:4177/index.html, kattintson a mikrofonra, vagy gépeljen be egy bejelentést, és figyelje, hogyan töltődik ki a jobb panel.
Következtetés és továbbfejlesztési lehetőségek
A bemutató megvalósítja a hibátlan szerepelosztást: sémák a szerződésként, szabályok determinisztikus döntésekre, az ADK graph a munkafolyamat, és FastAPI csak szállítóként működik. A javasolt további irányok:
- új kártípusok hozzáadása;
- beszélgetések perzisztálása a backend újraindítása esetén;
- csalás- és biztonsági jelek kiterjesztése;
- a végső csomag bekötése valós kárkezelő rendszerekbe vagy CRM-be;
- értékelési készlet építése a promptok és szabályok regressziójának elkapására.
A hibrid LLM-plus-rules minta az insurance FNOL-on túl is általánosítható, érdemes a koncepciót más alkalmazásokban is kipróbálni.
