How to Integrate Azure OpenAI for insurance with CosmosDB for startups

Azure OpenAI gives you the reasoning layer for insurance workflows: claim triage, policy Q&A, fraud flagging, and document extraction. Cosmos DB gives you the durable state layer: customer profiles, claim history, conversation memory, and audit trails. Put them together and you can build an AI agent that answers policy questions with context, stores every interaction, and keeps working across sessions.

Prerequisites

• •Python 3.10+
• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB for NoSQL account
• •Deployed Azure OpenAI model:
  • •Example: gpt-4o-mini or gpt-4.1-mini
• •Cosmos DB database and container created
  • •Partition key example: /customerId
• •Environment variables set:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_ENDPOINT
  • •COSMOS_KEY
  • •COSMOS_DATABASE
  • •COSMOS_CONTAINER
• •Python packages installed:
  • •azure-openai
  • •azure-cosmos
  • •python-dotenv

pip install azure-openai azure-cosmos python-dotenv

Integration Steps

1. •Set up your clients.

You want two clients in the same service boundary: one for inference, one for persistence. Keep them isolated so you can swap models or storage without touching business logic.

import os
from dotenv import load_dotenv
from azure.cosmos import CosmosClient
from openai import AzureOpenAI

load_dotenv()

aoai_client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-02-15-preview",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
)

cosmos_client = CosmosClient(
    url=os.environ["COSMOS_ENDPOINT"],
    credential=os.environ["COSMOS_KEY"]
)

database = cosmos_client.get_database_client(os.environ["COSMOS_DATABASE"])
container = database.get_container_client(os.environ["COSMOS_CONTAINER"])
deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

2. •Load customer context from Cosmos DB.

For insurance agents, context matters. Pull the customer record first so the model can answer based on known policy details instead of hallucinating from a generic prompt.

def get_customer_context(customer_id: str) -> dict:
    query = """
    SELECT * FROM c
    WHERE c.customerId = @customerId
    """
    items = list(container.query_items(
        query=query,
        parameters=[{"name": "@customerId", "value": customer_id}],
        enable_cross_partition_query=True
    ))
    return items[0] if items else {}

customer = get_customer_context("cust-1001")
print(customer)

3. •Send the insurance question to Azure OpenAI with retrieved context.

Use a system message that constrains the assistant to insurance domain behavior. Then inject only the fields you need from Cosmos DB.

def answer_insurance_question(customer_id: str, question: str) -> str:
    customer = get_customer_context(customer_id)

    messages = [
        {
            "role": "system",
            "content": (
                "You are an insurance assistant. "
                "Answer using only the provided customer context and general insurance knowledge. "
                "If data is missing, say what is missing."
            )
        },
        {
            "role": "user",
            "content": f"""
Customer context:
{customer}

Question:
{question}
"""
        }
    ]

    response = aoai_client.chat.completions.create(
        model=deployment_name,
        messages=messages,
        temperature=0.2,
        max_tokens=300,
    )

    return response.choices[0].message.content

print(answer_insurance_question("cust-1001", "Is my motor policy active?"))

4. •Store the conversation result back into Cosmos DB.

This is where startup systems usually fail: they answer once and forget everything. Persist both user input and model output so your agent can resume a thread later, support audits, and feed downstream workflows.

from datetime import datetime

def save_interaction(customer_id: str, question: str, answer: str):
    item = {
        "id": f"{customer_id}-{datetime.utcnow().isoformat()}",
        "customerId": customer_id,
        "question": question,
        "answer": answer,
        "createdAt": datetime.utcnow().isoformat(),
        "type": "insurance_chat"
    }
    container.upsert_item(item)
    return item

customer_id = "cust-1001"
question = "Do I have coverage for windshield damage?"
answer = answer_insurance_question(customer_id, question)
record = save_interaction(customer_id, question, answer)

print(record["id"])

5. •Wrap it in a simple agent function.

This is the production shape you want: fetch state, reason with Azure OpenAI, persist output. Keep it boring and deterministic.

def handle_agent_request(customer_id: str, question: str) -> dict:
    answer = answer_insurance_question(customer_id, question)
    saved = save_interaction(customer_id, question, answer)

    return {
        "customerId": customer_id,
        "answer": answer,
        "savedRecordId": saved["id"]
    }

result = handle_agent_request("cust-1001", "What is my deductible?")
print(result)

Testing the Integration

Run a single end-to-end test against a known customer record. You should see a grounded answer plus a saved document ID from Cosmos DB.

if __name__ == "__main__":
    test_customer_id = "cust-1001"
    test_question = "Is my home policy active and what is my deductible?"

    result = handle_agent_request(test_customer_id, test_question)
    print("ANSWER:", result["answer"])
    print("SAVED:", result["savedRecordId"])

Expected output:

ANSWER: Your home policy appears to be active. Your deductible is $1,000 based on the stored policy record.
SAVED: cust-1001-2026-04-21T10:15:30.123456

If you get an empty customer context, check:

• •The partition key matches your query pattern.
• •The document has a customerId field.
• •Your Azure OpenAI deployment name matches the deployed model name.
• •Your endpoint/API key are valid.

Real-World Use Cases

• •

  Claims intake agent

  • •Collects claim details through chat
  • •Stores structured claim notes in Cosmos DB
  • •Uses Azure OpenAI to classify severity and route to the right team
• •

  Policy servicing assistant

  • •Answers coverage questions using customer-specific records
  • •Persists every interaction for compliance review
  • •Pulls prior conversations to maintain continuity
• •

  Fraud triage workflow

  • •Summarizes suspicious claim patterns from stored history
  • •Flags anomalies with an LLM prompt chain
  • •Writes risk scores back into Cosmos DB for downstream rules engines

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.