How to Integrate Azure OpenAI for wealth management with CosmosDB for production AI

Combining Azure OpenAI with Cosmos DB gives you a clean production pattern for wealth management agents: the model handles client-facing reasoning, while Cosmos DB stores portfolios, suitability data, interaction history, and audit trails. That split matters when you need retrieval, traceability, and low-latency access to structured client data without stuffing everything into prompts.

Prerequisites

• •Python 3.10+
• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB account
• •A deployed Azure OpenAI chat model, such as gpt-4o-mini or gpt-4.1
• •A Cosmos DB database and container for client records
• •Environment variables set:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_API_VERSION
  • •AZURE_OPENAI_DEPLOYMENT_NAME
  • •COSMOS_ENDPOINT
  • •COSMOS_KEY
  • •COSMOS_DATABASE_NAME
  • •COSMOS_CONTAINER_NAME

Install the SDKs:

pip install openai azure-cosmos python-dotenv

Integration Steps

1. •Set up your clients and load configuration.

Use the Azure OpenAI SDK for chat completions and the Cosmos DB Python SDK for document access.

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=os.environ["AZURE_OPENAI_API_VERSION"],
    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_NAME"])
container = database.get_container_client(os.environ["COSMOS_CONTAINER_NAME"])
deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"]

2. •Fetch client context from Cosmos DB.

In wealth management, you usually want portfolio facts, risk profile, and recent interactions before calling the model.

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

client_profile = get_client_profile("client-1001")
print(client_profile)

A typical document might include:

{
  "id": "client-1001",
  "clientId": "client-1001",
  "riskTolerance": "moderate",
  "portfolioValue": 1250000,
  "holdings": ["MSFT", "BND", "VTI"],
  "lastReviewDate": "2026-03-15"
}

3. •Build a wealth-management prompt from the stored data.

Keep the prompt structured. Don’t dump raw JSON without context; shape it into a short briefing the model can use.

def build_prompt(profile: dict, user_question: str) -> list:
    system_message = (
        "You are a wealth management assistant. "
        "Use only the provided client context. "
        "If data is missing, say what is missing and ask for it."
    )

    context_message = f"""
Client ID: {profile.get("clientId")}
Risk tolerance: {profile.get("riskTolerance")}
Portfolio value: {profile.get("portfolioValue")}
Holdings: {profile.get("holdings")}
Last review date: {profile.get("lastReviewDate")}
"""

    return [
        {"role": "system", "content": system_message},
        {"role": "user", "content": f"Client context:\n{context_message}\n\nQuestion:\n{user_question}"},
    ]

4. •Call Azure OpenAI and write the response back to Cosmos DB.

This gives you persistence for auditability, which is non-negotiable in financial workflows.

from datetime import datetime, timezone

def generate_advice_and_store(client_id: str, user_question: str) -> str:
    profile = get_client_profile(client_id)
    messages = build_prompt(profile, user_question)

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

    answer = response.choices[0].message.content

    record = {
        "id": f"{client_id}-{datetime.now(timezone.utc).isoformat()}",
        "clientId": client_id,
        "question": user_question,
        "answer": answer,
        "createdAt": datetime.now(timezone.utc).isoformat(),
        "source": "azure-openai",
    }

    container.upsert_item(record)
    return answer

result = generate_advice_and_store(
    client_id="client-1001",
    user_question="Should we rebalance toward bonds given current risk tolerance?"
)

print(result)

5. •Add a retrieval pattern for follow-up questions.

For production agents, you need conversation state and prior recommendations stored in Cosmos DB so each turn has memory without relying on a long prompt window.

def get_recent_interactions(client_id: str, limit: int = 5) -> list[dict]:
    query = """
    SELECT TOP @limit * FROM c
    WHERE c.clientId = @client_id AND IS_DEFINED(c.question)
    ORDER BY c.createdAt DESC
    """
    return list(container.query_items(
        query=query,
        parameters=[
            {"name": "@client_id", "value": client_id},
            {"name": "@limit", "value": limit},
        ],
        enable_cross_partition_query=True,
    ))

history = get_recent_interactions("client-1001")
for item in history:
    print(item["createdAt"], item["question"])

Testing the Integration

Run a smoke test that reads from Cosmos DB, calls Azure OpenAI, and persists the result.

if __name__ == "__main__":
    output = generate_advice_and_store(
        client_id="client-1001",
        user_question="Summarize whether this portfolio is aligned with moderate risk tolerance."
    )
    print("Model output:")
    print(output)

    saved_items = get_recent_interactions("client-1001", limit=1)
    print("\nLatest stored record:")
    print(saved_items[0]["id"])

Expected output:

Model output:
The portfolio appears broadly aligned with moderate risk tolerance...
Latest stored record:
client-1001-2026-04-21T10:15:30.123456+00:00

Real-World Use Cases

• •

  Suitability-aware portfolio assistants

  • •Pull risk profile and holdings from Cosmos DB.
  • •Ask Azure OpenAI to explain rebalancing options in plain language.
  • •Store every recommendation for compliance review.
• •

  Advisor copilot

  • •Retrieve meeting notes, prior advice, and product preferences from Cosmos DB.
  • •Generate next-best-action suggestions before advisor calls.
  • •Keep an immutable interaction trail for audits.
• •

  Client service automation

  • •Answer questions about performance summaries, contribution history, or account changes.
  • •Use Cosmos DB as the source of truth.
  • •Use Azure OpenAI to produce concise responses that match firm policy.

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.