Implantar o Docker Compose para agentes na versão prévia dos Aplicativos de Contêiner do Azure

Este artigo mostra como implantar aplicativos nos Aplicativos de Contêiner do Azure usando o Compose for Agents do Docker. Esse recurso mantém o arquivo de composição que você já usa localmente e permite implantá-lo em Aplicativos de Contêiner. Em seguida, a extensão do aplicativo de contêiner az-cli converte o arquivo de composição em aplicativos do Aplicativo de Contêiner do Azure e gerencia as identidades, a escala e o ciclo de vida do modelo para você.

Neste artigo, você aprenderá a:

  • Entenda os recursos específicos do agente criados nos Aplicativos de Contêiner do Azure.
  • Analise os arquivos de composição de exemplo adaptados para os Aplicativos de Contêiner do Azure.
  • Implante um arquivo de redação com a CLI do Azure e verifique o ambiente.
  • Solucione problemas e saiba mais sobre as limitações atuais.

Importante

O suporte do Docker Compose para agentes nos Aplicativos de Contêiner do Azure está em versão prévia pública. Os recursos e o comportamento podem mudar sem aviso prévio.

Pré-requisitos

  • CLI do Azure 2.70.0 ou posterior com a extensão containerapp na versão 1.2.0b5+ai.compose ou posterior instalada (veja as instruções de instalação).
  • Uma assinatura do Azure com permissões para criar recursos de Aplicativos de Contêiner do Azure.
  • Um arquivo Docker Compose para agentes. Você pode começar a partir dos exemplos no repositório docker/compose-for-agents .
  • Instalação do Docker (para compilação local)
  • Um ambiente de Aplicativos de Contêiner do Azure pronto para implantações. Caso ainda não tenha um ambiente, crie um com az containerapp env create. A implantação de modelos na GPU exige que você escolha um dos locais a seguir. Os exemplos usados neste artigo pressupõem o uso da GPU sem servidor.

Arquitetura de implantação

Quando você executa az containerapp compose create, a CLI converte elementos de composição voltados para o agente nos recursos apropriados dos Aplicativos de Contêiner do Azure. Dois componentes críticos no Compose for Agents são o executor de modelo e o gateway MCP, responsáveis por disponibilizar o modelo e as ferramentas MCP para seu aplicativo.

Ferramentas do protocolo MCP (protocolo de contexto de modelo)

Os Aplicativos de Contêiner do Azure executam uma variante do gateway MCP do Docker como seu próprio aplicativo de contêiner. Ele usa a identidade gerenciada atribuída pelo sistema para adicionar ou remover contêineres de ferramenta MCP dentro do ambiente dinamicamente. Essa configuração aparece como contêineres separados no aplicativo mcp-gateway. O gateway para a comunicação com ferramentas MCP está limitado à rede. Os servidores STdio MCP são encapsulados para serem executados como servidores MCP baseados em SSE nos Aplicativos de Contêiner do Azure. Atualmente, o Docker for Agents nos Aplicativos de Contêiner do Azure dá suporte aos seguintes servidores Stdio MCP: AppSignal, BigQuery, Confluence, DuckDuckGo, Fetch, Filesystem, Git, Google Drive, Jira, MongoDB, MySQL, Notion, Playwright, PostgreSQL, SequentialThinking, Slack, SQLite, Supabase, Time, Twist.

Models

Os modelos são servidos por meio do executor modelo do Docker. Nos Aplicativos de Contêiner do Azure, o contêiner model-runner-config implantado como parte do aplicativo modelos manipula a configuração. Ele garante que o modelo correto seja puxado e configurado antes que seu aplicativo possa interagir com ele. A configuração é passada para o contêiner de configuração do modelo por meio da MODEL_CONFIG variável.

Redigir arquivos

Você pode usar o mesmo arquivo de composição para desenvolvimento e implantação local. Para atingir essa meta, adicione a x-azure-deployment diretiva. O Docker's Compose ignora essa diretiva, mas ela é usada durante a implantação nos Aplicativos de Contêiner do Azure. Aqui estão alguns exemplos prontos para implantar para você examinar. Todas essas amostras têm as seções a seguir em comum para o GPU sem servidor e para implantar a versão dos Aplicativos de Contêiner do Azure do mcp-gateway.

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:
  ...

Outras x-azure-deployment opções são:

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

Instalação e uso

Siga as etapas abaixo para configurar seu ambiente e implantar seus aplicativos usando seus arquivos de composição existentes.

Instalando o Compose para agentes

Neste estágio, esse recurso requer a instalação de dois pacotes. Depois de instalados, esses pacotes fornecem os recursos explicados. Siga estas etapas:

# 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

Usando o Compose para agentes

Comece com um dos arquivos preparados localizados aqui. Em seguida, siga as instruções:

# 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

Configurações padrão do agente

Os aplicativos criados sem configurações explícitas do agente recebem os seguintes padrões:

  • DiscoveryMode = Auto, que detecta automaticamente as dependências e as funcionalidades do agente.
  • IsAgent = false, indicando que o aplicativo não atua como um agente, a menos que esteja configurado explicitamente.

Esses padrões garantem um comportamento consistente para todos os aplicativos de contêiner em seu ambiente.

Desinstalando e voltando à versão anterior

Para voltar para a versão estável da extensão do aplicativo de contêiner:

# 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

Problemas conhecidos e soluções de problemas

  • Atrasos ocasionais de disponibilidade de imagem: às vezes, uma imagem criada localmente não está disponível imediatamente na plataforma. Reimplantar ou reiniciar o aplicativo para corrigir o problema. O erro tem a seguinte aparência:

    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]'

  • Problemas de identidade gerenciada: na nova implantação, você poderá ver esta mensagem. Esse erro ocorre porque a identidade é reatribuída ao mcp-gateway. Ignore a mensagem se o gateway estiver funcionando corretamente.

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

  • URLs de gateway inacessíveis: confirme se o nome do host do gateway omite o número da porta e corresponde ao valor injetado em MCP_GATEWAY_URL. Não reintroduza manualmente as portas removidas durante a implantação.

  • Ferramentaria do gateway MCP: Confira se o aplicativo mcp-gateway tem vários contêineres implantados. Nesse caso, as coisas devem estar operando corretamente.

  • Modelos não provisionados: revise os logs do contêiner model-runner-config do aplicativo models para verificar problemas de autenticação ao efetuar pull de modelos. Efetue pull dos modelos disponíveis executando curl http://YOUR_MODELS_ENDPOINT/models.

  • Relatar problemas: Relate problemas com a extensão no GitHub Oficial do Container Apps.

Limitações na pré-visualização

Aviso

Essas limitações se aplicam durante a versão prévia pública e podem ser alteradas antes da disponibilidade geral.

  • Há suporte apenas para um wrapper MCP baseado em SSE por arquivo de composição.
  • No momento, não há suporte para volumes e redes.
  • As mensagens de log nem sempre estão corretas.
  • Last updated on