실전 핸즈온 랩
Hosted Agent
실전 구축 · 배포 · 활용 가이드
Azure Developer CLI를 사용하여 Hosted Agent를 처음부터 끝까지 구축하고, 로컬에서 테스트한 후, Microsoft Foundry에 배포하여 플레이그라운드에서 대화하는 과정을 단계별로 실습합니다.
실습 개요
이 실습을 완료하면 다음을 수행할 수 있게 됩니다:
샘플 프로젝트 설정
azd CLI로 Hosted Agent 프로젝트를 초기화합니다.
로컬 테스트
배포 전에 에이전트를 로컬에서 실행하고 검증합니다.
Azure 배포
Foundry Agent Service에 컨테이너를 배포합니다.
플레이그라운드 테스트
Foundry 포털에서 에이전트와 대화합니다.
azd 설정
로컬 실행
배포
검증
활용!
Hosted Agent란?
Hosted Agent는 코드 기반 에이전트를 컨테이너 이미지로 빌드하고 Foundry Agent Service가 런타임, 스케일링, 인프라를 관리하는 방식입니다.
자세한 내용은 에이전트 유형 비교 가이드의 Hosted Agent 상세 섹션을 참고하세요.
사전 요구사항
실습을 시작하기 전에 아래 항목이 준비되어 있는지 확인하세요.
비용 주의
이 실습에서 프로비저닝되는 Azure 리소스는 과금이 발생할 수 있습니다. 실습 완료 후 반드시 리소스 정리 단계를 수행하세요.
azd down 명령으로 모든 리소스를 삭제할 수 있습니다.
환경 확인 명령어
Terminal
# Python 버전 확인 (3.10 이상 필요)
$ python3 --version
# Azure Developer CLI 버전 확인 (1.23.0 이상 필요)
$ azd version
# Azure CLI 로그인 상태 확인
$ az account show
아키텍처 이해
Hosted Agent의 배포 아키텍처를 먼저 이해하면 실습을 더 효과적으로 진행할 수 있습니다.
에이전트의 핵심 구성요소: Model + Instructions + Tools —
공식 문서
배포 시 생성되는 Azure 리소스
| 리소스 | 역할 | 비용 |
|---|---|---|
| Resource Group | 관련 리소스를 하나로 그룹화 | 무료 |
| Model Deployment | 에이전트가 사용하는 AI 모델 | Foundry 가격 |
| Foundry Project | 에이전트 호스팅 및 AI 기능 제공 | 사용량 기반 |
| Azure Container Registry | 에이전트 컨테이너 이미지 저장 | Basic 티어 |
| Application Insights | 에이전트 성능 모니터링 및 로그 | 종량제 |
| Log Analytics Workspace | 로그 데이터 통합 관리 | 무료 |
| Managed Identity | Azure 서비스 인증 | 무료 |
Agent → Conversation → Response 런타임 루프 —
Runtime Components 문서
1
샘플 프로젝트 설정
Azure Developer CLI의 ai agent 확장을 설치하고 Hosted Agent 프로젝트를 초기화합니다.
ai agent 확장 설치
Terminal
# Azure Developer CLI의 ai agent 확장 설치
$ azd ext install azure.ai.agents
# 설치 확인
$ azd ext list
프로젝트 초기화
Terminal
# 새 Hosted Agent 프로젝트 초기화
$ azd ai agent init
대화형 설정 흐름
azd ai agent init 실행 시 아래 항목을 순서대로 입력하게 됩니다:
- 템플릿 선택 → "Start new from a template" 선택
- 환경 이름 → 리소스 그룹명으로 사용됩니다 (예:
my-hosted-agent→rg-my-hosted-agent) - Azure 구독 → 리소스를 생성할 구독 선택
- 위치(리전) → 가까운 리전 선택 (예: Korea Central)
- 모델 SKU → 리전에서 사용 가능한 SKU 선택
- 배포 이름 → 모델 배포 이름 입력
- 컨테이너 크기 → CPU/메모리 할당 (기본값 권장)
MCP 서버를 사용하지 않는 경우
프로젝트의
agent.yaml 파일에서 아래 줄을 주석 처리하거나 삭제하세요:
agent.yaml
# MCP 서버 미사용 시 아래 2줄을 주석 처리 또는 삭제
# - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
# value: <CONNECTION_ID_PLACEHOLDER>
Azure 리소스 프로비저닝
Terminal
# Azure 리소스 생성 (약 5분 소요)
$ azd provision
팁
Azure 구독에 Contributor 액세스 권한이 필요합니다. 권한이 없으면 구독 관리자에게 요청하세요.
생성된 프로젝트 구조
📁 my-hosted-agent/
📁 .azure/
📁 <env-name>/
📄 .env ← 환경 변수
📄 agent.yaml ← 에이전트 매니페스트
📄 azure.yaml ← azd 서비스 구성
📄 Dockerfile ← 컨테이너 빌드 설정
📄 requirements.txt
📄 app.py ← 에이전트 코드
2
로컬에서 에이전트 테스트
Azure에 배포하기 전에 에이전트가 로컬 환경에서 정상 동작하는지 검증합니다.
에이전트 로컬 실행
Terminal 1 (에이전트 서버)
# 환경 설정, 의존성 설치, 에이전트 시작까지 자동 수행
$ azd ai agent run
예상 출력:
INFO: Started server process
INFO: Uvicorn running on http://0.0.0.0:8088 (Press CTRL+C to quit)
INFO: Application startup complete.
Hosting Adapter 동작 원리
Hosting Adapter는 에이전트 코드를 HTTP 서비스로 자동 변환하여
localhost:8088에서 REST API로 노출합니다. 대화 관리, 메시지 직렬화, 스트리밍, OpenTelemetry 관찰 가능성을 모두 자동 처리합니다.
테스트 메시지 전송
새 터미널 창을 열고 아래 명령어를 실행합니다:
Terminal 2 (테스트 클라이언트)
# azd CLI로 로컬 에이전트에 메시지 전송
$ azd ai agent invoke --local "Microsoft Foundry란 무엇인가요?"
또는 curl이나 REST 클라이언트로 직접 호출할 수 있습니다:
HTTP Request
POST http://localhost:8088/responses
Content-Type: application/json
{
"input": "서울의 현재 날씨를 알려주세요"
}
예상 응답 (JSON):
{
"id": "resp_abc123",
"object": "response",
"output": [
{
"type": "message",
"role": "assistant",
"content": "Microsoft Foundry는 AI 에이전트를 빌드, 배포, 스케일링하기 위한..."
}
],
"status": "completed"
}
로컬 실행 오류 해결
| 오류 증상 | 원인 | 해결 방법 |
|---|---|---|
AuthenticationError |
Azure 인증 만료 | azd auth login 재실행 |
ResourceNotFound |
엔드포인트 URL 불일치 | Foundry 포털에서 URL 확인 |
DeploymentNotFound |
모델 배포명 불일치 | Build > Deployments에서 이름 확인 |
Connection refused |
포트 8088 사용 중 | 다른 프로세스 종료 또는 포트 변경 |
3
Foundry Agent Service에 배포
Step 1에서 프로비저닝한 인프라에 에이전트 코드를 배포합니다. 컨테이너 이미지는 원격에서 빌드되므로 로컬에 Docker Desktop이 필요하지 않습니다.
Terminal
# 에이전트 코드를 Azure에 배포
$ azd deploy
과금 주의
배포된 Hosted Agent는 실행 중일 때 과금됩니다. 테스트가 끝나면 반드시 리소스 정리를 수행하세요.
배포 성공 시 출력:
Deploying services (azd deploy)
(✓) Done: Deploying service af-agent-with-foundry-tools
- Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/.../build?version=1
- Agent endpoint: https://ai-account-xxxx.services.ai.azure.com/api/projects/.../agents/.../versions/1
배포 완료!
위 출력에서 두 가지 중요한 URL을 확인할 수 있습니다:
- Agent playground — Foundry 포털에서 에이전트를 바로 테스트할 수 있는 URL
- Agent endpoint — 프로그래밍 방식으로 에이전트를 호출할 수 있는 REST API 엔드포인트
azd up = provision + deploy
azd up 명령어 하나로 azd provision과 azd deploy를 한 번에 실행할 수도 있습니다. 처음부터 하나의 명령으로 모든 것을 설정하고 배포하려면 azd up을 사용하세요.
4
배포 검증 및 테스트
에이전트가 Azure에서 정상 실행되는지 여러 방법으로 확인합니다.
4-1. 에이전트 상태 확인
Terminal
# 배포된 에이전트 상태 조회
$ azd ai agent show
4-2. CLI로 배포된 에이전트 테스트
Terminal
# 배포된 에이전트에 테스트 메시지 전송 (--local 플래그 없음)
$ azd ai agent invoke "Microsoft Foundry란 무엇인가요?"
4-3. 실시간 로그 모니터링
Terminal
# 에이전트의 실시간 컨테이너 로그 확인
$ azd ai agent monitor
4-4. Foundry 플레이그라운드에서 테스트
웹 기반 플레이그라운드에서 에이전트와 직접 대화할 수 있습니다. 아래 단계를 따라 진행하세요:
1. Foundry 포털 접속
ai.azure.com에 로그인합니다.
2. 프로젝트 선택
최근 프로젝트 목록 또는 "All projects"에서 프로비저닝한 프로젝트를 선택합니다.
3. 에이전트 목록 열기
왼쪽 네비게이션에서 Build를 확장하고 Agents를 클릭합니다.
4. 에이전트 선택
배포한 에이전트 이름을 클릭하여 상세 페이지로 이동합니다.
5. 플레이그라운드 열기
상단 툴바에서 "Open in playground"를 클릭합니다.
6. 대화 시작
채팅 인터페이스에 "Microsoft Foundry란 무엇인가요?"를 입력하고 응답을 확인합니다.
Foundry 포털에서 에이전트 파라미터를 구성하는 화면 예시 —
공식 문서
5
에이전트 생명주기 관리
배포된 에이전트의 시작, 중지, 업데이트, 스케일링 등 관리 작업을 수행합니다.
에이전트 시작
Terminal
$ az cognitiveservices agent start \
--account-name myAccount \
--project-name myProject \
--name myAgent \
--agent-version 1 \
--min-replicas 1 \
--max-replicas 2
에이전트 중지
Terminal
$ az cognitiveservices agent stop \
--account-name myAccount \
--project-name myProject \
--name myAgent \
--agent-version 1
스케일링 업데이트 (비버전형)
Terminal
# Replica 수 변경 (새 버전 생성 없이 업데이트)
$ az cognitiveservices agent update \
--account-name myAccount \
--project-name myProject \
--name myAgent \
--agent-version 1 \
--min-replicas 0 \
--max-replicas 3
비용 절감 팁
--min-replicas 0으로 설정하면 유휴 시 Scale-to-Zero로 비용을 절감할 수 있습니다. 단, 첫 요청 시 Cold Start가 발생하므로 지연 시간에 민감하다면 --min-replicas 1로 유지하세요.
에이전트 조회
Terminal
# 에이전트 상세 보기
$ az cognitiveservices agent show \
--account-name myAccount \
--project-name myProject \
--name myAgent
# 에이전트의 모든 버전 목록
$ az cognitiveservices agent list-versions \
--account-name myAccount \
--project-name myProject \
--name myAgent
[심화] SDK로 직접 배포하기
azd CLI 대신 Python SDK를 사용하여 에이전트를 직접 빌드·배포하는 방법입니다. CI/CD 파이프라인 통합이나 더 세밀한 제어가 필요할 때 활용합니다.
SDK 설치 및 Docker 이미지 빌드
Terminal
# Azure AI Projects SDK 설치 (v2.0.0 이상 필요)
$ pip install "azure-ai-projects>=2.0.0"
# Docker 이미지 빌드 (반드시 linux/amd64 플랫폼 지정!)
$ docker build --platform linux/amd64 -t myagent:v1 .
# Azure Container Registry 로그인 및 이미지 푸시
$ az acr login --name myregistry
$ docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
$ docker push myregistry.azurecr.io/myagent:v1
필수: --platform linux/amd64
Hosted Agent는 Linux AMD64 인프라에서 실행됩니다. Apple Silicon(M1/M2/M3) Mac에서 빌드할 때
--platform linux/amd64를 생략하면 컨테이너가 시작되지 않습니다.
SDK로 에이전트 버전 생성
create_agent.py
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
HostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
from azure.identity import DefaultAzureCredential
# Foundry 프로젝트 엔드포인트
PROJECT_ENDPOINT = "https://your-resource.services.ai.azure.com/api/projects/your-project"
# 클라이언트 초기화
client = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
allow_preview=True,
)
# Hosted Agent 버전 생성
agent = client.agents.create_version(
agent_name="my-custom-agent",
definition=HostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1",
)
],
cpu="1",
memory="2Gi",
image="myregistry.azurecr.io/myagent:v1",
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": PROJECT_ENDPOINT,
"MODEL_NAME": "gpt-5-mini",
},
),
)
print(f"에이전트 생성 완료: {agent.name} (version: {agent.version})")
SDK로 에이전트 호출
invoke_agent.py
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
PROJECT_ENDPOINT = "https://your-resource.services.ai.azure.com/api/projects/your-project"
AGENT_NAME = "my-custom-agent"
# 클라이언트 초기화
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
allow_preview=True,
)
openai = project.get_openai_client()
# 에이전트 조회
agent = project.agents.get(agent_name=AGENT_NAME)
print(f"에이전트: {agent.name} (version: {agent.versions.latest.version})")
# 에이전트에 메시지 전송
response = openai.responses.create(
input=[{"role": "user", "content": "안녕하세요! 무엇을 도와드릴까요?"}],
extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(f"응답: {response.output_text}")
예상 출력:
에이전트: my-custom-agent (version: 1)
응답: 안녕하세요! 저는 커스텀 호스트드 에이전트입니다. 다양한 질문에 답변해 드릴 수 있습니다...
트러블슈팅
실습 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.
| 문제 | 코드 | 해결 방법 |
|---|---|---|
SubscriptionNotRegistered |
400 | Azure 공급자 등록: az provider register --namespace Microsoft.CognitiveServices |
AuthorizationFailed |
403 | 구독 또는 리소스 그룹에 Contributor 역할을 요청하세요. |
AcrPullUnauthorized |
403 | 프로젝트 관리 ID에 Container Registry Repository Reader 역할 부여 |
AcrImageNotFound |
404 | 이미지 이름/태그 확인. 이미지가 ACR에 푸시되었는지 확인 |
RegistryNotFound |
400/404 | Registry DNS 또는 네트워크 연결 확인 |
azd ai agent init 실패 |
— | azd version으로 1.23.0 이상인지 확인. macOS: brew upgrade azd |
| 모델을 찾을 수 없음 | — | agent.yaml에서 모델을 구독에서 사용 가능한 것(예: gpt-4.1)으로 변경 |
5xx 오류 발생 시
서버 내부 오류(5xx)가 지속되면 Microsoft 지원에 문의하세요.
리소스 정리
실습이 끝나면 과금을 방지하기 위해 생성된 리소스를 삭제합니다.
주의: 되돌릴 수 없습니다!
azd down은 리소스 그룹 내의 모든 Azure 리소스를 영구 삭제합니다. Foundry 프로젝트, 모델 배포, Container Registry, Application Insights, Hosted Agent가 모두 포함됩니다.
삭제 대상 미리보기 (권장)
Terminal
# 삭제될 리소스 미리 확인
$ azd down --preview
리소스 삭제 실행
Terminal
# 모든 Azure 리소스 삭제 (약 2~5분 소요)
$ azd down
삭제 확인
Azure Portal에서 해당 리소스 그룹으로 이동하여 리소스가 더 이상 표시되지 않는지 확인합니다. 빈 리소스 그룹은 추가로 삭제할 수 있습니다.
SDK로 개별 삭제 시
project.agents.delete_version(agent_name="my-agent", agent_version="1")으로 특정 에이전트 버전만 삭제할 수도 있습니다.
다음 단계
실습을 성공적으로 완료했습니다! 다음으로 에이전트를 더 발전시킬 수 있는 방법을 알아보세요.