How to Integrate Azure OpenAI for lending with CosmosDB for startups

Combining Azure OpenAI for lending with Cosmos DB gives you a practical pattern for building loan decisioning agents that can reason over customer data, generate explanations, and persist every interaction. For startups, this means you can move from brittle rule engines to an AI-assisted workflow that pulls borrower history from Cosmos DB, runs a lending prompt through Azure OpenAI, and stores the decision trail for audit and review.

Prerequisites

• •Python 3.10+
• •An Azure subscription
• •An Azure OpenAI resource with:
  • •a deployed chat model name
  • •endpoint
  • •API key
• •An Azure Cosmos DB account with:
  • •database name
  • •container name
  • •endpoint
  • •key
• •pip installed
• •Environment variables set:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_DB_ENDPOINT
  • •COSMOS_DB_KEY
  • •COSMOS_DB_DATABASE
  • •COSMOS_DB_CONTAINER

Install the SDKs:

pip install openai azure-cosmos python-dotenv

Integration Steps

1. •Set up your clients and load configuration.

Use environment variables so you are not hardcoding secrets in your agent service.

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

load_dotenv()

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_DB_ENDPOINT"],
    credential=os.environ["COSMOS_DB_KEY"]
)

database_name = os.environ["COSMOS_DB_DATABASE"]
container_name = os.environ["COSMOS_DB_CONTAINER"]

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

2. •Create a container schema for lending records.

For startup workflows, keep one container for borrower profiles and another for decision logs if you need stricter separation. A simple partition key like /customerId works well for point reads.

from azure.cosmos.exceptions import CosmosResourceExistsError

try:
    database.create_container_if_not_exists(
        id=container_name,
        partition_key=PartitionKey(path="/customerId"),
        offer_throughput=400
    )
except CosmosResourceExistsError:
    pass

container = database.get_container_client(container_name)

3. •Read borrower data from Cosmos DB and build the lending prompt.

This is where the integration becomes useful. Pull structured fields from Cosmos DB, then pass them into Azure OpenAI as context for a credit memo or underwriting summary.

customer_id = "cust_1001"

borrower = container.read_item(
    item=customer_id,
    partition_key=customer_id
)

prompt = f"""
You are a lending assistant.
Assess this borrower profile and return:
1. risk level: low/medium/high
2. approval recommendation: approve/decline/review
3. short explanation

Borrower data:
- customerId: {borrower['customerId']}
- annualIncome: {borrower['annualIncome']}
- monthlyDebt: {borrower['monthlyDebt']}
- creditScore: {borrower['creditScore']}
- employmentYears: {borrower['employmentYears']}
- existingDelinquencies: {borrower['existingDelinquencies']}
"""

4. •Call Azure OpenAI to generate the lending recommendation.

Use the chat completions API through the Azure OpenAI client. Keep the output structured so your agent can store it and route it downstream.

response = azure_openai_client.chat.completions.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    messages=[
        {"role": "system", "content": "You produce concise lending decisions in JSON."},
        {"role": "user", "content": prompt}
    ],
    temperature=0.2,
)

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

5. •Persist the decision back into Cosmos DB.

Store both the raw model output and metadata about the request. That gives you traceability for compliance reviews and future model tuning.

from datetime import datetime, timezone

decision_record = {
    "id": f"decision_{customer_id}_{datetime.now(timezone.utc).timestamp()}",
    "customerId": customer_id,
    "createdAt": datetime.now(timezone.utc).isoformat(),
    "model": os.environ["AZURE_OPENAI_DEPLOYMENT"],
    "inputSnapshot": {
        "annualIncome": borrower["annualIncome"],
        "monthlyDebt": borrower["monthlyDebt"],
        "creditScore": borrower["creditScore"]
    },
    "decisionText": decision_text,
}

container.upsert_item(decision_record)
print("Decision saved to Cosmos DB")

Testing the Integration

Run a full read → infer → write cycle with a known borrower record in Cosmos DB.

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

    prompt = f"""
Assess this borrower profile and return JSON with keys:
risk_level, approval_recommendation, explanation

Data:
income={borrower['annualIncome']}
debt={borrower['monthlyDebt']}
credit_score={borrower['creditScore']}
employment_years={borrower['employmentYears']}
delinquencies={borrower['existingDelinquencies']}
"""

    response = azure_openai_client.chat.completions.create(
        model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
        messages=[
            {"role": "system", "content": "Return valid JSON only."},
            {"role": "user", "content": prompt}
        ],
        temperature=0.1,
    )

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

    container.upsert_item({
        "id": f"decision_{customer_id}",
        "customerId": customer_id,
        "result": result
    })

    return result

print(run_lending_flow("cust_1001"))

Expected output:

{
  "risk_level": "medium",
  "approval_recommendation": "review",
  "explanation": "The applicant has stable income but moderate debt and limited employment history."
}

If your record is stored correctly, you should also see a new document in Cosmos DB under the same partition key.

Real-World Use Cases

• •

  Loan pre-screening agents

  • •Pull applicant data from Cosmos DB.
  • •Ask Azure OpenAI to summarize risk factors before a human underwriter reviews the case.
• •

  Explainable decline notices

  • •Generate customer-facing explanations based on structured lending data.
  • •Store every explanation in Cosmos DB for auditability.
• •

  Portfolio monitoring assistants

  • •Query recent loan records from Cosmos DB.
  • •Use Azure OpenAI to flag borrowers showing early signs of stress based on payment history and delinquency trends.

The pattern here is simple: Cosmos DB holds your system of record, Azure OpenAI handles reasoning over that record, and your Python service ties them together. For startups building lending agents, that gives you a clean path from prototype to production without inventing a custom orchestration layer too early.

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.