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

Combining Azure OpenAI for insurance with Cosmos DB gives you a practical pattern for agent systems that need both reasoning and durable memory. In insurance workflows, that usually means: classify incoming claims, retrieve policy context, generate customer-safe responses, and persist every interaction for audit and follow-up.

The win is simple: Azure OpenAI handles language understanding and generation, while Cosmos DB stores structured state, conversation history, claim metadata, and agent decisions. That gives your AI agent a memory layer that survives restarts and supports traceability.

Prerequisites

• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB account
• •Deployed Azure OpenAI model:
  • •Example: gpt-4o-mini or another chat completion deployment
• •Cosmos DB database and container created
• •Python 3.10+
• •Installed packages:
  • •openai
  • •azure-cosmos
  • •python-dotenv
• •Environment variables set:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_ENDPOINT
  • •COSMOS_KEY
  • •COSMOS_DATABASE
  • •COSMOS_CONTAINER

Install the SDKs:

pip install openai azure-cosmos python-dotenv

Integration Steps

1) Initialize Azure OpenAI and Cosmos DB clients

Use the Azure OpenAI client for chat completions and the Cosmos client for persistence. Keep both clients in one module so your agent can read/write state around every model call.

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"],
    api_version="2024-06-01",
    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 prior insurance context from Cosmos DB

For an agent, memory should be explicit. Pull the current claim or customer conversation state from Cosmos before calling the model.

def get_agent_state(case_id: str) -> dict:
    try:
        return container.read_item(item=case_id, partition_key=case_id)
    except Exception:
        return {
            "id": case_id,
            "partitionKey": case_id,
            "messages": [],
            "claim_status": "new",
            "policy_type": None,
        }

case_id = "CLAIM-10027"
state = get_agent_state(case_id)
print(state["claim_status"])

3) Call Azure OpenAI to generate an insurance response

Pass the retrieved context into the chat completion request. For insurance use cases, keep prompts grounded in policy facts and avoid inventing coverage details.

def generate_response(state: dict, user_message: str) -> str:
    messages = [
        {
            "role": "system",
            "content": (
                "You are an insurance claims assistant. "
                "Use only the provided context. "
                "If coverage is unclear, ask for clarification."
            ),
        },
        {
            "role": "user",
            "content": f"""
Claim ID: {state['id']}
Claim status: {state['claim_status']}
Policy type: {state['policy_type']}

Customer message:
{user_message}
""".strip(),
        },
    ]

    response = azure_openai_client.chat.completions.create(
        model=deployment_name,
        messages=messages,
        temperature=0.2,
    )

    return response.choices[0].message.content

reply = generate_response(state, "Can you tell me if my windshield damage is covered?")
print(reply)

4) Persist the new agent turn back into Cosmos DB

After each model response, store both the user input and assistant output. This gives you traceability for compliance reviews and lets future turns reuse history.

from datetime import datetime, timezone

def save_turn(case_id: str, state: dict, user_message: str, assistant_reply: str):
    state["messages"].append({
        "ts": datetime.now(timezone.utc).isoformat(),
        "user": user_message,
        "assistant": assistant_reply,
    })

    state["updated_at"] = datetime.now(timezone.utc).isoformat()

    container.upsert_item(state)

save_turn(
    case_id=case_id,
    state=state,
    user_message="Can you tell me if my windshield damage is covered?",
    assistant_reply=reply,
)

5) Build a simple end-to-end agent loop

This is the pattern you want in production: read state, reason with Azure OpenAI, write back to Cosmos DB. You can wrap this in an API route or queue worker later.

def handle_claim_message(case_id: str, user_message: str) -> str:
    state = get_agent_state(case_id)
    assistant_reply = generate_response(state, user_message)
    save_turn(case_id, state, user_message, assistant_reply)
    return assistant_reply

result = handle_claim_message("CLAIM-10027", "I uploaded photos of the damage yesterday.")
print(result)

Testing the Integration

Run a quick smoke test against a known claim ID. You want to verify three things:

• •Cosmos DB returns or creates state
• •Azure OpenAI generates a response using that state
• •The updated record is written back successfully

if __name__ == "__main__":
    case_id = "CLAIM-TEST-001"
    message = "My policy number changed after renewal. Does that affect my claim?"

    answer = handle_claim_message(case_id, message)

    print("Assistant reply:")
    print(answer)

    saved = container.read_item(item=case_id, partition_key=case_id)
    print("\nStored turns:", len(saved["messages"]))

Expected output:

Assistant reply:
Your policy number change after renewal does not automatically affect your claim...
Stored turns: 1

If you get a stored turn count of 1 or higher and a coherent response from the model, the integration is working.

Real-World Use Cases

• •

  Claims triage agents

  • •Classify incoming claims by severity, line of business, and required documents.
  • •Store triage decisions in Cosmos DB so adjusters can review them later.
• •

  Policy Q&A assistants

  • •Answer customer questions about deductibles, exclusions, renewals, and coverage limits.
  • •Persist conversation history so the agent can continue across sessions without losing context.
• •

  Underwriting support agents

  • •Summarize applicant data, flag missing fields, and draft follow-up questions.
  • •Use Cosmos DB as the system of record for each underwriting case and its AI-generated notes.

This setup is small enough to ship quickly and strong enough to survive production requirements. Once this works end to end, add retries around both SDK calls, schema validation on stored items, and role-based access before exposing it to real policyholder data.

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.