# hieumoscow/azure-openai-agents architecture

> Architecture diagram of the GitHub repository hieumoscow/azure-openai-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hieumoscow/azure-openai-agents
- Repository: https://github.com/hieumoscow/azure-openai-agents

## Overview

##### Project Type and Purpose
- This is a **backend-focused demo application** (no web UI in this repo). It’s a standalone Python service that:
- Hosts multiple OpenAI Agents (Customer Service, Loan Specialist, Investment Specialist, Banking Assistant)
- Exposes “tools” (check_account_balance, calculate_loan_payment)
- Connects to Azure OpenAI (direct or via APIM)
- Emits telemetry via Logfire → OpenTelemetry → Azure Application Insights

##### File Structure
- **main.py**: Entry point. Configures Logfire, instruments OpenAI Agents, kicks off demo workflow.
- **fixed_openai_agents.py**: Patches Agent SDK for correct span naming in telemetry.
- **otel-collector-config.yaml**: Defines local OTLP receiver and Azure Monitor exporter.
- **requirements.txt**/.env.sample: Dependencies and environment variables for Azure OpenAI vs. APIM.
- **assets/**: Demo video and gif for Application Insights dashboard.

##### Extract Key Architecture Elements
a. **Components**
- User (CLI or script runner)
- BankingAgentService (the Python app)
- Agent Orchestrator (OpenAI Agents SDK)
- Agents (Customer Service, Loan, Investment, Banking Assistant)
- Tools Layer (check_account_balance, calculate_loan_payment)
- External Systems
- Azure OpenAI endpoint (or Azure API Management layer)
- (Optional) Bank backend APIs for real data
- Telemetry Pipeline
- Logfire instrumentation
- Local OTLP receiver (otel-collector)
- Azure Application Insights

b. **Interactions & Data Flows**
1. **User → BankingAgentService**: User invokes main.py (e.g., CLI input).
2. **Agent Orchestrator** chooses appropriate Agent based on input.
3. **Agent → Azure OpenAI**: Sends ChatCompletion or Agent API calls.
4. **Agent → Tools Layer**: If a “tool” is invoked (e.g., check balance), calls internal function or external bank API.
5. **Telemetry**: All calls are instrumented by Logfire → emitted as OTLP → collected by otel-collector → forwarded to Azure Application Insights.

c. **Architectural Patterns/Principles**
- **Agent-Based Orchestration**: Decoupled, each Agent has its own domain knowledge & toolset.
- **Handoff Workflow**: Customer Service Agent delegates to specialists.
- **Sidecar-style Telemetry**: Application and collector run separately but communicate via OTLP.
- **Configuration-driven**: Environment variables select direct vs. APIM connection.

##### Putting It All Together
- In the center, group:
[BankingAgentService]
– Orchestrator
– Tools Layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User (CLI)"]
    
    %% Service Group
    subgraph "BankingAgentService"
        direction TB
        Service["BankingAgentService"]:::core
        Service --> Orchestrator
        Service --> FixedPatcher
        Service --> Config
        Service --> Deps
        Service --> Assets

        Orchestrator["Agent Orchestrator"]:::core
        FixedPatcher["Fixed OpenAI Agents Telemetry Patcher"]:::core

        subgraph "Agents"
            direction TB
            Customer["Customer Service Agent"]:::core
            Loan["Loan Specialist Agent"]:::core
            Investment["Investment Specialist Agent"]:::core
            BankingAssistant["Banking Assistant Agent"]:::core
        end

        Tools["Tools Layer"]:::core
    end

    %% External Services
    AzureOpenAI[(Azure OpenAI Endpoint)]:::external
    APIM[(Azure API Management)]:::external
    BankAPI[(Bank Backend APIs)]:::external

    %% Telemetry Pipeline
    Logfire["Logfire Instrumentation"]:::telemetry
    OTLPReceiver["OpenTelemetry Collector"]:::telemetry
    AppInsights[(Azure Application Insights)]:::telemetry

    %% Flows
    User -->|"invoke main.py"| Service
    Config -->|"env vars"| Service
    Deps -.-> Service
    Assets -.-> Service

    Service -->|"initializes"| Orchestrator
    Service -->|"applies patch"| FixedPatcher
    Orchestrator -->|"calls Agents"| Customer
    Orchestrator -->|"calls Agents"| Loan
    Orchestrator -->|"calls Agents"| Investment
    Orchestrator -->|"calls Agents"| BankingAssistant

    Orchestrator -->|"HTTPS"| AzureOpenAI
    Orchestrator -->|"HTTPS"| APIM

    Customer -->|"internal call"| Tools
    Loan -->|"internal call"| Tools
    Investment -->|"internal call"| Tools
    BankingAssistant -->|"internal call"| Tools

    Service -->|"OTLP/HTTP or gRPC"| OTLPReceiver
    OTLPReceiver -->|"Azure Monitor Exporter"| AppInsights

    %% Configuration and Assets
    Config[".env.sample"]:::core
    Deps["requirements.txt"]:::core
    Assets["assets/"]:::core

    %% Click Events
    click Service "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click Orchestrator "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click FixedPatcher "https://github.com/hieumoscow/azure-openai-agents/blob/main/fixed_openai_agents.py"
    click Customer "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click Loan "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click Investment "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click BankingAssistant "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click Tools "https://github.com/hieumoscow/azure-openai-agents/blob/main/main.py"
    click OTLPReceiver "https://github.com/hieumoscow/azure-openai-agents/blob/main/otel-collector-config.yaml"
    click Config "https://github.com/hieumoscow/azure-openai-agents/blob/main/.env.sample"
    click Deps "https://github.com/hieumoscow/azure-openai-agents/blob/main/requirements.txt"
    click Assets "https://github.com/hieumoscow/azure-openai-agents/tree/main/assets/"

    %% Styles
    classDef core fill:#add8e6,stroke:#000,stroke-width:1px
    classDef external fill:#90ee90,stroke:#000,stroke-width:1px
    classDef telemetry fill:#ffa500,stroke:#000,stroke-width:1px
```
