Architecture Review Agent는 소프트웨어 아키텍처를 검토하고 대화형 다이어그램을 생성하는 오픈 소스 AI 에이전트 샘플입니다. 어떤 아키텍처 설명(YAML, Markdown, 일반 텍스트, 코드, 설계 문서)이든 입력하면 위험 분석, 실행 가능한 권장 사항, 그리고 편집 및 공유가 가능한 Excalidraw 다이어그램이 포함된 구조화된 검토 결과를 반환합니다.

구조화된 문서 맵(설정, 배포, 스크립트, 시나리오, 테스트)은 docs/README.md를 참조하세요.

클라이언트 (Teams/M365 Copilot, CLI, 웹 브라우저) → Foundry Agent Service 또는 Web App → 핵심 엔진 (Smart Parser, Risk Detector, Report Builder, Diagram Renderer, LLM Inference) → Azure OpenAI / Excalidraw MCP / ACR / Azure App Service

flowchart TB
subgraph Agent["Architecture Review Agent<br/>"]
review_architecture
...

즉각적인 아키텍처 피드백 - 며칠이 아닌 몇 초 만에 우선순위가 지정된 위험 평가 및 개선 계획을 받으세요.
기존 방식 그대로 활용 - YAML 명세서를 붙여넣거나, README 파일을 드래그하거나, 일반적인 영어로 시스템을 설명하세요. 입력 형식이 정식(formal)이 아니더라도 LLM이 구조를 추론합니다.
대화형 다이어그램 - 자동으로 생성된 Excalidraw 다이어그램은 구성 요소, 연결 및 데이터 흐름을 렌더링합니다. 브라우저에서 직접 편집하거나 PNG로 내보낼 수 있습니다.
두 가지 배포 옵션 - Azure App Service에서 풀스택 Web App(FastAPI + React)으로 실행하거나, Teams / M365 Copilot 통합 기능이 있는 Microsoft Foundry에서 Hosted Agent로 실행할 수 있습니다.
개발자를 위해 구축됨 - 단일 스크립트로 로컬에서 실행할 수 있고, 한 번의 명령으로 Azure에 배포할 수 있으며, 파이프라인 통합을 위한 REST API를 제공합니다.

마이크로서비스 뱅킹 아키텍처(Microservices Banking Architecture) — 전체 엔드 투 엔드(end-to-end) 검토: 파일 업로드 → 위험 감지 → 대화형 Excalidraw 다이어그램 → 권장 사항.

비디오가 인라인으로 렌더링되지 않으면, 여기에서 다운로드하여 시청하세요.

기능 (Capability)	설명 (Description)
스마트 입력 지능 (Smart Input Intelligence)	YAML, Markdown, 평문 화살표, README, 설계 문서, 코드, 설정 등 모든 입력을 수용합니다. 형식이 구조화되어 있지 않은 경우 LLM이 아키텍처를 자동으로 추론합니다.
아키텍처 파싱 (Architecture Parsing)	YAML, Markdown, 평문을 위한 규칙 기반 파서(Rule-based parsers)를 제공하며, 비구조화된 콘텐츠의 경우 LLM으로 자동 전환(fallback)됩니다.
위험 감지 (Risk Detection)	구조화된 입력에 대해서는 템플릿 기반 감지기를 사용하며, 추론(inference)을 사용할 때는 LLM이 생성한 문맥 인식 위험 요소와 함께 한 줄 요약된 문제 및 권장 사항을 제공합니다.
대화형 다이어그램 (Interactive Diagrams)	Excalidraw MCP 서버를 통해 대화형 시각화가 가능한 아키텍처 다이어그램을 렌더링합니다.
PNG 내보내기 (PNG Export)	문서, 발표 자료 및 오프라인 공유를 위한 고해상도 PNG 출력을 지원합니다.
컴포넌트 매핑 (Component Mapping)	Fan-in/Fan-out 메트릭 및 고립 노드(orphan) 감지를 포함한 의존성 분석을 수행합니다.
구조화된 보고서 (Structured Reports)	경영진 요약(Executive summary), 우선순위가 지정된 권장 사항, 심각도별로 그룹화된 위험 평가를 제공합니다.
웹 UI (Web UI)	대화형 Excalidraw 다이어그램, 드래그 앤 드롭 파일 업로드, 위험 테이블 및 다운로드 가능한 출력을 포함하는 React 프론트엔드를 제공합니다.
FastAPI 백엔드 (FastAPI Backend)	전체 리뷰 파이프라인을 노출하는 REST API로, Azure App Service에 배포 가능합니다.
호스팅된 에이전트 (Hosted Agent)	Microsoft Agent Framework를 통해 OpenAI Responses와 호환되는 API로 배포됩니다.

이 샘플은 두 가지 프로덕션 배포 경로를 제공합니다. 두 경로 모두 동일한 핵심 분석 엔진(tools.py)을 공유하므로, 운영 모델에 적합한 것을 선택하십시오.

전통적인 풀스택 웹 애플리케이션: FastAPI 백엔드 + React 프론트엔드로 구성되며, 단일 Docker 이미지로 패키징되어 Azure App Service에 배포됩니다.

API 인터페이스 소유 - 사용자 정의 REST 엔드포인트 (/api/review, /api/infer 등)
대화형 브라우저 UI - 드래그 앤 드롭 파일 업로드, 탭 형식의 결과, PNG/Excalidraw 다운로드를 지원하는 React + Excalidraw
표준 App Service 모델 - 자체 인프라 사용, App Service Plan을 통한 확장(수동 또는 자동 확장 규칙)
인증 (Authentication) - API 키 또는 Azure AD, 사용자가 직접 구성

최적의 사용 사례: **커스텀 UI (custom UI)**를 원하는 팀, 기존 도구에 API를 임베드해야 하는 팀, 또는 인프라 및 확장(scaling)에 대한 완전한 제어권을 선호하는 팀에 적합합니다.

주요 파일: api.py · Dockerfile.web · frontend/ · scripts/windows/deploy-webapp.ps1

**VS Code Foundry 확장 프로그램 (extension)**을 통해 Microsoft Foundry의 호스팅된 에이전트(Hosted Agent) 인프라에 배포되는 **관리형 에이전트 (managed agent)**입니다. 플랫폼이 컨테이너화 (containerisation), ID (identity), 확장 (scaling) 및 API 준수 사항을 처리합니다.

OpenAI Responses API - 에이전트가 OpenAI 호환 /responses 엔드포인트를 자동으로 노출합니다.
관리형 인프라 (Managed infrastructure) - Microsoft Foundry가 컨테이너를 빌드, 호스팅 및 확장합니다 (0 → 5개의 복제본(replicas), scale-to-zero 포함).
관리형 ID (Managed identity) - 컨테이너 내에 API 키가 필요하지 않으며, 플랫폼이 RBAC(역할 기반 액세스 제어)가 적용된 시스템 관리형 ID를 할당합니다.
대화 지속성 (Conversation persistence) - Foundry Agent Service가 요청 간의 대화 상태(conversation state)를 관리합니다.
채널 게시 (Channel publishing) - 에이전트를 Microsoft Teams, Microsoft 365 Copilot, 웹 앱 미리보기 (Web App preview) 또는 **안정적인 API 엔드포인트 (stable API endpoint)**에 추가 코드 없이 게시할 수 있습니다.
관측성 (Observability) - Azure Monitor 통합과 함께 OpenTelemetry 트레이싱(tracing)이 내장되어 있습니다.
안정적인 배포 워크플로 (Stable deployment workflow) - **VS Code Foundry 확장 프로그램 (extension)**이 자동 ACR 통합, 관리형 ID 할당 및 내장된 검증 기능을 갖춘 단계별 가이드를 제공합니다.

최적의 사용 사례: 인프라 오버헤드 없이 **관리형의 확장 가능한 API (managed, scalable API)**를 원하는 팀, 또는 에이전트를 Teams / M365 Copilot 채널에 게시해야 하는 팀에 적합합니다. 확장 프로그램 기반의 배포 흐름은 스크립트 기반 방식보다 더 신뢰할 수 있으며 실시간 피드백을 제공합니다.

주요 파일: main.py · agent.yaml · Dockerfile · docs/deployment.md

옵션 A - 웹 앱 |
옵션 B - 호스팅 에이전트 |
|
|---|---|---|
진입점 (Entry point) | api.py (FastAPI + Uvicorn) | main.py (에이전트 프레임워크)
컨테이너 (Container) | Dockerfile.web (multi-stage Node + Python) | Dockerfile (Python 전용)
API 스타일 (API style) | 사용자 정의 REST (/api/review, /api/infer) | OpenAI Responses API (/responses)
UI 포함 여부 (UI included) | 예 - React + Excalidraw | 아니요 (API 전용; Foundry Playground 또는 채널 사용)
Azure 대상 (Azure target) | Azure App Service + ACR | Microsoft Foundry Agent Service
확장성 (Scaling) | App Service Plan (수동/자동 확장 규칙) | 플랫폼 관리형 (0–5 복제본, 제로 스케일링)
신원 (Identity) | 사용자가 구성 (API 키, Azure AD) | 시스템 할당 관리 ID (자동)
대화 기록 (Conversations) | 상태 비저장 REST (사용자 상태 관리) | 플랫폼 관리형 대화 지속성
채널 게시 (Channel publishing) | 해당 없음 (사용자 정의 UI) | Teams, M365 Copilot, 웹 미리보기, 안정 엔드포인트
관측 가능성 (Observability) | 자체 추가 (App Insights 등) | 내장 OpenTelemetry + Azure Monitor
배포 (Deployment) | 스크립트: .\scripts\windows\deploy-webapp.ps1 | VS Code Foundry 확장 프로그램
철거 (Teardown) | .\scripts\windows\teardown.ps1 -ResourceGroup <rg> | Foundry 포털을 통해

팁: 두 옵션을 동시에 실행할 수 있습니다. 내부 팀의 브라우저 기반 검토에는 웹 앱을, API 소비자 및 Teams/Copilot 통합에는 호스팅 에이전트를 사용하세요.

• Python 3.11 이상
• (선택 사항) LLM 추론 및 호스팅 에이전트 모드를 위한 Azure OpenAI 액세스

설정 스크립트는 .venv 가상 환경을 생성하고, 모든 종속성을 설치하며, .env 파일을 한 번에 초기화합니다:

Windows (PowerShell):

# 저장소 복제
git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample
...

Linux / macOS (Bash):

# 저장소 복제
git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample
...

수동으로 설정하는 것을 선호한다면:

저장소 복제 (Clone the repository)

git clone https://github.com/Azure-Samples/agent-architecture-review-sample
cd agent-architecture-review-sample
...

# 템플릿 복사
cp .env.template .env

.env 파일을 본인의 설정값으로 편집하세요:

# Microsoft Foundry / OpenAI 설정
# Microsoft Foundry 프로젝트의 경우 PROJECT_ENDPOINT를 사용하고, Azure OpenAI의 경우 AZURE_OPENAI_ENDPOINT를 사용하세요
PROJECT_ENDPOINT=https://your-project.services.ai.azure.com/api/projects/your-project
...

참고: ARCH_REVIEW_NO_SSL_VERIFY=1 플래그는 Excalidraw MCP 서버 연결에 대한 SSL 검증을 비활성화합니다. HTTPS 트래픽을 가로채는 기업용 프록시(Proxy) 또는 방화벽 뒤에 있는 경우 이 설정을 사용하세요. 인라인(inline)으로도 설정할 수 있습니다:

PowerShell

$env:ARCH_REVIEW_NO_SSL_VERIFY="1"

Bash

export ARCH_REVIEW_NO_SSL_VERIFY=1

로컬 러너(Local runner)는 전체 파이프라인(Pipeline)인 파싱(Parse), 위험 분석(Risk analysis), 다이어그램 생성(Diagram generation), 컴포넌트 매핑(Component mapping) 및 구조화된 보고서 출력(Structured report output)을 실행합니다.

# YAML 아키텍처 파일 분석 (규칙 기반 파서 (Rule-based parser))
python run_local.py scenarios/ecommerce.yaml
# Markdown 아키텍처 파일 분석
...

출력물 (output/에 저장됨):

architecture.excalidraw

• 로컬 확인을 위한 Excalidraw 파일

architecture.png

• 고해상도 PNG 다이어그램

review_bundle.json

• 전체 구조화된 검토 보고서 (JSON)

웹 앱 워크플로(Web app workflow)를 사용하려면 scripts/README.md에 있는 운영체제별 스크립트를 사용하세요. 호스팅된 에이전트(Hosted-agent) 워크플로의 경우, 로컬 azd 실행을 위해서는 docs/azd-local.md를, Foundry 배포를 위해서는 docs/deployment.md를 사용하세요.

이 샘플은 Azure OpenAI 또는 Microsoft Foundry에 배포된 모델(GPT-4.1 권장)이 필요합니다.

• Microsoft Foundry로 이동하여 프로젝트를 생성하거나 엽니다.
• Models + endpoints → Deploy model → Deploy base model로 이동합니다.
• gpt-4.1(또는 선호하는 모델)을 선택하고 Deploy를 클릭합니다.
• Project endpoint(예: https://<project>.services.ai.azure.com)를 복사합니다.
• Deployment name(예: gpt-4.1)을 기록합니다.
• 환경 변수를 설정합니다:

PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com
MODEL_DEPLOYMENT_NAME=gpt-4.1

• Azure Portal에서 Azure OpenAI 리소스를 생성합니다. - Microsoft Foundry로 이동하여 리소스를 선택한 후 Deployments → Create deployment를 클릭합니다. - gpt-4.1을 선택하고, 배포 이름(deployment name)을 설정한 뒤 배포합니다. - Endpoint(예: https://<resource>.openai.azure.com/)를 복사합니다. - 환경 변수를 설정합니다:

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4.1

Architecture Review Agent는 두 가지 인증 방식을 지원합니다:

API Key(가장 간단함) - .env 파일에 AZURE_OPENAI_API_KEY를 설정합니다. 값이 존재하면 자동으로 사용됩니다. DefaultAzureCredential(대체 방식) - Azure CLI (az login), 관리 ID (Managed Identity), 그리고 서비스 주체(service principal) 환경 변수 (AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_CLIENT_SECRET)를 지원합니다.

API 키를 사용한 로컬 개발의 경우:

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-key-here

또는 Azure CLI를 사용하는 경우:

az login
az account set --subscription <your-subscription-id>

Architecture Review Agent는 구조화된 데이터(structured)든 비구조화된 데이터(unstructured)든 어떠한 입력도 수용합니다. 컴포넌트(Component) 이름, 유형, 아키텍처는 완전히 동적입니다.

flowchart LR
A["ANY INPUT<br/>(YAML, MD, README,<br/>code, prose, etc.)"] --> B{Smart Parser}
B -- "Structured" --> C["Rule-based<br/>(fast)"]
...

구조화된 형식 (Structured formats) (components / connections가 포함된 YAML, ## Components 헤더가 있는 Markdown, 평문 화살표 등) → 빠른 규칙 기반 파서(rule-based parser)를 사용합니다. 비구조화된 입력 (Unstructured inputs) (그 외 모든 파일, 산문, 코드, 설정 등) → 규칙 기반 파싱 결과가 1개 이하의 컴포넌트로 나타날 경우, LLM이 자동으로 콘텐츠를 분석하여 컴포넌트/유형/연결 관계를 추론하고 진행합니다. LLM 강제 사용 (Force LLM) → --infer 플래그를 사용하면 구조화된 입력에 대해서도 항상 LLM 추론을 사용합니다.

name: My Architecture
components:
- name: API Gateway
...

허용되는 키(keys): components / services / nodes 및 connections

/edges

/flows

/links

.

## Components (구성 요소)
### API Gateway (API 게이트웨이)
- **Type (유형):** gateway (게이트웨이)
...

API Gateway -> User Service -> User Database
API Gateway -> Product Service -> Product DB
Product Service -> Redis Cache

연결된 화살표 (A -> B -> C)는 개별 연결(connections)로 자동 확장됩니다.

README, 설계 문서, 코드 파일, Terraform 설정, 회의록 등을 입력하면 LLM이 이를 분석합니다:

우리 플랫폼은 프론트엔드(frontend)로 React를 사용하며, CloudFront CDN을 통해 서비스됩니다.
모든 API 호출은 Kong API Gateway를 거치며, 이는 세 개의 마이크로서비스(microservices)로 라우팅됩니다:
User Service, Order Service, 그리고 Inventory Service입니다. 각 서비스는 자체적인
...

모델은 다음과 같이 추론합니다:

10개의 구성 요소 (components)

• React Frontend, CloudFront CDN, Kong API Gateway, User Service, Order Service, Inventory Service, 3× PostgreSQL DBs, Kafka, Redis, Datadog

구성 요소 유형 (Component types)

• frontend (프론트엔드), cache (캐시), gateway (게이트웨이), service (서비스), database (데이터베이스), queue (큐), monitoring (모니터링)

~12개의 연결 (connections)

• Frontend→CDN→Gateway→Services→DBs, Order→Kafka→Inventory 등

그 후 전체적인 리스크 분석 (risk analysis), 다이어그램 생성 (diagram generation), 그리고 보고서 작성을 진행합니다.