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

Combining Azure OpenAI for payments with Cosmos DB gives you a practical pattern for multi-agent systems that need to reason, decide, and persist state across transactions. The model handles intent extraction, payment classification, and next-best-action decisions, while Cosmos DB stores agent memory, payment events, and workflow state with low-latency reads.

This is the right setup when you need multiple agents to coordinate on payment flows: one agent validates invoices, another checks risk or fraud signals, and a third writes durable state so the system can recover cleanly after retries or failures.

Prerequisites

• •Python 3.10+
• •An Azure subscription
• •An Azure OpenAI resource with:
  • •a deployed chat model, such as gpt-4o-mini
  • •endpoint URL
  • •API key
• •An Azure Cosmos DB account with:
  • •database created
  • •container created
  • •partition key chosen, ideally /conversationId or /paymentId
• •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 initialize clients.

pip install openai azure-cosmos python-dotenv

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"],
)

db = cosmos_client.get_database_client(os.environ["COSMOS_DATABASE"])
container = db.get_container_client(os.environ["COSMOS_CONTAINER"])
deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

2. •Use Azure OpenAI to classify the payment request and extract structured intent.

For multi-agent systems, don’t pass raw chat text around as state. Convert it into a structured object first so downstream agents can make deterministic decisions.

import json

def classify_payment_request(message: str) -> dict:
    response = aoai_client.chat.completions.create(
        model=deployment_name,
        messages=[
            {"role": "system", "content": "You classify payment requests into structured JSON."},
            {"role": "user", "content": f"""
Extract:
- action: create_payment | refund_payment | check_status | dispute_payment
- amount: number or null
- currency: ISO code or null
- merchant: string or null
- confidence: float between 0 and 1

Message: {message}
Return JSON only.
"""}
        ],
        temperature=0,
    )

    return json.loads(response.choices[0].message.content)

intent = classify_payment_request("Refund $49.99 to Acme Corp for invoice INV-1042")
print(intent)

3. •Persist the agent state in Cosmos DB.

Store both the model output and your workflow metadata. That gives each agent a shared source of truth for retries, auditability, and handoffs.

from datetime import datetime, timezone

def save_payment_state(payment_id: str, conversation_id: str, payload: dict) -> None:
    document = {
        "id": payment_id,
        "paymentId": payment_id,
        "conversationId": conversation_id,
        "type": "payment_intent",
        "createdAt": datetime.now(timezone.utc).isoformat(),
        "payload": payload,
        "status": "classified",
    }
    container.upsert_item(document)

save_payment_state(
    payment_id="pay_1001",
    conversation_id="conv_7788",
    payload=intent,
)

4. •Add a second agent step that reads Cosmos DB state before making a decision.

This is where multi-agent systems become useful. One agent can classify; another can inspect stored context and decide whether to approve, escalate, or request more data.

def get_payment_state(payment_id: str) -> dict:
    return container.read_item(
        item=payment_id,
        partition_key=payment_id,
    )

def decide_next_action(payment_id: str) -> str:
    state = get_payment_state(payment_id)
    payload = state["payload"]

    response = aoai_client.chat.completions.create(
        model=deployment_name,
        messages=[
            {"role": "system", "content": "You are a payments operations agent."},
            {"role": "user", "content": f"""
Given this stored payment intent:
{json.dumps(payload)}

Decide one action:
- APPROVE
- ESCALATE
- REQUEST_MORE_INFO

Return one word only.
"""}
        ],
        temperature=0,
    )

    return response.choices[0].message.content.strip()

action = decide_next_action("pay_1001")
print(action)

5. •Update the Cosmos DB record with the final decision.

That closes the loop. Each agent writes back its output so later agents or human reviewers can trace what happened.

def update_payment_status(payment_id: str, status: str) -> None:
    item = container.read_item(item=payment_id, partition_key=payment_id)
    item["status"] = status
    item["updatedAt"] = datetime.now(timezone.utc).isoformat()
    container.replace_item(item=payment_id, body=item)

update_payment_status("pay_1001", action.lower())

Testing the Integration

Run an end-to-end test that classifies a message, stores it in Cosmos DB, retrieves it, and returns a decision.

test_message = "Please refund USD 120 to vendor Contoso for duplicate charge"
payment_id = "pay_test_001"
conversation_id = "conv_test_001"

intent = classify_payment_request(test_message)
save_payment_state(payment_id, conversation_id, intent)
decision = decide_next_action(payment_id)
update_payment_status(payment_id, decision.lower())

stored = get_payment_state(payment_id)

print("Intent:", intent)
print("Decision:", decision)
print("Stored status:", stored["status"])

Expected output:

Intent: {'action': 'refund_payment', 'amount': 120.0, 'currency': 'USD', 'merchant': 'Contoso', 'confidence': 0.98}
Decision: APPROVE
Stored status: approve

Real-World Use Cases

• •Payment support copilots that classify customer requests, route them to the right workflow, and persist every turn for audit trails.
• •Multi-agent fraud triage systems where one agent extracts intent from chat/email and another checks historical patterns stored in Cosmos DB.
• •Invoice processing pipelines where an extraction agent parses invoice data and a policy agent decides whether to auto-pay or escalate for review.

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.