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

Combining Azure OpenAI with Cosmos DB gives you a practical backbone for multi-agent fintech systems: one service generates and reasons over financial workflows, the other stores agent state, conversation history, customer context, and audit trails. That means you can build systems like fraud triage agents, KYC review agents, or loan underwriting assistants that stay consistent across turns and across services.

The key pattern is simple: use Azure OpenAI for generation and tool orchestration, then persist every meaningful agent event in Cosmos DB so your agents can coordinate without losing state.

Prerequisites

• •An Azure subscription
• •An Azure OpenAI resource with:
  • •a deployed chat model name, such as gpt-4o-mini
  • •endpoint URL
  • •API key
• •An Azure Cosmos DB account
  • •either NoSQL API or MongoDB API
  • •database and container created
• •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) Install dependencies and load configuration

Start by wiring the SDKs into your app. Keep secrets in environment variables; don’t hardcode them into agent code.

pip install openai azure-cosmos python-dotenv

import os
from dotenv import load_dotenv

load_dotenv()

AZURE_OPENAI_ENDPOINT = os.environ["AZURE_OPENAI_ENDPOINT"]
AZURE_OPENAI_API_KEY = os.environ["AZURE_OPENAI_API_KEY"]
AZURE_OPENAI_DEPLOYMENT = os.environ["AZURE_OPENAI_DEPLOYMENT"]

COSMOS_ENDPOINT = os.environ["COSMOS_ENDPOINT"]
COSMOS_KEY = os.environ["COSMOS_KEY"]
COSMOS_DATABASE = os.environ["COSMOS_DATABASE"]
COSMOS_CONTAINER = os.environ["COSMOS_CONTAINER"]

2) Create the Azure OpenAI client

Use the official OpenAI Python SDK configured for Azure. For fintech workflows, keep the prompt scoped to policy and structured outputs.

from openai import AzureOpenAI

aoai_client = AzureOpenAI(
    api_key=AZURE_OPENAI_API_KEY,
    api_version="2024-06-01",
    azure_endpoint=AZURE_OPENAI_ENDPOINT,
)

def generate_agent_response(user_message: str) -> str:
    response = aoai_client.chat.completions.create(
        model=AZURE_OPENAI_DEPLOYMENT,
        messages=[
            {
                "role": "system",
                "content": (
                    "You are a fintech operations agent. "
                    "Be concise, factual, and return JSON-like summaries when possible."
                ),
            },
            {"role": "user", "content": user_message},
        ],
        temperature=0.2,
    )
    return response.choices[0].message.content

This is the core call you’ll use in each agent: client.chat.completions.create(...). In production, keep temperature low for deterministic financial workflows.

3) Connect to Cosmos DB and create a persistence layer

Cosmos DB is where your agents store shared memory: conversation state, task status, decisions, and timestamps. Use a partition key that matches your multi-agent access pattern, usually sessionId or caseId.

from azure.cosmos import CosmosClient, PartitionKey

cosmos_client = CosmosClient(COSMOS_ENDPOINT, credential=COSMOS_KEY)
database = cosmos_client.create_database_if_not_exists(id=COSMOS_DATABASE)

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

def save_agent_event(session_id: str, agent_name: str, event_type: str, payload: dict):
    item = {
        "id": f"{session_id}:{agent_name}:{event_type}",
        "sessionId": session_id,
        "agentName": agent_name,
        "eventType": event_type,
        "payload": payload,
    }
    container.upsert_item(item)
    return item

For multi-agent systems, this pattern matters because each agent can read the same session partition and make decisions based on prior outputs.

4) Build an orchestrated multi-agent flow

Here’s a simple two-agent pattern: one agent classifies a fintech request, another drafts the response. Both persist their outputs to Cosmos DB so the system has traceability.

def classify_request(user_message: str) -> str:
    response = aoai_client.chat.completions.create(
        model=AZURE_OPENAI_DEPLOYMENT,
        messages=[
            {"role": "system", "content": "Classify the request as fraud, kyc, lending, payments, or support."},
            {"role": "user", "content": user_message},
        ],
        temperature=0,
    )
    return response.choices[0].message.content.strip()

def run_multi_agent_session(session_id: str, user_message: str):
    classification = classify_request(user_message)
    save_agent_event(
        session_id=session_id,
        agent_name="classifier",
        event_type="classification",
        payload={"classification": classification, "input": user_message},
    )

    draft = generate_agent_response(
        f"User request category: {classification}. Respond to this fintech case: {user_message}"
    )
    save_agent_event(
        session_id=session_id,
        agent_name="responder",
        event_type="draft_response",
        payload={"response": draft},
    )

    return {"classification": classification, "response": draft}

This is enough to get a working coordinator. In a larger system, each specialist agent can read from Cosmos DB before acting.

5) Read back state for downstream agents

A multi-agent system is only useful if later agents can inspect earlier decisions. Pull session history from Cosmos DB using SQL queries against the partition key.

def get_session_events(session_id: str):
    query = """
    SELECT * FROM c
    WHERE c.sessionId = @sessionId
    ORDER BY c._ts ASC
    """
    params = [{"name": "@sessionId", "value": session_id}]

    items = list(
      container.query_items(
          query=query,
          parameters=params,
          enable_cross_partition_query=False,
      )
    )
    return items

def build_context_from_history(session_id: str) -> str:
    events = get_session_events(session_id)
    lines = []
    for event in events:
        lines.append(f"{event['agentName']} [{event['eventType']}]: {event['payload']}")
    return "\n".join(lines)

That gives you durable memory for handoffs between agents like investigator → reviewer → approver.

Testing the Integration

Run a single session end-to-end and verify both generation and persistence work.

if __name__ == "__main__":
    session_id = "fintech-case-1001"
    user_message = "A customer reports an unauthorized card payment of $480 in another country."

    result = run_multi_agent_session(session_id=session_id, user_message=user_message)
    print("Classification:", result["classification"])
    print("Response:", result["response"])

    history = get_session_events(session_id)
    

Expected output:

Classification: fraud
Response: The case should be routed to fraud operations immediately...

You should also see two documents in Cosmos DB for the same sessionId: one from the classifier and one from the responder.

Real-World Use Cases

• •

  Fraud investigation copilot

  • •One agent classifies suspicious activity.
  • •Another retrieves prior case notes from Cosmos DB.
  • •A third drafts analyst-ready recommendations.
• •

  KYC / AML review workflow

  • •Agents extract entities from documents.
  • •Cosmos DB stores verification status per customer case.
  • •Azure OpenAI generates exception summaries for compliance teams.
• •

  Loan origination assistant

  • •One agent collects applicant data.
  • •Another checks policy rules and missing fields.
  • •Cosmos DB keeps application state across multiple review steps.

The production pattern here is straightforward: Azure OpenAI handles reasoning and language tasks, while Cosmos DB handles durable coordination. If you design your partitioning around session or case IDs from day one, your multi-agent system stays traceable and easy to scale.

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.