How to Integrate Azure OpenAI for healthcare with CosmosDB for startups

Azure OpenAI for healthcare gives you clinical-grade language understanding and generation. CosmosDB gives you low-latency, globally distributed state for your agent, so you can persist patient context, conversation history, and workflow events without bolting on a separate database later.

The useful pattern here is simple: use Azure OpenAI for healthcare to interpret medical text, summarize encounters, or draft patient-facing responses, then store structured outputs in CosmosDB so your agent can retrieve them across sessions. For startups building healthcare workflows, that means less glue code and a cleaner path from prototype to production.

Prerequisites

• •An Azure subscription with:
  • •Azure OpenAI resource deployed
  • •A model deployment name for your healthcare workload
• •A Cosmos DB account with:
  • •Database created
  • •Container created
  • •Partition key chosen, e.g. /patientId
• •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) Load configuration and initialize both clients

Keep credentials out of code. Use environment variables and initialize the Azure OpenAI client plus the Cosmos DB client at startup.

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

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_name = os.environ["COSMOS_DATABASE"]
container_name = os.environ["COSMOS_CONTAINER"]

database = cosmos_client.get_database_client(database_name)
container = database.get_container_client(container_name)

deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

2) Send clinical text to Azure OpenAI for structured extraction

For healthcare workflows, don’t ask the model for free-form prose if you need downstream automation. Ask for JSON-like output that your agent can store directly in Cosmos DB.

clinical_note = """
Patient reports intermittent chest pain for 3 days.
No shortness of breath. History of hypertension.
Vitals stable. Recommend ECG and follow-up.
"""

response = aoai_client.chat.completions.create(
    model=deployment_name,
    messages=[
        {
            "role": "system",
            "content": (
                "You are a healthcare assistant. Extract structured data from clinical notes "
                "and return concise JSON with fields: summary, symptoms, risks, next_steps."
            ),
        },
        {"role": "user", "content": clinical_note},
    ],
    temperature=0.2,
)

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

3) Persist the model output in Cosmos DB

Store the original note, extracted fields, and timestamps together. That gives your agent a durable record it can query later when a clinician or patient returns.

import json
from datetime import datetime, timezone

item = {
    "id": "encounter-001",
    "patientId": "patient-123",
    "createdAt": datetime.now(timezone.utc).isoformat(),
    "sourceNote": clinical_note,
    "modelOutput": extracted,
}

# If your model returns valid JSON text, parse it before storing.
try:
    item["structuredOutput"] = json.loads(extracted)
except json.JSONDecodeError:
    item["structuredOutput"] = {"raw": extracted}

container.upsert_item(item)
print("Saved encounter to Cosmos DB")

4) Retrieve patient context before calling the model again

This is where the integration becomes an agent system instead of isolated API calls. Pull prior encounters from Cosmos DB and feed them back into Azure OpenAI as context.

query = """
SELECT TOP 5 c.id, c.createdAt, c.modelOutput
FROM c
WHERE c.patientId = @patientId
ORDER BY c.createdAt DESC
"""

parameters = [{"name": "@patientId", "value": "patient-123"}]

items = list(
    container.query_items(
        query=query,
        parameters=parameters,
        enable_cross_partition_query=True,
    )
)

context_block = "\n".join(
    f"- {item['createdAt']} ({item['id']}): {item.get('modelOutput', '')}"
    for item in items
)

followup_response = aoai_client.chat.completions.create(
    model=deployment_name,
    messages=[
        {
            "role": "system",
            "content": (
                "You are assisting with a healthcare workflow. Use prior encounter history "
                "to produce a short follow-up summary."
            ),
        },
        {
            "role": "user",
            "content": f"Patient history:\n{context_block}\n\nWrite follow-up guidance.",
        },
    ],
)

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

5) Build an agent loop around both services

In production, wrap this into a single function that handles ingestion, storage, retrieval, and response generation. Keep the boundary clear: Azure OpenAI does reasoning; Cosmos DB does state.

def process_clinical_message(patient_id: str, note: str) -> dict:
    llm_response = aoai_client.chat.completions.create(
        model=deployment_name,
        messages=[
            {
                "role": "system",
                "content": (
                    "Extract summary, symptoms, risks, and next_steps as JSON."
                ),
            },
            {"role": "user", "content": note},
        ],
        temperature=0.2,
    )

    output_text = llm_response.choices[0].message.content

    record = {
        "id": f"{patient_id}-{datetime.now(timezone.utc).timestamp()}",
        "patientId": patient_id,
        "note": note,
        "outputText": output_text,
        "createdAt": datetime.now(timezone.utc).isoformat(),
    }

    try:
        record["structuredOutput"] = json.loads(output_text)
    except json.JSONDecodeError:
        record["structuredOutput"] = {"raw": output_text}

    container.upsert_item(record)
    return record


saved_record = process_clinical_message(
    patient_id="patient-123",
    note="Patient has fever and sore throat for two days. No known allergies.",
)
print(saved_record["id"])

Testing the Integration

Run a simple end-to-end check: generate an output from Azure OpenAI, write it to Cosmos DB, then read it back by patient ID.

test_patient_id = "patient-test-001"
test_note = "Patient reports mild headache after starting new medication."

saved = process_clinical_message(test_patient_id, test_note)

read_back_query = """
SELECT TOP 1 c.id, c.patientId, c.createdAt, c.outputText
FROM c
WHERE c.patientId = @patientId
ORDER BY c.createdAt DESC
"""

results = list(
    container.query_items(
        query=read_back_query,
        parameters=[{"name": "@patientId", "value": test_patient_id}],
        enable_cross_partition_query=True,
    )
)

print(results[0]["patientId"])
print(results[0]["id"])
print(results[0]["outputText"][:120])

Expected output:

patient-test-001
patient-test-001-1710000000.123456
{"summary":"...","symptoms":"...","risks":"...","next_steps":"..."}

Real-World Use Cases

• •

  Clinical intake triage

  • •Ingest symptom descriptions from chat or forms.
  • •Use Azure OpenAI to classify urgency.
  • •Store triage decisions in Cosmos DB for auditability.
• •

  Patient follow-up agents

  • •Retrieve prior encounters from Cosmos DB.
  • •Generate personalized follow-up instructions with Azure OpenAI.
  • •Persist every response for continuity across sessions.
• •

  Care coordination workflows

  • •Summarize lab notes or discharge instructions.
  • •Track task state in Cosmos DB.
  • •Let an agent decide what to send to clinicians versus patients based on stored context.

If you’re building this for a startup, keep one rule in mind: don’t let the model be your database. Let Azure OpenAI reason over healthcare text, then use Cosmos DB as the system of record for everything the agent needs to remember.

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.