# microsoft/multi-agent-custom-automation-engine-solution-accelerator architecture

> Architecture diagram of the GitHub repository microsoft/multi-agent-custom-automation-engine-solution-accelerator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator
- Repository: https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator

## Overview

##### Project type and purpose
- This is a full-stack, AI-driven orchestration system (“Multi-Agent Custom Automation Engine”) that uses multiple specialized agents to automate business tasks.
- Frontend: React/TypeScript app served via a Python server.
- Backend: Python service using Semantic Kernel, providing REST APIs, agent orchestration, memory persistence, and telemetry.
- Infra: Azure resources (Container Apps, OpenAI Service, Cosmos DB, Container Registry) provisioned via Bicep.

##### File structure
- Top level directories:
- infra: Bicep templates & scripts for Azure infra deployment.
- src/backend: Python service (app_kernel, handlers, auth, context, agents, tools, middleware).
- src/frontend: React/TS app (Vite), served by frontend_server.py.
- tests/e2e-test: Selenium-like E2E tests for the running application.
- CI/CD & DevOps: .github/workflows & .azdo/pipelines define build, test, container-build, deploy, WAF deployment.
- Dockerfiles: in src/backend & src/frontend for containerization.
- Configuration files: pyproject.toml, requirements.txt, .env.sample, azure.yaml.

##### README for additional insights
User → Frontend (Container App) → Backend (Container App) → Azure OpenAI + Cosmos DB.
- Agent flow: how tasks move through Planner, Executor, Validator agents.

a. Main components
- User: browser or client.
- Frontend: React app + Python server (API gateway).
- Backend: Python service with layers:
– API Handlers (entrypoints)
– Auth module
– Kernel Orchestrator (app_kernel.py, config_kernel.py)
– Context/Memory (cosmos_memory_kernel.py)
– Kernel Agents (planner, hr, marketing, procurement, product, tech_support, human)
– Kernel Tools (tool wrappers per domain)
– Event utilities & OTLP tracing
- Database: Azure Cosmos DB (persist memory, metadata).
- AI Service: Azure OpenAI Service (LLMs).
- Container Registry: stores container images.
- CI/CD pipelines & Infra: Azure DevOps/GitHub Actions + Bicep templates.

b. Relationships and interactions
- User sends tasks via frontend UI → Frontend Server exposes REST or WebSocket → Backend API Handler receives request → Auth middleware validates → Kernel Orchestrator breaks down task → Kernel Agents (via agent_factory) coordinate planning/execution → Agents call Tools (which wrap external APIs or DB) → Context module persists interim results to Cosmos DB → Orchestrator aggregates results → Handler returns response to frontend → Frontend updates UI.
- Backend logs/telemetry via OTLP to Azure Monitor.

c. Architectural patterns
- Layered architecture (API layer, orchestration layer, persistence layer).
- Plugin-like agent modules (each agent implements a common interface via agent_base).
- Factory pattern (agent_factory selects & instantiates agents).
- Dependency injection/config kernel for environment & service wiring.
- Infra-as-Code (Bicep) defining cloud resources.

d. Key technologies/frameworks
- Python, Semantic Kernel SDK, FastAPI or equivalent (see Dockerfile & app_kernel imports).
- React + Vite + TypeScript in frontend.
- Azure Container Apps, Azure OpenAI, Azure Cosmos DB, Azure Container Registry.
- Bicep for infra.
- GitHub Actions & Azure DevOps for CI/CD.

##### Backend structure (per your request)
- Entrypoint: app_kernel.py loads config, wires up auth, telemetry, and kernel.
- config_kernel.py sets up connections (Cosmos DB, OpenAI client).
- Handlers folder: individual modules (runtime_interrupt_kernel, health_check) expose API endpoints.
- auth module: auth_utils & sample_user demonstrate token/credential verification.
- context module: cosmos_memory_kernel implements IKernalMemory storing messages & state.
- kernel_agents: one class per business domain; all implement agent_base and use agent_utils.
- kernel_tools: low-level wrappers around domain APIs or logic, invoked by agents.
- utils_date, utils_kernel, event_utils provide shared tooling.
- Testing: unit tests under src/backend/tests validate each layer; integration tests exercise agent flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        RF["React Frontend App"]:::frontend
        FS["Frontend Server (API Gateway & Static Serving)"]:::frontend
        FE_DOCKER["Frontend Dockerfile"]:::infra
    end

    %% Backend Layer
    subgraph "Backend Layer"
        %% API Layer
        APIHandler["API Handler\n(runtime_interrupt_kernel)"]:::api
        HealthCheck["Health Check Middleware"]:::backend
        Auth["Auth Module"]:::backend
        Models["Message Models"]:::backend

        %% Orchestration Layer
        OrchEntry["App Kernel & Config"]:::orchestration

        %% Persistence Layer
        Context["Cosmos Memory Context"]:::persistence

        %% Agents Layer
        subgraph "Kernel Agents"
            AgentBase["agent_base"]:::agent
            AgentFactory["agent_factory"]:::agent
            Planner["PlannerAgent"]:::agent
            HRAgent["HRAgent"]:::agent
            MarketingAgent["MarketingAgent"]:::agent
            ProcurementAgent["ProcurementAgent"]:::agent
            ProductAgent["ProductAgent"]:::agent
            TechSupportAgent["TechSupportAgent"]:::agent
            HumanAgent["HumanAgent"]:::agent
        end

        %% Tools Layer
        subgraph "Kernel Tools"
            HRTools["HR Tools"]:::tool
            MarketingTools["Marketing Tools"]:::tool
            ProcurementTools["Procurement Tools"]:::tool
            ProductTools["Product Tools"]:::tool
            TechSupportTools["Tech Support Tools"]:::tool
            GenericTools["Generic Tools"]:::tool
        end

        %% Telemetry & Events
        EventUtil["Event Utils"]:::telemetry
        OTLP["OTLP Tracing"]:::telemetry

        %% Containerization
        BE_DOCKER["Backend Dockerfile"]:::infra
    end

    %% Azure Services
    subgraph "Azure Services"
        OpenAI["Azure OpenAI Service"]:::external
        CosmosDB["Azure Cosmos DB"]:::external
        ACR["Azure Container Registry"]:::external
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Infra"
        GHWF["GitHub Workflows"]:::infra
        AzDO["Azure DevOps Pipeline"]:::infra
        Bicep["Bicep Templates"]:::infra
    end

    %% Relationships
    User --> RF
    RF --> FS
    FS -->|REST API| APIHandler
    APIHandler --> HealthCheck
    APIHandler --> Auth
    APIHandler --> OrchEntry
    HealthCheck --> OrchEntry
    Auth --> OrchEntry
    OrchEntry --> AgentFactory
    OrchEntry --> Context
    AgentFactory --> AgentBase
    AgentFactory --> Planner
    AgentFactory --> HRAgent
    AgentFactory --> MarketingAgent
    AgentFactory --> ProcurementAgent
    AgentFactory --> ProductAgent
    AgentFactory --> TechSupportAgent
    AgentFactory --> HumanAgent
    Planner --> HRTools
    Planner --> MarketingTools
    Planner --> ProcurementTools
    Planner --> ProductTools
    Planner --> TechSupportTools
    Planner --> GenericTools
    HRAgent --> HRTools
    MarketingAgent --> MarketingTools
    ProcurementAgent --> ProcurementTools
    ProductAgent --> ProductTools
    TechSupportAgent --> TechSupportTools
    HumanAgent --> GenericTools
    Context --> CosmosDB
    OrchEntry --> OpenAI
    EventUtil --> OTLP
    OrchEntry --> EventUtil

    GHWF --> ACR
    AzDO --> ACR
    ACR --> FS
    ACR --> FS
    ACR --> BE_DOCKER
    Bicep --> OpenAI
    Bicep --> CosmosDB
    Bicep --> ACR
    Bicep --> FS
    Bicep --> BE_DOCKER

    %% Click Events
    click RF "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/tree/main/src/frontend/src"
    click FS "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/frontend/frontend_server.py"
    click FE_DOCKER "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/tree/main/src/frontend/Dockerfile"
    click APIHandler "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/handlers/runtime_interrupt_kernel.py"
    click HealthCheck "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/middleware/health_check.py"
    click Auth "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/auth/auth_utils.py"
    click Auth "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/auth/sample_user.py"
    click OrchEntry "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/app_kernel.py"
    click OrchEntry "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/config_kernel.py"
    click Context "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/context/cosmos_memory_kernel.py"
    click AgentBase "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/agent_base.py"
    click AgentFactory "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/agent_factory.py"
    click Planner "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/planner_agent.py"
    click HRAgent "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/hr_agent.py"
    click MarketingAgent "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/marketing_agent.py"
    click ProcurementAgent "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/procurement_agent.py"
    click ProductAgent "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/product_agent.py"
    click TechSupportAgent "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/tech_support_agent.py"
    click HumanAgent "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_agents/human_agent.py"
    click HRTools "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_tools/hr_tools.py"
    click MarketingTools "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_tools/marketing_tools.py"
    click ProcurementTools "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_tools/procurement_tools.py"
    click ProductTools "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_tools/product_tools.py"
    click TechSupportTools "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_tools/tech_support_tools.py"
    click GenericTools "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/kernel_tools/generic_tools.py"
    click EventUtil "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/event_utils.py"
    click OTLP "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/src/backend/otlp_tracing.py"
    click BE_DOCKER "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/tree/main/src/backend/Dockerfile"
    click Bicep "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/infra/main.bicep"
    click GHWF "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/tree/main/.github/workflows"
    click AzDO "https://github.com/microsoft/multi-agent-custom-automation-engine-solution-accelerator/blob/main/.azdo/pipelines/azure-dev.yml"

    %% Styles
    classDef external fill:#d5d8db,stroke:#1f2c34,color:#1f2c34;
    classDef frontend fill:#dae8fc,stroke:#6c8ebf,color:#0b365d;
    classDef api fill:#e1d5e7,stroke:#9673a6,color:#4b1132;
    classDef backend fill:#d5e8d4,stroke:#82b366,color:#274e13;
    classDef orchestration fill:#d5e8d4,stroke:#82b366,color:#274e13;
    classDef persistence fill:#fff2cc,stroke:#d6b656,color:#806517;
    classDef agent fill:#f8cecc,stroke:#b85450,color:#4b1c1c;
    classDef tool fill:#f5f5f5,stroke:#a4a4a4,color:#333333;
    classDef telemetry fill:#e1e1e1,stroke:#888888,color:#333333;
    classDef infra fill:#ffe6cc,stroke:#d27b19,color:#663300;
```
