빠른 시작: 첫 번째 호스팅 에이전트 배포

• Azure 개발자 CLI 버전 1.24.0 이상

• Visual Studio Code
• Microsoft Visual Studio Code 확장용 Foundry 도구 키트

필요한 권한

호스트된 에이전트를 만들고 배포하려면 project 범위에서 AZURE AI Project Manager가 필요합니다. 이 역할에는 에이전트를 만들기 위한 데이터 평면 권한과 Azure AI 사용자 역할을 플랫폼에서 만든 에이전트 ID에 할당하는 기능이 모두 포함됩니다. 에이전트 ID는 프로젝트의 AZURE AI 사용자가 런타임에 모델 및 아티팩트 액세스에 필요합니다.

azd 또는 VS Code 확장을 사용하는 경우 도구는 다음을 포함하여 대부분의 RBAC 할당을 자동으로 처리합니다.

Foundry Project의 관리 ID가 사용하는 Azure Container Registry에 ACR Pull 권한이 있는지 확인하십시오. 소유자 또는 "사용자 액세스 관리자" 액세스 권한을 선호하고 사용하는 경우 도구 azd/vscode도 이 할당을 수행할 수 있습니다. 플랫폼에서 생성된 에이전트 식별자를 위한 Azure AI 사용자 (런타임 모델 및 도구 액세스)

1단계: 샘플 프로젝트 설정

Azure 개발자 CLI 에이전트 확장을 설치하고 호스트된 새 에이전트 프로젝트를 초기화합니다.

1. Azure Developer CLI에 대한 ai agent 확장을 설치합니다.

   azd ext install azure.ai.agents
   

   확장이 설치되어 있는지 확인하려면 다음을 실행합니다.

   azd ext list
   

2. 빈 디렉터리에서 호스트된 새 에이전트 프로젝트를 초기화합니다.

   azd ai agent init
   

   대화형 흐름은 다음 구성을 안내합니다.

   • Language — C# 또는 Python 샘플 코드를 사용할 프로그래밍 언어를 선택합니다.
   • 에이전트 템플릿 - 시작할 샘플을 선택합니다.
   • 모델 구성 - Foundry에 새 모델을 배포하거나 기존 Foundry Project 기존 모델을 사용하도록 선택합니다.
   • Azure 구독 — Foundry 리소스를 생성할 구독을 선택합니다.
   • 위치 - 리소스의 지역을 선택합니다.
   • 모델 SKU - 지역 및 구독에 사용할 수 있는 SKU를 선택합니다.
   • 배포 이름 - 모델 배포의 이름을 입력합니다.
   • 컨테이너 크기 - CPU 및 메모리 할당을 선택하거나 기본값을 적용합니다.

   중요

   도구를 사용하여 샘플을 선택했고 MCP 서버를 사용하지 않는 경우 파일에서 agent.yaml 다음 줄을 주석으로 처리하거나 제거합니다.

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   팁

   대화형이 아닌 환경, 예를 들어 CI/CD 파이프라인 또는 SSH 세션에서 실행 중인 경우 --no-prompt 플래그와 azd ai agent init를 사용합니다. 또한 대화형 프롬프트에 응답하는 대신 모든 필수 값을 명령줄 플래그로 제공해야 합니다.

3. 필요한 Azure 리소스를 프로비전합니다.

   참고

   리소스 프로비저닝을 위해 Azure 구독에서 Contributor 액세스 권한이 필요합니다.

   azd provision
   

   이 명령은 몇 분 정도 걸리며 다음 리소스를 만듭니다.

   리소스	목적	비용
   리소스 그룹	동일한 영역에서 관련된 모든 리소스를 구성합니다.	비용 없음
   모델 배포	에이전트에서 사용하는 모델	Foundry 가격 책정을 참조하세요
   Foundry 프로젝트	에이전트를 호스트하고 AI 기능을 제공합니다.	소비 기반 모델로 Foundry 가격 책정을 참조하십시오.
   Azure 컨테이너 레지스트리	에이전트 컨테이너 이미지를 저장합니다.	기본 계층; ACR 가격 책정 참조
   Log Analytics 작업 영역	한 곳에서 모든 로그 데이터 관리	직접 비용 없음. Log Analytics 비용
   Application Insights	에이전트 성능 및 로그 모니터링	종량제; Azure Monitor 가격 책정을 참조하세요.
   관리형 아이덴티티	Azure 서비스에 대한 에이전트 인증	비용 없음

   팁

   이 빠른 시작을 완료하면 실행 azd down 하여 리소스를 삭제하고 요금 발생을 중지합니다.

2단계: 에이전트를 로컬로 테스트

배포하기 전에 에이전트가 로컬에서 작동하는지 확인합니다.

1. 에이전트를 로컬로 시작합니다.

   azd ai agent run
   

   이 명령은 자동으로 환경을 설정하고, 종속성을 설치하고, 에이전트를 시작합니다. azure.yaml에서 정의된 startupCommand을 사용하여 에이전트를 시작합니다.

   참고

   미리 보기 패키지는 설치 중에 pip 종속성 버전 충돌 경고를 생성할 수 있습니다. 이러한 경고는 비차단적입니다. 에이전트는 이 경고에도 불구하고 시작하고 올바르게 응답합니다.

   에이전트가 시작되지 않으면 다음과 같은 일반적인 문제를 확인하십시오.

   오류	솔루션
   AuthenticationError 또는 DefaultAzureCredential 실패	azd auth logout을 실행한 다음 azd auth login을 실행하여 세션을 새로 고치십시오.
   ResourceNotFound	엔드포인트 URL이 Foundry 포털의 값과 일치하는지 확인합니다.
   DeploymentNotFound	빌드>배포에서 배포 이름을 확인합니다.
   Connection refused	포트 8088을 사용하는 다른 프로세스가 없는지 확인합니다.

2. 별도의 터미널에서 로컬 에이전트에 테스트 메시지를 보냅니다.

   응답 API를 사용하는 에이전트의 경우 문자열을 페이로드로 보낼 수 있습니다.

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   호출 API를 사용하는 에이전트는 README.md에서 예상 페이로드를 확인하십시오. 샘플에는 일반적으로 JSON 페이로드가 필요하지만 특정 예제에 대한 해당 샘플의 README.md 내용을 검토합니다.

   에이전트의 응답이 표시됩니다.

3단계: Foundry 에이전트 서비스에 배포

1단계에서 인프라를 이미 프로비전했으므로 Azure 에이전트 코드를 배포합니다.

azd deploy

에이전트 컨테이너는 원격으로 빌드되므로 컴퓨터에 Docker Desktop이 필요하지 않습니다.

완료되면 출력에는 에이전트 플레이그라운드에 대한 링크와 에이전트를 프로그래밍 방식으로 호출하기 위한 엔드포인트가 표시됩니다.

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

1단계: Foundry 프로젝트 만들기

VS Code에서 Microsoft Foundry 도구 키트 확장을 사용하여 새 Microsoft Foundry Project 리소스를 만듭니다.

1. 명령 팔레트(Ctrl+Shift+P)를 열고 Microsoft Foundry: Project 선택합니다.

2. Azure 구독을 선택합니다.

3. 새 리소스 그룹을 만들거나 기존 리소스 그룹을 선택합니다.

4. Foundry Project 리소스의 이름을 입력합니다.

프로젝트 만들기가 완료되면 다음 단계로 계속 진행하여 모델을 배포합니다.

2단계: 모델 배포

VS Code에서 Microsoft Foundry 도구 키트 확장을 사용하여 Foundry에 모델을 배포합니다.

1. 명령 팔레트(Ctrl+Shift+P)를 열고 Microsoft Foundry: 모델 카탈로그 열기 선택합니다.

2. 모델 카탈로그를 찾아보거나 gpt-4.1을 검색하고 배포 단추를 선택합니다.

3. 모델 배포 페이지에서 Microsoft Foundry에 배포 단추를 선택합니다.

모델이 성공적으로 배포되면 다음 단계로 이동하여 호스트된 에이전트 프로젝트를 만듭니다.

3단계: 호스트된 에이전트 프로젝트 만들기

VS Code에서 Microsoft Foundry Toolkit 확장을 사용하여 호스트된 새 에이전트 프로젝트를 스캐폴드합니다.

1. 명령 팔레트(Ctrl+Shift+P)를 열고 Microsoft Foundry: 새 호스트된 에이전트 만들기 선택합니다.

2. 사용할 프레임워크를 선택합니다.

3. 프로그래밍 언어, Python 또는 C#을 선택합니다.

4. 응답 API 또는 API 호출을 선택합니다.

5. 사용하려는 샘플 코드를 선택합니다.

6. 프로젝트 파일을 저장할 폴더를 선택합니다.

7. 호스트된 에이전트의 이름을 입력합니다.

새 에이전트 프로젝트 폴더를 활성 작업 영역으로 사용하여 새 VS Code 창이 시작됩니다.

4단계: 종속성 설치

가상 환경을 사용하여 프로젝트 종속성을 격리하는 것이 좋습니다.

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows(PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

종속성 설치

pip를 사용하여 필요한 Python 종속성을 설치합니다.

pip install -r requirements.txt

필요한 패키지 목록은 requirement.txt 참조하세요.

5단계: 에이전트를 로컬로 테스트

배포하기 전에 에이전트를 실행하고 테스트합니다.

옵션 1: F5 키를 누릅니다(권장)

VS Code에서 F5 키를 눌러 디버깅을 시작합니다. 또는 VS Code 디버그 메뉴를 사용할 수 있습니다.

1. 실행 및 디버그 보기 열기(Ctrl+Shift+D / Cmd+Shift+D)
2. 드롭다운에서 "로컬 워크플로 HTTP 서버 디버그" 를 선택합니다.
3. 녹색 디버깅 시작 단추를 클릭하거나 F5 키를 누릅니다.

이렇게 하면:

1. 디버깅을 사용하도록 설정된 HTTP 서버 시작
2. 대화형 테스트를 위해 Foundry 도구 키트 에이전트 검사기 열기
3. 중단점을 설정하고 워크플로를 검사할 수 있습니다.

옵션 2: 터미널에서 실행

HTTP 서버로 실행(기본값):

python main.py

그러면 호스팅 에이전트가 로컬에서 http://localhost:8088/에 시작됩니다.

PowerShell(Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl(Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

에이전트는 이 도구를 사용하여 get_available_hotels 조건과 일치하는 사용 가능한 호텔을 검색합니다.

6단계: Foundry 에이전트 서비스에 배포

VS Code에서 직접 에이전트를 배포합니다.

1. 명령 팔레트(Ctrl+Shift+P)를 열고 Microsoft Foundry: 호스트된 에이전트 배포를 선택합니다.

2. "기본 ACR"을 선택합니다.

3. 호스트된 에이전트 컨테이너에 대한 CPU 및 메모리 구성을 선택합니다.

왼쪽의 아이콘을 선택하여 Microsoft Foundry 도구 키트 탐색기로 전환합니다. 에이전트는 배포가 완료된 후 호스트된 에이전트(미리 보기) 트리 뷰 사이드바에 표시됩니다.

에이전트 상태 확인

에이전트의 상태를 확인하여 실행 중인지 확인합니다.

1. 호스트된 에이전트(미리 보기) 트리 보기에서 호스트된 에이전트를 선택합니다.

2. 방금 배포한 에이전트 선택

세부 정보 페이지에는 컨테이너 세부 정보 섹션 아래의 상태가 표시됩니다.

VS Code를 사용하여 플레이그라운드에서 테스트

Microsoft VS Code용 Foundry 도구 키트에는 에이전트와 채팅하고 상호 작용할 수 있는 통합 플레이그라운드가 포함되어 있습니다.

1. 호스트된 에이전트(미리 보기) 트리 보기에서 호스트된 에이전트를 선택합니다.

2. 플레이그라운드 옵션을 선택하고 메시지를 입력하고 에이전트를 테스트하기 위해 보냅니다.

에이전트 상태 확인

배포된 에이전트의 상태를 확인합니다.

azd ai agent show

출력을 테이블 형식으로 표시하려면 다음을 수행합니다.

azd ai agent show --output table

프로젝트에 여러 에이전트 서비스가 있는 경우 에이전트 이름을 위치 인수로 지정합니다.

azd ai agent show <agent-name>

배포된 에이전트를 테스트 하기

이전에 사용했던 동일한 invoke 명령을 --local 플래그 없이 사용하여 배포된 에이전트에 테스트 메시지를 보냅니다.

응답 API를 사용하는 에이전트의 경우 문자열을 페이로드로 보낼 수 있습니다.

azd ai agent invoke <payload>

몇 초 후에 에이전트의 응답이 표시됩니다.

에이전트 로그 보기

에이전트의 라이브 로그를 모니터링합니다.

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

프로젝트에 여러 에이전트 서비스가 있는 경우 에이전트 이름을 위치 인수로 지정합니다.

azd ai agent monitor <agent-name> --follow

삭제할 항목을 미리 보려면 다음 명령을 실행합니다 down .

azd down

완료되면 azd 삭제될 모든 리소스를 표시하고 확인하라는 메시지를 표시합니다. yes 선택 후 계속하거나 no 취소합니다.

정리 프로세스는 약 2-5분이 걸립니다.

리소스를 삭제하려면 Azure 포털을 열고 리소스 그룹으로 이동하여 포함된 모든 리소스와 함께 삭제합니다.

에이전트의 컨테이너 로그 보기

컨테이너의 콘솔 및 시스템 로그를 확인하여 문제를 해결할 수 있습니다.

1. 호스트된 에이전트(미리 보기) 트리 보기에서 호스트된 에이전트를 선택합니다.

2. 호스트된 에이전트의 "플레이그라운드" 탭 선택

3. 세션 세부 정보에서 "로그" 섹션을 선택합니다.

에이전트의 세션 파일 보기

ADC 기반 에이전트의 홈 디렉터리에 저장된 모든 파일을 볼 수 있습니다.

1. 호스트된 에이전트(미리 보기) 트리 뷰에서 호스트된 에이전트를 선택합니다.

2. 호스트된 에이전트의 "플레이그라운드" 탭 선택

3. 세션 세부 정보에서 "파일" 섹션을 선택합니다.

현재 폴더 내에서 폴더를 다운로드, 업로드 및 만들 수 있습니다. 폴더를 클릭하면 폴더가 한 단계씩 실행되고 위쪽 탐색 모음을 클릭하면 해당 폴더로 다시 한 단계씩 이동됩니다.