Azure에서 프로덕션 레디 AI 에이전트 구축 가이드
요약
Azure 환경에서 프로덕션 수준의 AI 에이전트를 구축하기 위한 종합 가이드를 제공합니다. GitHub-first 워크플로우를 기반으로 SDK 사용법, 아키텍처 설계, IaC를 통한 배포 파이프라인 구축 방법을 다룹니다.
핵심 포인트
- Azure AI Foundry를 활용한 단일 엔드포인트 관리 방식 제안
- Python 및 .NET SDK를 지원하는 Microsoft Agent Framework 활용
- GitHub Actions와 azd를 이용한 클라우드 배포 자동화
- AI 엔지니어, 아키텍트, DevOps를 위한 역할별 가이드 제공
Pre-configured dev environment • Python 3.12 • Azure CLI • Agent Framework • No setup required
Code to Cloud의 오픈 소스 이니셔티브
🚀 시작하기 · ☁️ Codespaces · 📖 문서(Docs) · 💻 샘플(Samples) · 🏗️ 아키텍처(Architecture) · 🤝 기여(Contributing)
클릭하여 확장하세요
이 리포지토리는 GitHub-first 워크플로우를 사용하여 Azure에서 프로덕션 레디 AI 에이전트를 구축하기 위한 종합적인 가이드입니다.
| Azure AI Foundry | Agent Framework | GitHub Actions |
💡
Azure DevOps가 아닙니다— 이 리포는 GitHub에 초점을 맞추고 있습니다. Azure DevOps의 경우, Azure DevOps 문서를 참조하세요.
| 역할 | 찾을 수 있는 것 | |
|---|---|
| AI 엔지니어 | SDK 가이드, 코드 샘플, 에이전트 패턴 |
| 아키텍트 | 참고 아키텍처, 랜딩 존(landing zones), 디자인 체크리스트 |
| DevOps/플랫폼 | IaC 템플릿, 배포 파이프라인, 운영 지침 |
| 보안 팀 | 보안 모범 사례, 규정 준수 패턴 |
| 단계 | 가이드 | 시간 | 할 일 |
|---|---|---|---|
| 1 | 전제 조건(Prerequisites) | 15분 | Azure CLI, Python, VS Code 설치 |
| 2 | 첫 번째 에이전트(First Agent) | 15분 | 첫 AI 에이전트 구축 |
| 3 | 배포(Deploy) | 15분 | azd를 사용하여 Azure에 배포 |
| 4 | 다음 단계(Next Steps) | 5분 | 다중 에이전트, 관측 가능성(observability), 프로덕션 |
💡
이미 익숙하신가요? 빠른 시작 또는 리소스로 이동하세요.
| 도구 | 설치 방법 | |
|---|---|
| Azure CLI | brew install azure-cli 또는 다운로드 |
...
# Microsoft Agent Framework (Python)
pip install agent-framework --pre
# Azure AI Foundry SDK
...
# Microsoft Agent Framework (.NET)
dotnet add package Microsoft.Agents.AI --prerelease
# 기본(Primary): Foundry 프로젝트 엔드포인트 (모델, 에이전트, 도구 포함)
export AZURE_AI_FOUNDRY_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
# 선택 사항(Optional): Azure OpenAI에 직접 액세스하는 경우 (기존 패턴)
...
💡
Foundry-first: 단일 Foundry 프로젝트 엔드포인트에 연결하여 모델, 에이전트 및 도구에 액세스하세요. 별도의 Azure OpenAI 엔드포인트를 관리할 필요가 없습니다.
import asyncio
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
...
파일 트리 확장 클릭
azure-agentic-engineering/
├── 📄 README.md # 현재 위치
├── 📁 docs/
...
🛠️ 개발자 도구 및 SDK (Developer Tools & SDKs)
🤔 "어떤 SDK를 사용해야 하나요?" → 전체 SDK 결정 가이드 (Full SDK Decision Guide)
| SDK | 목적 | ✅ 사용 시점 | ❌ 사용 금지 시점 |
|---|---|---|---|
| Agent Framework | 에이전트 구축 및 오케스트레이션 (orchestrate) | 멀티 에이전트 워크플로 (Multi-agent workflows), 그래프 (graphs) | 단순 채팅 완성 (chat completions) |
| Foundry SDK | Azure AI 플랫폼 액세스 | 호스팅된 에이전트, 평가 (evaluations) | 클라우드 불가지론적 (cloud-agnostic) 환경이 필요한 경우 |
| Copilot SDK | 앱에 Copilot 임베딩 | 개발자 도구, CLI | 개발 영역이 아닌 도메인 |
| OpenAI SDK | 직접적인 모델 추론 (model inference) | 단순 채팅, 호환성 | 오케스트레이션 (orchestration)이 필요한 경우 |
☁️ 플랫폼 및 인프라 (Platforms & Infrastructure)
| 리소스 | 설명 | 링크 |
|---|---|---|
| Microsoft Foundry GitHub | 공식 Foundry 샘플 및 도구 | [GitHub] |
| Azure AI Landing Zones | 엔터프라이즈 규모의 AI 인프라 (Bicep/Terraform) | [GitHub] |
| Deploy AI in Production | 풀스택 프로덕션 배포 가속기 | [GitHub] |
| Azure Container Apps | AI 워크로드를 위한 서버리스 컨테이너 | [Docs] |
| Azure Kubernetes Service | 대규모 AI를 위한 엔터프라이즈 Kubernetes | [Docs] |
👁️ 관측성 및 모니터링 (Observability & Monitoring)
| 리소스 (Resource) | 설명 (Description) | 링크 (Link) |
|---|---|---|
| Agent 365 Observability | 에이전트를 위한 통합 텔레메트리 (OTel 기반) | [Docs] |
| AI Foundry Observability | Foundry에서의 트레이싱 (Tracing) 및 모니터링 | [Docs] |
| Azure Monitor | Azure를 위한 풀스택 모니터링 | [Docs] |
| Application Insights | AI 애플리케이션을 위한 APM | [Docs] |
| OpenTelemetry Integration | 에이전트를 위한 분산 트레이싱 (Distributed tracing) | [Agent Framework Observability] |
🔒 보안 및 거버넌스 (Security & Governance)
| 리소스 (Resource) | 설명 (Description) | 링크 (Link) |
|---|---|---|
| AI Agent Governance (CAF) | 조직 전반의 거버넌스 및 보안 | [Docs] |
| Foundry Agent Governance | AI Foundry에서의 에이전트 도구 거버넌스 | [Docs] |
| Microsoft Purview | 데이터 거버넌스 및 컴플라이언스 (Compliance) | [Docs] |
| Azure AI Content Safety | 유해 콘텐츠 탐지 | [Docs] |
| Microsoft Defender for Cloud | 보안 태세 관리 (Security posture management) | [Docs] |
| Azure Policy for AI | AI 서비스를 위한 거버넌스 정책 | [Docs] |
🔐 ID 및 액세스 (Identity & Access)
| 리소스 (Resource) | 설명 (Description) | 링크 (Link) |
|---|---|---|
| Foundry Authentication | AI Foundry에서의 인증 (Authentication) 및 인가 (Authorization) | [Docs] |
| Microsoft Entra ID | ID 및 액세스 관리 (Identity and access management) | |
| Managed Identity | 자격 증명이 필요 없는 인증 (Credential-free authentication) | [Docs] |
| Azure Key Vault | 비밀(Secrets), 키(Keys) 및 인증서(Certificates) | [Docs] |
| RBAC for AI Services | 역할 기반 액세스 제어 (Role-based access control) | [Docs] |
📊 관리 및 운영 (Management & Operations)
| 리소스 (Resource) | 설명 (Description) | 링크 (Link) |
|---|---|---|
| Azure Resource Manager | 인프라 관리 | [Docs] |
| Azure Bicep | 코드형 인프라 (Infrastructure as Code) | [Docs] |
| Terraform for Azure | 멀티 클라우드 IaC | [Registry] |
| Azure Cost Management | 비용 모니터링 및 최적화 | [Docs] |
🐙 AI를 위한 GitHub DevOps
| 리소스 (Resource) | 설명 (Description) | 링크 (Link) |
|---|---|---|
| GitHub Actions for Azure | Azure를 위한 CI/CD 워크플로 | [Marketplace] |
| GitHub Copilot SDK | 개발자 도구에 Copilot 임베딩 | [GitHub] |
| Azure Developer CLI (azd) | 엔드 투 엔드 배포 자동화 | [Docs] |
| GitHub Codespaces | 클라우드 개발 환경 | [Docs] |
| Copilot for Azure | AI 지원 Azure 관리 | [Docs] |
📐 아키텍처 참조 (Architecture References)
| 리소스 (Resource) | 설명 (Description) | 링크 (Link) |
|---|---|---|
| Azure Architecture Center | 27개 이상의 AI/ML 참조 아키텍처 (Reference Architectures) | 찾아보기 (Browse) |
| Well-Architected Framework | AI 워크로드 베스트 프랙티스 (Best Practices) | [Docs] |
| Cloud Adoption Framework | AI 도입 가이드라인 (Guidance) | [Docs] |
| 가이드 (Guide) | 설명 (Description) |
|---|---|
| 🆕 시작하기 (Getting Started) | 단계별 초보자 학습 경로 (약 50분 소요) |
| 아키텍처 베스트 프랙티스 (Architecture Best Practices) | 참조 아키텍처 및 디자인 패턴 (Design Patterns) |
| 에이전트 개발 (Agent Development) | 에이전트 구축을 위한 베스트 프랙티스 |
| 프로덕션 배포 (Production Deployment) | AI 애플리케이션의 프로덕션 환경 배포 |
| ... | |
| 원칙 (Principle) | 설명 (Description) |
| --- | --- |
| 🔒 보안 우선 (Security First) | 기본적으로 프라이빗 엔드포인트 (Private Endpoints), 관리 ID (Managed Identities), RBAC 적용 |
| 📈 확장성 (Scalability) | Azure Container Apps 또는 AKS를 통한 수평적 확장 (Horizontal Scaling) 설계 |
| 🔄 회복 탄력성 (Resilience) | 재시도 정책 (Retry Policies), 서킷 브레이커 (Circuit Breakers), 우아한 성능 저하 (Graceful Degradation) 구현 |
| 👁️ 관측 가능성 (Observability) | OpenTelemetry 통합, 분산 트레이싱 (Distributed Tracing), 구조화된 로깅 (Structured Logging) |
| 💰 비용 인식 (Cost Awareness) | 리소스 적정 규모 산정 (Right-sizing), 오토스케일링 (Auto-scaling) 구현, 토큰 사용량 모니터링 |
AI 랜딩 존 (AI Landing Zone)은 기업용 AI 워크로드를 위한 기초 인프라를 제공합니다:
┌──────────────────────────────────────────────────────────────────────────┐
│ 플랫폼 랜딩 존 (Platform Landing Zone) │
│ ┌────────────────────────────────────────────────────────────────────┐ │
...
| 구성 요소 (Component) | 목적 (Purpose) |
|---|---|
| API Management (APIM) | 토큰 관리, 부하 분산 (Load Balancing), 인증 (Auth)을 위한 AI 게이트웨이 (AI Gateway) |
| Azure AI Foundry | 모델, 에이전트 (AI Agent Service) 및 도구 (Tools)를 호스팅하는 통합 플랫폼 |
| AI Agent Service | 내장된 도구 오케스트레이션 (Tool Orchestration)과 함께 Foundry 내부에서 실행되는 호스팅 에이전트 |
| Azure AI Search | RAG 및 지식 검색 (프라이빗 엔드포인트) |
| Content Safety | 유해 콘텐츠 탐지 및 필터링 |
| Storage | AI 워크로드를 위한 데이터 레이크 (Data Lake) (프라이빗 엔드포인트) |
| Key Vault | 비밀 관리 (Secrets Management) (프라이빗 엔드포인트) |
| Monitoring | 관측 가능성 (Observability) 및 로깅 |
| Networking | 프라이빗 엔드포인트 (Private Endpoints) 및 VNet |
| Defender for Cloud | 보안 태세 관리 (Security Posture Management) |
🔌 Azure AI Foundry와 함께 APIM AI Gateway를 사용해야 하는 경우
📢 새로운 소식! 이제 AI Gateway를 Microsoft Foundry에 직접 통합할 수 있어, Foundry 환경 내에서 AI 모델, 에이전트(Agents) 및 도구(Tools)를 거버넌스(Governance)할 수 있습니다.
Azure API Management (APIM)의 AI Gateway는 AI 워크로드(Workloads)를 위해 특별히 설계된 기능을 제공합니다. 다음과 같은 상황에서 사용하세요:
| 기능 | APIM AI Gateway 제공 사항 |
|---|---|
| 토큰 속도 제한 (Token Rate Limiting) | azure-openai-token-limit 정책 - 소비자, 앱 또는 팀별로 TPM(Tokens Per Minute) 제한 |
| 토큰 할당량 (Token Quotas) | 구독별 시간/일/주/월/년 단위 할당량 |
| 부하 분산 (Load Balancing) | 여러 Foundry 엔드포인트(Endpoints) 간의 라운드 로빈(Round-robin), 가중치 기반(Weighted), 우선순위 기반(Priority-based) 분산 |
| 시맨틱 캐싱 (Semantic Caching) | 의미적 유사성(Semantic similarity)을 기반으로 완료(Completions) 결과 캐싱 (비용 절감) |
| 서킷 브레이커 (Circuit Breaker) | 백엔드에서 오류를 반환하거나 과부하가 발생할 때 자동 장애 조치 (Auto-failover) |
| 콘텐츠 안전 (Content Safety) | 프롬프트(Prompts) 조절을 위해 Azure AI Content Safety 정책 적용 |
| 토큰 메트릭 (Token Metrics) | 소비자별 관찰 가능성(Observability)을 위한 llm-emit-token-metric 정책 |
| PTU 최적화 (PTU Optimization) | 종량제(Pay-as-you-go) 적용 전 프로비저닝된 처리량 단위(Provisioned Throughput Units) 우선순위 지정 |
| 시나리오 | APIM 사용 여부? | 이유 |
|---|---|---|
| 여러 앱이 AI 엔드포인트를 공유하는 경우 | ✅ 예 | 특정 앱이 모든 TPM 할당량을 소비하는 것을 방지 |
| 멀티 테넌트 SaaS (Multi-tenant SaaS) | ✅ Yes | 테넌트별 토큰 할당량 설정 및 과금을 위한 사용량 추적 |
| PTU + PAYG 하이브리드 | ✅ Yes | PTU로 우선 라우팅하고, 초과 시 종량제(Pay-as-you-go)로 전환 |
| 여러 Foundry 리전 (Regions) | ✅ Yes | 리전 간 부하 분산 및 장애 조치 (Failover) |
| 캐싱을 통한 비용 절감 | ✅ Yes | 시맨틱 캐싱(Semantic caching)을 통해 불필요한 API 호출 방지 |
| 중앙 집중식 인증 (API 키 미사용) | ✅ Yes | 관리 ID(Managed identity), OAuth를 통한 키 확산 방지 |
| 단일 내부 앱, 직접 액세스 | - | 지연 시간(Latency) 추가; 직접 Foundry에 액세스하는 것으로 충분할 수 있음 |
| 프로토타입 / 개발 환경 | ❌ 아니요 | 초기 단계에서는 불필요한 복잡성 유발 |
📖
더 알아보기:
🚀 엔터프라이즈 AI 랜딩 존(Landing Zone)을 배포할 준비가 되셨나요?
| Enterprise Bicep/Terraform | Full Stack (~45 min) | Reference Patterns |
Microsoft Agent Framework
# pip install agent-framework --pre
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import DefaultAzureCredential
...
Azure AI Foundry SDK (호스팅 에이전트)
# pip install azure-ai-projects azure-identity openai
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
...
Azure Developer CLI를 이용한 배포
# 프로덕션 가속기 클론
git clone --recurse-submodules \
...
# 이 레포지토리에서
cd infra/bicep
az deployment group create -g myRG -f main.bicep -p principalId=$(az ad signed-in-user show --query id -o tsv)
프로덕션에 배포하기 전에:
DefaultAzureCredential사용 (API 키 없음) - 프라이빗 엔드포인트 활성화- 모든 비밀 정보는 Key Vault 사용
- 최소 권한을 가진 RBAC(Role-Based Access Control)
- 진단 로깅(Diagnostic logging) 활성화
- Content Safety 통합
기여를 환영합니다! 자세한 내용은 기여 가이드(Contributing Guide)를 참조하세요.
# 빠른 기여 워크플로우
git checkout -b feature/my-feature
# 변경 사항 적용
...
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 확인하세요.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기