agentic-insurance-agent is an open-source way to run insurance processes (policy issue, premium collection, claims) as diagrams and rules, with an AI layer that can recommend but not move money.
Open-source tools · How-to · Insurance process automation
How to use agentic-insurance-agent: open-source insurance workflows with safe AI
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/agentic-insurance-agent
Watch the walkthrough
Watch on YouTube: youtu.be/AS_eU0bt6lM
What it is for
Insurers often run policy, premium and claims work on commercial platforms such as Appian, Pega or Guidewire. This repo is an open-source version of the orchestration layer only. The process is drawn as BPMN diagrams, decision rules sit in DMN tables, and small Python workers do the steps. A SQLite ledger records policies, claims and payments.
On top sits a GenAI service in the ai/ folder: document reading, a triage agent that can call tools, guardrails (personal data, prompt injection, grounding), model routing, tracing and regression tests. The design rule is that the diagram owns the process, the AI only recommends, and the decision tables stay authoritative. The AI cannot pay a claim by itself.
The demo ran the test suites and the evaluation gate. It did not start the workflow engine or the Docker stack.
Who it is for
- Developers and architects exploring open-source alternatives to commercial workflow platforms
- Insurance and operations teams who want to see how AI can be added with an audit trail
- Students of process automation, rules engines and AI governance
- Production insurance operations. Several parts are placeholders (see limits)
- Replacing Appian, Pega or Guidewire connectors. The repo does not include their prebuilt insurance integrations
- Judging real model quality. The demo used a mock model
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3.12 or newer | pyproject.toml sets requires-python to 3.12 or above | python.org or brew install python@3.12 |
| Python packages | requirements-dev.txt lists fastapi, uvicorn, pydantic, httpx, pytest, psycopg[binary] and numpy | pip install -r requirements-dev.txt inside a virtual environment |
| Docker or Podman | only to run the full workflow engine (Operaton) with docker compose | Not needed for the tests or the mock evals. The engine was not started in the demo |
| Cloud model keys | optional: AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, AZURE_DEPLOY_SMALL, AZURE_DEPLOY_LARGE, or ANTHROPIC_API_KEY for real models | Leave them unset and use AI_PROVIDER=mock. The real-model adapters are written but have never been called live |
| Disk and RAM | small for the tests; the engine container needs more | A normal laptop is enough for the tests |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/agentic-insurance-agent.git
cd agentic-insurance-agent
claude # or: geminiInstall
- Clone the repo.
git clone https://github.com/herrrickshaw/agentic-insurance-agent.git cd agentic-insurance-agent - Create a virtual environment and install the dev requirements. The README's own worker test uses pytest, which is in this file, so install it before running that test.
python3 -m venv .venv .venv/bin/pip install -r requirements-dev.txt - Optional: start the workflow engine and demo. This was documented but not run in the demo. Short timers let you see the due-date and grace branches quickly.
DUE_IN=PT2M GRACE_IN=PT2M PAYOUT_SLA=PT2M docker compose up --build python3 scripts/demo.py
Quick start: commands and what you should see
Run the worker logic tests.
.venv/bin/python -I -m pytest -v tests/test_handlers.py3 passed in about 0.6 seconds. The README says python3 -I tests/test_handlers.py, but on a system Python without pytest that fails with ModuleNotFoundError. Using the virtual environment works.
Run the AI service tests.
.venv/bin/python -m pytest -v ai/tests16 passed in about 3.6 seconds (10 in test_ai.py and 6 in test_governance_fairness.py). The README still says 8 tests, so it is out of date.
Run the regression evals on the mock provider.
AI_PROVIDER=mock .venv/bin/python -m ai.evals.run_evalsA JSON report. Classification accuracy, field exact match, injection recall, adversarial issue recall and triage route accuracy all show 1.0, with no failures, and the command exits 0. It exits 1 if a score drops below its threshold.
Ways to use it
| Method | How it works |
|---|---|
| Open the models | The BPMN and DMN files in models/ open in bpmn.io or Camunda Modeler. They include policy_issuance, premium_collection and claim_handling, plus customer_onboarding, portfolio_risk_review and records_migration. |
| Run the engine | docker compose (or podman compose) starts Operaton, a Camunda 7 fork, with Tasklist and Cockpit at http://localhost:8080/camunda/app/. Not run in the demo. |
| AI service | The ai/ folder is an async FastAPI service on port 8090 that the claims process calls. Use AI_PROVIDER=mock to run it without keys. |
| Python library | Import the workers, ledger and ai modules in your own code. The tests show how. |
| Through an AI assistant | Open the folder in Claude Code or Gemini CLI. docs/CAPABILITY_MAP.md is a good first file to hand it. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Read README.md and docs/CAPABILITY_MAP.md and explain in plain English what is verified, what is mock-only and what is a gap.
- Set up the virtual environment and run the worker tests, the AI tests and the mock evals. Tell me what each result means.
- Show me the claim_handling process in models/ step by step. Where does the AI recommend, and where does a decision table decide?
- I run [my type of insurance]. Which parts of this repo would I need to change in the DMN tables and the ledger? Do not edit anything yet.
- Explain the guardrails in ai/guardrails.py for personal data, prompt injection and grounding, with one example each.
- List the limits of the 100% eval scores and suggest how I could build a harder test set from my own claims.
Limits and honest caveats
- The 100% eval scores prove that the test harness works, not that a model is good. The mock model was tuned on its own golden set.
- Azure OpenAI, OpenAI and Anthropic adapters are written but were never called live. Agent frameworks such as LangGraph are listed as a gap, and CI pipelines were not run.
- The timer, lapse and escalation branches have not yet been exercised on the engine.
- Engine state is not durable: it runs on embedded H2, and the Postgres environment variables did not switch it.
- No authentication on the engine REST interface. The fraud score is a placeholder. There is a single annual premium, and documents and notifications are log stubs.
- Actuarial maths uses an illustrative mortality table and synthetic data (docs/ACTUARIAL_AND_PORTFOLIO.md).
- The repo is the open-source equivalent of the orchestration layer only, not of the commercial vendors' prebuilt insurance connectors.
- The demo did not start the Docker and Operaton stack, so everything about the live engine comes from the README, which reports a verified live run on 2026-10-16.
Sources: the agentic-insurance-agent README, requirements-dev.txt, pyproject.toml and docs/CAPABILITY_MAP.md, and the demo run of 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
