How to Integrate Azure OpenAI for insurance with CosmosDB for production AI

Azure OpenAI gives you the language layer for insurance workflows: intake, triage, claims summaries, policy Q&A, and agent assist. CosmosDB gives you the durable memory layer: customer context, claim history, conversation state, and audit-friendly retrieval at production scale.

Put them together and you get an AI agent that can answer with policy-aware context instead of stateless guesses. That matters in insurance because every response needs to be grounded in customer records, claim data, and compliance constraints.

Prerequisites

• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB for NoSQL account
• •A deployed Azure OpenAI model, such as:
  • •gpt-4o-mini
  • •gpt-4.1-mini
• •A CosmosDB database and container created for agent memory
• •Python 3.10+
• •Installed packages:
  • •openai
  • •azure-cosmos
  • •python-dotenv
• •Environment variables configured:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_ENDPOINT
  • •COSMOS_KEY
  • •COSMOS_DATABASE
  • •COSMOS_CONTAINER

Install the dependencies:

pip install openai azure-cosmos python-dotenv

Integration Steps

1) Initialize both clients

Start by wiring up the Azure OpenAI client and the CosmosDB client in the same service. Keep credentials out of code and load them from environment variables.

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

load_dotenv()

azure_openai_client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-06-01"
)

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"]

This is the minimum production shape. One client generates responses, the other stores state you can retrieve later.

2) Store insurance context in CosmosDB

For insurance agents, you need structured context: policy number, claim ID, customer name, status, last interaction. Store that as a document so your model can answer with current facts.

from datetime import datetime, timezone

def upsert_claim_context(claim_id: str, customer_id: str, policy_number: str, status: str):
    item = {
        "id": claim_id,
        "customerId": customer_id,
        "policyNumber": policy_number,
        "claimStatus": status,
        "updatedAt": datetime.now(timezone.utc).isoformat(),
        "type": "claim_context"
    }
    container.upsert_item(item)
    return item

context = upsert_claim_context(
    claim_id="CLM-100245",
    customer_id="CUST-7781",
    policy_number="POL-442190",
    status="Under review"
)
print(context)

Use a stable partition key strategy here. In most insurance systems, customerId or policyNumber works better than random IDs because it keeps related records together.

3) Retrieve context before calling Azure OpenAI

Before generating a response, fetch the latest record from CosmosDB. This makes your agent grounded in real operational data instead of relying on prompt memory alone.

def get_claim_context(claim_id: str):
    query = """
    SELECT * FROM c
    WHERE c.id = @claim_id AND c.type = 'claim_context'
    """
    items = list(container.query_items(
        query=query,
        parameters=[{"name": "@claim_id", "value": claim_id}],
        enable_cross_partition_query=True
    ))
    return items[0] if items else None

claim_context = get_claim_context("CLM-100245")
print(claim_context)

If your use case needs conversation history too, store each message as a separate document with timestamps. That gives you replayable audit trails for regulated workflows.

4) Generate an insurance response with Azure OpenAI

Now pass the retrieved context into Azure OpenAI. The model should answer as an assistant operating on known policy facts.

def generate_claim_response(claim_context: dict, user_question: str):
    system_prompt = (
        "You are an insurance claims assistant. "
        "Answer only using the provided claim context. "
        "If data is missing, say what is missing."
    )

    user_prompt = f"""
Claim Context:
{claim_context}

Customer Question:
{user_question}
"""

    response = azure_openai_client.chat.completions.create(
        model=deployment_name,
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_prompt}
        ],
        temperature=0.2
    )

    return response.choices[0].message.content

answer = generate_claim_response(
    claim_context=claim_context,
    user_question="What is the current status of my claim?"
)
print(answer)

Keep temperature low for insurance workflows. You want consistent phrasing and fewer hallucinations when answering policy or claims questions.

5) Persist the interaction back to CosmosDB

After generating the answer, write it back to CosmosDB. This gives you traceability for compliance reviews and supports follow-up turns in the same agent session.

from uuid import uuid4

def save_interaction(customer_id: str, claim_id: str, question: str, answer: str):
    record = {
        "id": str(uuid4()),
        "customerId": customer_id,
        "claimId": claim_id,
        "type": "agent_interaction",
        "question": question,
        "answer": answer,
        "createdAt": datetime.now(timezone.utc).isoformat()
    }
    container.create_item(record)
    return record

interaction = save_interaction(
    customer_id="CUST-7781",
    claim_id="CLM-100245",
    question="What is the current status of my claim?",
    answer=answer
)
print(interaction["id"])

This closes the loop: retrieve context from CosmosDB, generate with Azure OpenAI, persist the result back to CosmosDB.

Testing the Integration

Run a simple end-to-end test that seeds a record, queries it back, generates a response, and saves the result.

test_claim = upsert_claim_context(
    claim_id="CLM-TEST-001",
    customer_id="CUST-TEST-9",
    policy_number="POL-TEST-77",
    status="Approved for payout"
)

loaded_claim = get_claim_context("CLM-TEST-001")
test_answer = generate_claim_response(
    loaded_claim,
    "Has my claim been approved?"
)

saved = save_interaction(
    customer_id="CUST-TEST-9",
    claim_id="CLM-TEST-001",
    question="Has my claim been approved?",
    answer=test_answer
)

print("Loaded:", loaded_claim["claimStatus"])
print("Answer:", test_answer)
print("Saved interaction:", saved["id"])

Expected output:

Loaded: Approved for payout
Answer: Your claim has been approved for payout based on the current claim context.
Saved interaction: 8f2d7a6e-bc5f-4f8f-a8b1-d3f2a5e9c123

If this fails in production first check:

• •Azure OpenAI deployment name matches exactly
• •API version is supported by your resource
• •CosmosDB partition key matches your document shape
• •The container has enough RU/s for query + write traffic

Real-World Use Cases

• •

  Claims triage agent

  • •Pulls current claim status from CosmosDB
  • •Uses Azure OpenAI to draft next-step guidance for adjusters or customers
• •

  Policy Q&A assistant

  • •Retrieves policy metadata and endorsements from CosmosDB
  • •Generates compliant answers about coverage limits, deductibles, and exclusions
• •

  Agent copilot

  • •Stores call notes and conversation history in CosmosDB
  • •Uses Azure OpenAI to summarize interactions and suggest follow-up actions

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.