How to Integrate Azure OpenAI for fintech with CosmosDB for startups

Combining Azure OpenAI with Cosmos DB gives you a practical pattern for fintech agents: the model handles language, classification, and summarization, while Cosmos DB stores customer profiles, transaction context, risk flags, and conversation state. For startups, this means you can build assistants that answer account questions, triage support tickets, detect suspicious activity patterns, and keep every interaction grounded in your own data.

Prerequisites

• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB account
• •Deployed Azure OpenAI model deployment name
  • •Example: gpt-4o-mini
• •Cosmos DB container created
  • •Database example: fintechdb
  • •Container example: agent_memory
• •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

Integration Steps

1. •Set up your clients

Create one client for Azure OpenAI and one for Cosmos DB. Keep credentials in environment variables and never hardcode them.

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

azure_openai_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 = 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. •Store fintech context in Cosmos DB

For an AI agent, the useful data is not just chat history. Store customer risk profile, recent transactions, case status, and any policy rules you want the model to respect.

from datetime import datetime

customer_context = {
    "id": "cust_1001",
    "customerId": "cust_1001",
    "partitionKey": "cust_1001",
    "name": "Amina Khan",
    "accountType": "business",
    "riskScore": 72,
    "recentTransactions": [
        {"amount": 1200, "currency": "USD", "merchant": "Cloud Hosting"},
        {"amount": 9800, "currency": "USD", "merchant": "Payroll Provider"}
    ],
    "lastUpdated": datetime.utcnow().isoformat()
}

container.upsert_item(customer_context)

3. •Retrieve context before calling Azure OpenAI

Pull the relevant record from Cosmos DB first. This keeps the model grounded in live operational data instead of guessing.

customer_id = "cust_1001"
context_item = container.read_item(
    item=customer_id,
    partition_key=customer_id
)

prompt = f"""
You are a fintech support assistant.
Use only the customer context below.

Customer Context:
{context_item}

Task:
Explain whether the recent activity looks normal or needs review.
Return a short answer and a risk note.
"""

4. •Call Azure OpenAI with retrieved data

Use the chat completions API to generate a response based on the stored context. This is the core retrieval-and-reasoning loop for your agent.

response = azure_openai_client.chat.completions.create(
    model=deployment_name,
    messages=[
        {"role": "system", "content": "You are a compliance-aware fintech assistant."},
        {"role": "user", "content": prompt}
    ],
    temperature=0.2,
)

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

5. •Write the model output back to Cosmos DB

Store the response so your agent has memory across sessions. In production, this also helps with auditability and human review.

agent_result = {
    "id": f"case_{customer_id}",
    "partitionKey": customer_id,
    "customerId": customer_id,
    "analysis": assistant_reply,
    "modelDeployment": deployment_name,
    "createdAt": datetime.utcnow().isoformat()
}

container.upsert_item(agent_result)

Testing the Integration

Run an end-to-end test that reads from Cosmos DB, sends context to Azure OpenAI, then writes back the result.

def run_fintech_agent_check(customer_id: str):
    item = container.read_item(item=customer_id, partition_key=customer_id)

    prompt = f"""
Customer profile:
{item}

Decide if this account should be reviewed by a human analyst.
Answer in two lines:
1) Decision
2) Reason
"""

    result = azure_openai_client.chat.completions.create(
        model=deployment_name,
        messages=[
            {"role": "system", "content": "You assess fintech risk using provided data only."},
            {"role": "user", "content": prompt}
        ],
        temperature=0.1,
    )

    text = result.choices[0].message.content

    container.upsert_item({
        "id": f"test_{customer_id}",
        "partitionKey": customer_id,
        "customerId": customer_id,
        "result": text
    })

    return text

print(run_fintech_agent_check("cust_1001"))

Expected output:

Decision: Review required by human analyst.
Reason: Recent high-value transactions plus elevated risk score warrant manual verification.

Real-World Use Cases

• •

  Fraud triage assistant

  • •Pull transaction history from Cosmos DB.
  • •Ask Azure OpenAI to summarize anomalies and produce a review note for analysts.
• •

  Customer support copilot

  • •Store conversation state and account metadata in Cosmos DB.
  • •Generate compliant responses for balance questions, payment issues, or onboarding flows.
• •

  KYC case summarizer

  • •Save document status, flags, and reviewer notes in Cosmos DB.
  • •Have Azure OpenAI turn messy case data into a clean summary for operations teams.

The pattern is simple: Cosmos DB holds state, Azure OpenAI reasons over it. For startups building fintech agents, that separation keeps your system auditable, scalable, and much easier to extend when requirements change.

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.