Azure Container Apps 미리 보기에 에이전트용 Docker Compose 배포

이 문서에서는 Docker의 에이전트용 Compose를 사용하여 Azure Container Apps에 애플리케이션을 배포하는 방법을 보여 줍니다. 이 기능은 이미 로컬로 사용하는 작성 파일을 유지하고 컨테이너 앱에 배포할 수 있도록 합니다. 그런 다음 컨테이너 앱 확장은 az-cli 작성 파일을 Azure Container App 애플리케이션으로 변환하고 ID, 크기 조정 및 모델 수명 주기를 관리합니다.

이 문서에서는 다음을 알아봅니다.

필수 조건

• containerapp 확장 버전 1.2.0b5+ai.compose 이상이 설치된 Azure CLI 2.70.0 이상(설치 지침 참조).
• Azure Container Apps 리소스를 만들 수 있는 권한이 있는 Azure 구독입니다.
• 에이전트 파일을 위한 Docker Compose입니다. docker/compose-for-agents 리포지토리의 샘플에서 시작할 수 있습니다.
• Docker 설치(로컬 빌드용)
• 배포할 준비가 된 Azure Container Apps 환경입니다. az containerapp env create을 사용하여 환경이 아직 없는 경우 환경을 만드십시오. GPU에 모델을 배포하려면 다음 위치 중 하나를 선택해야 합니다. 이 문서에 사용된 샘플에서는 서버리스 GPU를 사용하는 것으로 가정합니다.

배포 아키텍처

az containerapp compose create를 실행하면 CLI는 에이전트 중심 구성 요소를 적절한 Azure Container Apps 리소스로 변환합니다. 에이전트용 Compose의 두 가지 중요한 구성 요소는 모델 실행기 및 MCP 게이트웨이이며, 애플리케이션에서 모델 및 MCP 도구를 사용할 수 있도록 하는 역할을 담당합니다.

MCP(모델 컨텍스트 프로토콜) 도구

Azure Container Apps는 Docker의 MCP 게이트웨이 변형을 자체 컨테이너 앱으로 실행합니다. 시스템 할당 관리 ID를 사용하여 환경 내에서 MCP 도구 컨테이너를 동적으로 추가하거나 제거합니다. 이 설정은 mcp-gateway 애플리케이션 아래에 별도의 컨테이너로 표시됩니다. MCP에 대한 게이트웨이 도구 통신은 네트워크로 제한됩니다. Stdio MCP 서버는 Azure Container Apps에서 SSE 기반 MCP 서버로 실행되도록 래핑됩니다. Azure Container Apps의 에이전트용 Docker는 현재 다음의 Stdio MCP 서버를 지원합니다: AppSignal, BigQuery, Confluence, DuckDuckGo, Fetch, Filesystem, Git, Google Drive, Jira, MongoDB, MySQL, Notion, Playwright, PostgreSQL, SequentialThinking, Slack, SQLite, Supabase, Time, Twist.

Models

모델은 Docker의 모델 실행기를 통해 제공됩니다. Azure Container Apps에서 모델 앱의 일부로 배포된 model-runner-config 컨테이너는 구성을 처리합니다. 앱이 상호 작용하기 전에 올바른 모델을 끌어오고 구성합니다. 구성은 변수를 통해 모델 구성 컨테이너에 MODEL_CONFIG 전달됩니다.

파일 작성

로컬 개발 및 배포에 동일한 작성 파일을 사용할 수 있습니다. 이 목표를 달성하려면 지시문을 추가합니다 x-azure-deployment . Docker의 Compose는 이 지시문을 무시하지만 Azure Container Apps에서 배포하는 동안 사용됩니다. 다음은 검토할 수 있는 배포 준비 샘플 입니다. 이러한 샘플에는 모두 서버리스 GPU 및 mcp-gateway의 Azure Container Apps 버전을 배포하기 위한 다음 섹션이 있습니다.

services:
  ...

models:
  gemma:
    model: ai/gemma3-qat
	# run the models on serverless GPU workload profile
    x-azure-deployment:
      workloadProfiles:
        workloadProfileType: Consumption-GPU-NC8as-T4

serivces:
	mcp-gateway:
	...
	# use the Azure Container Apps flavored image for the mcp-gateway
	x-azure-deployment:
	  image: acateam.azurecr.io/preview-ai-compose/mcp-gateway:latest
  ...

models:
  ...

다른 x-azure-deployment 옵션은 다음과 같습니다.

x-azure-deployment:
  image: ghcr.io/example/app:custom-build
  resources:
    cpu: 1.0
    memory: 2
  scale:
    maxReplicas: 1
    minReplicas: 1
  ingress:
    external: true
    allowInsecure: false

설치 및 사용

아래 단계에 따라 환경을 설정하고 기존 작성 파일을 사용하여 애플리케이션을 배포합니다.

에이전트용 Compose 설치

이 단계에서 이 기능을 사용하려면 두 개의 패키지를 설치해야 합니다. 설치되면 이러한 패키지는 설명된 기능을 제공합니다. 아래 단계를 수행하세요.

# remove the existing container apps extension
az extension remove --name containerapp

# install the pycomposefile module and the preview extension for containerapps
pip install "https://raw.githubusercontent.com/microsoft/azure-container-apps/main/preview/ai-compose/az-extension/release-1.2.0b5+ai.compose-py2.py3-none-any/pycomposefile-0.0.32-py3-none-any.whl"
az extension add --source "https://raw.githubusercontent.com/microsoft/azure-container-apps/main/preview/ai-compose/az-extension/release-1.2.0b5+ai.compose-py2.py3-none-any/containerapp-1.2.0b5+ai.compose-py2.py3-none-any.whl" --yes

# check of the extension is installed (should show 1.2.0b5+ai.compose)
az extension show --name containerapp --query version -o tsv
# you are ready to use the extension
az containerapp compose --help

에이전트를 위한 Compose 사용

여기에 있는 준비된 파일 중 하나로 시작합니다. 그런 다음, 지침을 따릅니다.

# define the needed variables
export LOCATION=westus2
export RESOURCE_GROUP=rg-compose-for-agents
export ENV_NAME=ai-app-env
export COMPOSE=compose-aca.yml

# create the resource group
az group create --name $RESOURCE_GROUP   --location $LOCATION && 

# create the Azure Container Apps environment
az containerapp env create \
			--name $ENV_NAME \
			--resource-group $RESOURCE_GROUP \
			--location $LOCATION

# deploy your compose file
az containerapp compose create \
			--compose-file-path $COMPOSE \
			--resource-group $RESOURCE_GROUP \
			--environment $ENV_NAME

에이전트 설정 기본값

명시적 에이전트 설정 없이 만든 애플리케이션은 다음과 같은 기본값을 받습니다.

• DiscoveryMode = Auto에이전트 기능 및 종속성을 자동으로 검색하는 입니다.
• IsAgent = false- 명시적으로 구성하지 않는 한 앱이 에이전트 역할을 하지 않음을 나타냅니다.

이러한 기본값은 사용자 환경의 모든 컨테이너 앱에 대해 일관된 동작을 보장합니다.

제거 및 다시 전환

컨테이너 앱 확장의 안정적인 릴리스로 다시 전환하려면 다음을 수행합니다.

# remove the current extension
az extension remove --name containerapp
# reinstall and confirm stable install
az extension install --name containerapp
az extension show --name containerapp --query version -o tsv

알려진 문제 및 문제 해결

• 경우에 따라 이미지 가용성 지연: 로컬로 빌드된 이미지를 플랫폼에서 즉시 사용할 수 없는 경우가 있습니다. 애플리케이션을 다시 배포하거나 다시 시작하여 문제를 해결합니다. 오류는 다음과 같습니다.

  Failed to provision revision for container app 'app'. Error details: The following field(s) are either invalid or missing. Field 'template.containers.app.image' is invalid with details: 'Invalid value: "acateam.azurecr.io/preview-ai-compose/samples/spring-ai-app:latest": GET https:: MANIFEST_UNKNOWN: manifest tagged by "latest" is not found; map[Tag:latest]'
  

• 관리 ID 문제: 다시 배포 시 이 메시지가 표시될 수 있습니다. 이 오류는 ID가 mcp-gateway에 다시 할당되기 때문에 발생합니다. 게이트웨이가 제대로 작동하는 경우 메시지를 무시합니다.

  ⚠️  Could not automatically assign role: AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance.
  

• 연결할 수 없는 게이트웨이 URL: 게이트웨이 호스트 이름이 포트 번호를 생략하고 삽입된 MCP_GATEWAY_URL값과 일치하는지 확인합니다. 배포 중에 제거된 포트를 수동으로 다시 도입하지 마세요.

• MCP 게이트웨이 도구: mcp-gateway 앱에 여러 컨테이너가 배포되어 있는지 확인합니다. 그렇다면 제대로 작동해야 합니다.

• 프로비전되지 않은 모델: 모델을 끌어온 경우 앱의 model-runner-config 컨테이너 로그를 검토 models 하여 인증 문제를 확인합니다. 를 실행 curl http://YOUR_MODELS_ENDPOINT/models하여 사용 가능한 모델을 끌어오기.

• 보고 문제: 공식 Container Apps GitHub에서 확장 관련 문제를 보고합니다.

미리 보기 제한 사항

• 작성 파일당 하나의 SSE 기반 MCP 래퍼만 지원됩니다.
• 볼륨 및 네트워크는 현재 지원되지 않습니다.
• 로그 메시지가 항상 올바른 것은 아닙니다.