How to Integrate Azure OpenAI for insurance with CosmosDB for multi-agent systems

Combining Azure OpenAI for insurance with CosmosDB gives you a clean pattern for agentic systems that need memory, policy context, and structured state. In practice, this lets one agent extract claim details, another validate coverage, and a third persist the decision trail in CosmosDB without losing context between turns.

For insurance workflows, that matters because the conversation is rarely stateless. You need durable storage for customer profiles, claims, underwriting notes, and agent handoffs, while Azure OpenAI handles classification, summarization, and next-step reasoning.

Prerequisites

• •An Azure subscription with:
  • •Azure OpenAI resource deployed
  • •A model deployment name for chat completions
• •An Azure Cosmos DB for NoSQL account
• •Python 3.10+
• •pip installed
• •Environment variables configured:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_ENDPOINT
  • •COSMOS_KEY
  • •COSMOS_DATABASE
  • •COSMOS_CONTAINER
• •Python packages:
  • •openai
  • •azure-cosmos
  • •python-dotenv

Install the dependencies:

pip install openai azure-cosmos python-dotenv

Integration Steps

1) Initialize Azure OpenAI and Cosmos DB clients

Use the Azure OpenAI client for generation and Cosmos DB for persistent agent memory. Keep both clients in a shared module so every agent can use the same connection layer.

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

load_dotenv()

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

deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

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

database_name = os.environ["COSMOS_DATABASE"]
container_name = os.environ["COSMOS_CONTAINER"]

2) Create the database and container for multi-agent state

For multi-agent systems, store one document per workflow instance. Use a stable partition key like caseId or claimId so all related agent messages stay together.

database = cosmos_client.create_database_if_not_exists(id=database_name)

container = database.create_container_if_not_exists(
    id=container_name,
    partition_key=PartitionKey(path="/caseId"),
    offer_throughput=400
)

print(f"Ready: {database_name}/{container_name}")

A good document shape looks like this:

case_document = {
    "id": "claim-10001",
    "caseId": "claim-10001",
    "customerId": "cust-7781",
    "status": "new",
    "summary": "",
    "agentHistory": [],
}

3) Call Azure OpenAI to extract insurance intent and entities

In insurance workflows, you usually want structured output before you write anything to storage. Ask the model to return JSON fields that downstream agents can consume.

import json

user_message = """
Customer says: I was rear-ended yesterday. My bumper is damaged.
Policy number is POL-88321. I want to file a claim.
"""

response = aoai_client.chat.completions.create(
    model=deployment_name,
    messages=[
        {"role": "system", "content": "Extract insurance claim details as JSON."},
        {"role": "user", "content": user_message}
    ],
    temperature=0
)

raw_text = response.choices[0].message.content
print(raw_text)

A production version should validate the JSON before using it. If you expect strict structure, define the schema in your prompt and reject malformed responses.

4) Persist the extracted result into Cosmos DB

Once you have structured data, save it as the shared memory layer for all agents. Each agent can append its own output to the same case document.

claim_data = {
    "id": "claim-10001",
    "caseId": "claim-10001",
    "customerId": "cust-7781",
    "status": "triaged",
    "summary": raw_text,
    "agentHistory": [
        {
            "agent": "intake-agent",
            "result": raw_text
        }
    ]
}

upserted_item = container.upsert_item(claim_data)
print("Upserted:", upserted_item["id"])

If you need updates from multiple agents, use optimistic concurrency patterns or make each agent write an append-only event record instead of overwriting the main case object.

5) Read case memory back into another agent prompt

This is where Cosmos DB becomes useful for multi-agent orchestration. One agent writes intake data, another reads it back and reasons over policy coverage or fraud indicators.

case_id = "claim-10001"

query = f"SELECT * FROM c WHERE c.caseId = '{case_id}'"
items = list(container.query_items(
    query=query,
    enable_cross_partition_query=True
))

case_state = items[0]
prompt_context = f"""
Case ID: {case_state['caseId']}
Customer ID: {case_state['customerId']}
Status: {case_state['status']}
Summary: {case_state['summary']}
"""

coverage_response = aoai_client.chat.completions.create(
    model=deployment_name,
    messages=[
        {"role": "system", "content": "You are a claims coverage assistant."},
        {"role": "user", "content": prompt_context}
    ],
    temperature=0.2
)

print(coverage_response.choices[0].message.content)

Testing the Integration

Run an end-to-end test that creates a claim record, stores model output, then reads it back for a second agent pass.

test_case_id = "claim-test-001"

container.upsert_item({
    "id": test_case_id,
    "caseId": test_case_id,
    "customerId": "cust-test",
    "status": "new",
    "summary": "",
    "agentHistory": []
})

test_prompt = """
Customer reports water damage in the kitchen after a pipe burst.
Policy number is POL-112233.
"""

extract_resp = aoai_client.chat.completions.create(
    model=deployment_name,
    messages=[
        {"role": "system", "content": "Return JSON with incident_type, policy_number, urgency."},
        {"role": "user", "content": test_prompt}
    ],
)

container.patch_item(
    item=test_case_id,
    partition_key=test_case_id,
    patch_operations=[
        {"op": "set", "path": "/summary", "value": extract_resp.choices[0].message.content},
        {"op": "set", "path": "/status", "value": "triaged"}
]
)

saved = container.read_item(item=test_case_id, partition_key=test_case_id)
print(saved["status"])
print(saved["summary"])

Expected output:

triaged
{"incident_type":"water_damage","policy_number":"POL-112233","urgency":"high"}

Real-World Use Cases

• •

  Claims intake + triage

  • •One agent extracts claim details from chat or email.
  • •Another agent checks policy context stored in Cosmos DB.
  • •A final agent drafts the next action for a human adjuster.
• •

  Underwriting support

  • •Store applicant history, prior decisions, and document references in Cosmos DB.
  • •Use Azure OpenAI to summarize risk signals and generate underwriting notes.
  • •Keep each step auditable across multiple agents.
• •

  Fraud review workflows

  • •One agent flags suspicious patterns from incoming claims.
  • •Another agent pulls related cases from Cosmos DB by customer or device ID.
  • •A supervisor agent generates escalation summaries for investigators.

The main pattern here is simple: use Azure OpenAI for reasoning and extraction, use Cosmos DB as durable shared memory. That separation keeps your multi-agent system easier to debug, easier to scale, and much safer to operate in regulated insurance workflows.

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.