microsoft-foundry

개요

microsoft-foundry 스킬은 무엇인가요?

microsoft-foundry 스킬은 Azure AI Foundry 에이전트의 전체 수명주기를 안내하는 워크플로와 레퍼런스 문서를 모아 정리한 패키지입니다. 실제 배포와 운영에 바로 쓸 수 있는 내용을 중심으로 구성되어 있습니다.

• prompt 및 hosted 에이전트 생성
• Docker 이미지를 빌드하고 **Azure Container Registry (ACR)**에 푸시
• Azure AI Foundry로 에이전트 배포
• projects, RBAC, quota, connections 구성
• evaluation datasets 실행 및 agent-metadata.yaml 관리
• standard 및 private-network 에이전트 구성 설정
• observability, tracing, troubleshooting 활성화

모든 콘텐츠는 microsoft/azure-skills 리포지토리에서 제공되며, 리포지토리 구조를 역추적할 필요 없이 Azure AI Foundry에서 에이전트를 운영 환경에 올릴 수 있도록 체계적으로 정리되어 있습니다.

이 스킬은 누구를 위한 것인가요?

다음과 같은 경우 microsoft-foundry를 사용하는 것이 좋습니다.

• Azure AI Foundry 에이전트 배포와 운영을 담당하는 백엔드/플랫폼 엔지니어
• 프로토타입을 Foundry 프로젝트의 운영 환경으로 이전하려는 AI/ML 엔지니어
• 기존 서비스, SDK, MCP 도구와 Foundry 에이전트를 통합하려는 개발자
• RBAC, 쿼터, 프라이빗 네트워크, 환경 구성을 책임지는 기술 오너(Technical Owner)

App Service, Functions, 일반 웹 앱 수준의 기본적인 Azure 인프라 배포만 필요하다면, 이 스킬은 적합하지 않습니다. 더 범용적인 Azure 배포 스킬을 사용하세요.

microsoft-foundry는 어떤 문제를 해결하나요?

이 스킬은 다음과 같은 반복적으로 등장하는 과제를 해결하도록 설계되었습니다.

• "Foundry용 에이전트 리포지토리는 어떻게 구조를 잡아야 하나요?"
  .foundry/ 레이아웃과 agent-metadata.yaml 필드에 대한 안내는 references/agent-metadata-contract.md를 참고하세요.

• "에이전트를 일관되게 생성·배포하려면 어떻게 해야 하나요?"
  foundry-agent/create 및 foundry-agent/deploy 워크플로를 사용해 prompt/hosted 에이전트를 만들고, 컨테이너를 빌드해 ACR에 푸시한 뒤 에이전트 컨테이너를 시작할 수 있습니다.

• "projects, connections, RBAC, quota는 어떻게 설정해야 하나요?"
  project/create, rbac/rbac.md, quota/quota.md를 참고해 프로젝트를 생성하고, 역할을 할당하고, 용량 계획을 수립하세요.

• "에이전트를 어떻게 평가하고 모니터링할 수 있나요?"
  foundry-agent/eval-datasets, foundry-agent/observe, foundry-agent/trace를 사용해 배치 평가를 수행하고, 데이터셋과 evaluator를 관리하며, Observability 리소스에 연결할 수 있습니다.

• "standard 구성과 private-network 구성은 어떻게 선택하고 설정하나요?"
  references/standard-agent-setup.md와 references/private-network-standard-agent-setup.md를 참고해 환경에 맞는 네트워크 모델을 선택하고 구성하세요.

언제 microsoft-foundry를 사용하면 좋나요?

다음과 같은 경우 이 스킬 사용을 권장합니다.

• Azure AI Foundry에 prompt 또는 hosted 에이전트를 배포해야 할 때
• .foundry/agent-metadata.yaml을 사용해 에이전트 프로젝트 구조를 표준화하려 할 때
• MCP 도구 및 Azure SDK를 재사용 가능한 워크플로에 통합하고 싶을 때
• 에이전트 워크로드의 RBAC, 쿼터, 용량 계획을 관리해야 할 때
• evaluation datasets를 실행하고 환경별 결과를 추적하고자 할 때
• Application Insights와 traces를 사용해 observability를 구축하고자 할 때
• standard 또는 private-network(VNet) 구성으로 배포해야 할 때

다음과 같은 경우에는 이 스킬 사용을 권장하지 않습니다.

• 일반적인 Azure 앱 배포(웹 앱, Functions, App Service)만 필요한 경우
• Azure 계정/구독 준비 수준의 고수준 가이드만 필요한 경우

이러한 상황에서는 일반적인 Azure 배포/준비 스킬과 함께 사용하거나 azure-deploy / azure-prepare 같은 전용 스킬을 사용하는 것이 더 적합합니다.

사용 방법

설치

microsoft/azure-skills 리포지토리에서 microsoft-foundry를 추가하려면 다음 명령으로 설치하세요.

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

설치를 마치면 microsoft-foundry의 워크플로와 레퍼런스 콘텐츠를 에이전트 또는 도구 환경에서 사용할 수 있습니다. 설치 후 주 진입점은 skills/microsoft-foundry 폴더의 SKILL.md입니다.

리포지토리 레이아웃 및 주요 폴더

스킬을 설치하거나 리포지토리에서 열어 보면 다음과 같은 구조를 확인할 수 있습니다.

• SKILL.md – 최상위 스킬 인덱스 및 하위 스킬 목록
• foundry-agent/ – 개별 에이전트에 대한 엔드 투 엔드 워크플로
  • create/ – prompt 또는 hosted 에이전트 생성
  • deploy/ – 에이전트(컨테이너 및 ACR 포함) 빌드 및 배포
  • eval-datasets/ – 평가 데이터셋 및 평가 실행 관리
  • invoke/ – 기존 에이전트 호출
  • observe/ – 관측 및 모니터링 워크플로 설정
  • trace/ – 트레이스 수집 및 트레이스로부터 데이터셋 생성
  • troubleshoot/ – 실패한 실행에 대한 트러블슈팅 가이드
• project/
  • create/ – Azure AI Foundry 프로젝트 생성 및 구성
  • connections.md – 프로젝트 수준 connections 가이드
• rbac/
  • rbac.md – RBAC 역할, 권한, 공통 패턴
• quota/
  • quota.md – 쿼터 및 용량 계획 가이드
  • references/ – 용량 계획, 오류 해결, 최적화 자료
• references/
  • agent-metadata-contract.md – .foundry/ 레이아웃 및 agent-metadata.yaml
  • auth-best-practices.md – Azure 인증 패턴 및 RBAC
  • standard-agent-setup.md – 표준(비격리) 에이전트 구성
  • private-network-standard-agent-setup.md – VNet/private-link 구성
  • sdk/ – MCP 도구를 사용할 수 없을 때 참고할 SDK 기반 운영 레퍼런스

먼저 SKILL.md에서 하위 스킬 구성을 파악한 다음, 필요한 시나리오 폴더로 들어가면 됩니다.

빠른 시작 워크플로: 프로젝트에서 배포된 에이전트까지

이 섹션은 microsoft-foundry 스킬 콘텐츠를 활용하는 실질적인 진행 경로를 제시합니다.

1. Foundry 프로젝트 생성 또는 준비

1. project/create/create-foundry-project.md를 엽니다.
2. 다음 단계를 순서대로 수행합니다.
   • Azure AI Foundry 프로젝트 생성
   • 프로젝트 엔드포인트 확인(예: https://<resource>.services.ai.azure.com/api/projects/<project>)
   • 표준 구성에 필요한 connections(Cosmos DB, Storage, Azure AI Search 등)를 연결
3. project/connections.md를 검토하여 thread storage, file storage, vector store connections가 올바르게 구성되어 있는지 확인합니다. 특히 standard agent setup을 사용할 계획이라면 중요합니다.

2. RBAC 및 인증 구성

1. rbac/rbac.md를 읽고 다음을 확인합니다.
   • 리소스 그룹 및 Foundry 리소스에 필요한 역할(Owner, Contributor, User Access Administrator 등)
   • Azure RBAC 모범 사례에 따라 역할을 할당하는 방법
2. references/auth-best-practices.md를 열고 다음 권장 사항을 적용합니다.
   • 운영 환경에서는 managed identities와 Azure RBAC 사용
   • 로컬 개발 환경에만 DefaultAzureCredential 사용 제한
   • 운영, CI/CD, 개발 환경별로 적절한 credential 타입 선택

이를 통해 하드 코딩된 시크릿 없이도 배포와 에이전트 운영에 필요한 인증을 안정적으로 구성할 수 있습니다.

3. Basic / Standard / Private-network 구성 선택

1. references/standard-agent-setup.md를 열어 다음을 이해합니다.
   • Basic과 Standard 구성의 차이점
   • standard 구성에 필요한 connections: Cosmos DB, Azure Storage, Azure AI Search, 필요 시 Azure AI Services
   • 리소스 그룹에 대한 RBAC 역할 등 선행 조건
2. 완전한 네트워크 격리가 필요하다면 references/private-network-standard-agent-setup.md를 읽습니다.
   • VNet 및 서브넷(에이전트 서브넷, private endpoint 서브넷) 요구 사항
   • Foundry 리소스와 VNet 간의 리전 정렬
   • private-network standard agent setup을 위한 공식 Bicep 템플릿 사용 방법

에이전트를 만들기 전에 컴플라이언스와 네트워크 요구사항에 맞는 구성을 결정해 두는 것이 좋습니다.

4. 에이전트 프로젝트 레이아웃 표준화

1. references/agent-metadata-contract.md를 열고 프로젝트 구조를 문서에 맞춰 정리합니다.

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. agent-metadata.yaml에 다음과 같은 환경 정의 필드를 포함했는지 확인합니다.

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (hosted 에이전트용)
   • environments.<name>.observability.* (Application Insights용)
   • environments.<name>.testCases[] (evaluation 번들용)

이 파일은 환경별 설정에 대한 단일 소스 오브 트루스 역할을 하며, 나머지 microsoft-foundry 워크플로는 이 파일이 존재하고 정확히 구성되어 있다고 가정합니다.

5. Prompt 또는 Hosted 에이전트 생성

1. prompt 에이전트의 경우, foundry-agent/create/create-prompt.md를 엽니다.

   • prompt 에이전트와 workflow의 차이 이해
   • 프로젝트 컨텍스트(엔드포인트, credentials)를 확인하는 단계 수행
   • MCP 도구가 있는 경우 우선 사용하고, 문서에 따라 azure-ai-projects SDK로 폴백
   • 에이전트 이름, 모델 배포, instructions 및 선택적 도구(file search, code interpreter 등)를 설정

2. hosted 에이전트의 경우, foundry-agent/create/create.md를 엽니다.

   • 신규 에이전트(greenfield)를 만들지, 기존 프로젝트(brownfield)를 변환할지 결정
   • 제공된 샘플 경로를 기준으로 프레임워크와 언어 선택(Python 또는 C# 기반 Microsoft Agent Framework, LangGraph 등)
   • 필요 시 foundry-samples 리포지토리와 연동하는 방법을 참고

이 단계를 마치면 Foundry에 배포 가능한 형태의 에이전트 프로젝트가 준비되어 있어야 합니다.

6. 에이전트 빌드 및 배포

1. foundry-agent/deploy/deploy.md를 엽니다.
2. 다음을 포함하는 워크플로를 순서대로 따릅니다.
   • 프로젝트 스캔 및 환경 변수 수집
   • hosted 에이전트용 Dockerfile 생성과 docker / az acr 사용
   • agent_update, agent_container_control, agent_container_status_get 같은 MCP 도구 사용
   • 배포 생성/업데이트 및 에이전트 컨테이너 시작/중지
3. 이 가이드를 검토하지 않은 상태에서 azd up, azd deploy, az acr build, docker build를 개별적으로 실행하지 마세요. 이 스킬은 이러한 명령을 하나의 완결된 배포 파이프라인 안에서 조율하도록 설계되어 있습니다.

이 단계를 완료하면 에이전트가 Azure AI Foundry를 통해 배포되어 액세스 가능한 상태가 됩니다.

7. 에이전트 호출 및 테스트

1. foundry-agent/invoke/invoke.md를 엽니다.
2. 문서화된 패턴에 따라 다음을 수행합니다.
   • agent-metadata.yaml에서 올바른 환경과 엔드포인트를 해석
   • 샘플 또는 커스텀 payload로 에이전트를 호출
   • 응답, 도구 호출, 상태 관리가 예상대로 동작하는지 확인

본격적인 평가 스위트를 실행하기 전에 간단한 스모크 테스트를 수행하기에 좋은 단계입니다.

8. 평가 및 반복 개선

1. foundry-agent/eval-datasets/eval-datasets.md를 엽니다.
2. 다음 가이드를 참고해 작업을 진행합니다.
   • .foundry/datasets와 .foundry/evaluators 아래에서 데이터셋과 evaluator 관리
   • agent-metadata.yaml의 testCases 정의를 사용해 평가 워크플로 실행
   • .foundry/results에 출력 결과를 저장하고 환경 또는 에이전트 버전 별로 비교
3. prompt나 instructions를 반복적으로 개선하고 평가를 재실행해, 시간에 따른 성능 향상을 추적합니다.

Observability, Tracing, Troubleshooting

Observability 및 모니터링

1. foundry-agent/observe/observe.md를 엽니다.
2. 다음 가이드에 따라 observability를 구성합니다.
   • agent-metadata-contract.md에서 설명하는 resource ID 및 connection string 필드를 사용해 Application Insights 연결
   • 지연 시간, 오류, 처리량을 모니터링하기 위한 권장 대시보드나 쿼리 활용

이를 통해 운영 환경의 동작을 모니터링하고, 배포 변경 사항과 연계해 분석할 수 있습니다.

트레이싱 및 트레이스로부터 데이터셋 생성

1. foundry-agent/trace/trace.md를 엽니다.
2. 문서화된 워크플로를 통해 다음을 수행합니다.
   • 에이전트에서 트레이스 수집
   • 트레이스로부터 데이터셋을 큐레이션하고 .foundry/datasets에 저장
   • 이 데이터셋을 평가 워크플로에 연결해, 실제 트래픽에 가까운 테스트 수행

실제 사용자 트래픽을 평가 시나리오로 전환하고자 할 때 특히 유용합니다.

배포 및 런타임 이슈 트러블슈팅

1. foundry-agent/troubleshoot/troubleshoot.md를 엽니다.
2. 다음과 같은 문제 유형에 대한 트러블슈팅 가이드를 따릅니다.
   • 배포 실패 및 컨테이너 시작 오류
   • 엔드포인트, credentials, connections 오구성
   • 쿼터 또는 용량 관련 오류(quota/quota.md 및 quota/references/*.md와 교차 참고)

로그와 Application Insights 텔레메트리와 함께 이 문서를 참고하면 문제를 진단하고 해결하는 데 도움이 됩니다.

쿼터, 용량, 최적화

1. quota/quota.md를 열어 다음 내용을 개략적으로 파악합니다.
   • Azure AI Foundry에서 모델 및 배포에 쿼터가 어떻게 적용되는지
   • 환경 및 리전 간 용량을 어떻게 설계해야 하는지
2. quota/references/ 내 파일을 검토합니다.
   • capacity-planning.md – 에이전트 사용량에 기반한 용량 추정 방법
   • error-resolution.md – 자주 발생하는 쿼터 관련 오류와 권장 해결책 매핑
   • optimization.md – 쿼터 범위 내에서 워크로드를 튜닝하는 방법 제안

이 콘텐츠를 활용하면 규모가 커졌을 때 갑작스러운 성능 저하나 실패를 줄이고, 에이전트 응답성을 유지할 수 있습니다.

FAQ

Azure AI Foundry를 사용하려면 microsoft-foundry가 반드시 필요한가요?

필수는 아닙니다. Azure 포털, CLI, SDK만으로도 Azure AI Foundry를 직접 사용할 수 있습니다. microsoft-foundry 스킬은 프로젝트, 에이전트, 환경을 보다 일관되게 설정할 수 있도록 모범 사례와 워크플로, 레퍼런스를 한곳에 모아 제공하는 구조화된 가이드입니다.

microsoft-foundry를 Foundry 이외의 Azure 서비스에도 사용할 수 있나요?

이 스킬은 Azure AI Foundry 에이전트와 프로젝트를 배포·운영하는 것이 주된 목적일 때 사용하는 것이 좋습니다. 웹 앱, API, 기타 PaaS 서비스(App Service, Functions, 일반 컨테이너 등)를 일반적으로 배포하려면, 별도의 Azure 배포 스킬이나 가이드를 사용하는 편이 더 적합합니다.

microsoft-foundry는 prompt 에이전트와 hosted 에이전트를 모두 지원하나요?

네. 이 스킬에는 두 유형 모두에 대한 전용 콘텐츠가 포함되어 있습니다.

• foundry-agent/create/create-prompt.md – prompt 에이전트 관련 가이드
• foundry-agent/create/create.md, foundry-agent/deploy/deploy.md – 컨테이너화, ACR, 컨테이너 수명 주기 관리를 포함한 hosted 에이전트 관련 가이드

microsoft-foundry는 인증과 보안을 어떻게 다루나요?

보안과 인증은 references/auth-best-practices.md, rbac/rbac.md에서 다룹니다.

• 운영 환경에서는 managed identities와 Azure RBAC 사용
• 로컬 개발에는 DefaultAzureCredential을 제한적으로 사용
• CI/CD 및 온프레미스 환경에 적합한 credential 선택

SDK나 MCP 도구를 연결하기 전에 이 문서를 먼저 참고하면 불안정하거나 보안에 취약한 구성을 피할 수 있습니다.

MCP 도구를 꼭 써야 하나요, 아니면 SDK만으로도 충분한가요?

이 콘텐츠는 MCP 도구를 사용할 수 있을 때는 MCP를 활용하고, 그렇지 않을 때는 SDK 기반 폴백을 사용할 수 있도록 작성되어 있습니다. 예를 들어 create-prompt.md에서는 MCP 도구가 없는 경우 azure-ai-projects SDK를 기본 옵션으로 사용하는 방법을 설명합니다.

내 에이전트 프로젝트 구조가 올바른지 어떻게 확인할 수 있나요?

references/agent-metadata-contract.md와 프로젝트를 비교해 보세요. 다음 사항을 충족해야 합니다.

• 에이전트 루트에 .foundry/ 디렉터리가 존재
• 환경 및 테스트 케이스를 포함한 유효한 agent-metadata.yaml
• 문서에 설명된 datasets/, evaluators/, results/ 폴더

이 계약을 지키면 나머지 microsoft-foundry 워크플로는 프로젝트 레이아웃과 자연스럽게 호환됩니다.

microsoft-foundry를 프라이빗 네트워크(VNet) 구성과 함께 사용할 수 있나요?

네. references/private-network-standard-agent-setup.md에서 다음 사항을 자세히 안내합니다.

• 필요한 VNet 및 서브넷 구성
• Foundry 리소스와 VNet 간 리전 제약 사항
• private-network standard agent setup용 공식 Bicep 템플릿 사용 방법

트래픽을 프라이빗 네트워크 내에 유지해야 하는 경우 references/standard-agent-setup.md와 함께 이 문서를 참고하세요.

설치 후 리포지토리에서 어디부터 시작해야 하나요?

스킬 설치를 마친 뒤에는 다음 순서로 진행하는 것을 권장합니다.

1. SKILL.md – 전체 하위 스킬에 대한 상위 개요 확인
2. project/create/create-foundry-project.md – Foundry 프로젝트 설정
3. references/agent-metadata-contract.md – 에이전트 레이아웃 표준화
4. foundry-agent/create/ 및 foundry-agent/deploy/ – 첫 번째 에이전트를 빌드하고 배포

그 이후에는 시나리오에 따라 eval-datasets, observe, trace, rbac, quota 폴더를 차례로 살펴보면 됩니다.