Implantar Docker Compose para agentes no Azure Container Apps Preview

Este artigo mostra-lhe como implementar aplicações para Azure Container Apps utilizando o Compose for Agents do Docker. Esta funcionalidade mantém o ficheiro de composição que já usa localmente e permite-lhe implementá-lo em Aplicações Container. A az-cli extensão da aplicação container traduz então o ficheiro de composição em aplicações do Azure Container Apps e gere identidades, escalabilidade e ciclo de vida do modelo para você.

Neste artigo, você aprende a:

Compreenda os recursos específicos para agentes criados nas Azure Container Apps.
Reveja exemplos de ficheiros de composição adaptados para Azure Container Apps.
Implementa um ficheiro compose com a CLI do Azure e verifica o ambiente.
Resolver problemas e aprender sobre as limitações atuais.

Importante

O suporte do Docker Compose para agentes no Azure Container Apps está em pré-visualização pública. As funcionalidades e o comportamento podem mudar sem aviso.

Pré-requisitos

Azure CLI 2.70.0 ou posterior com a containerapp versão 1.2.0b5+ai.compose de extensão ou posterior instalada (ver instruções de instalação).
Uma subscrição Azure com permissões para criar recursos Azure Container Apps.
Um ficheiro Docker Compose para agentes. Podes começar pelos samples no repositório docker/compose-for-agents .
Instalação do Docker (para compilação local)
Um ambiente Azure Container Apps pronto para implementações. Crie um ambiente com az containerapp env create se ainda não tiver um. Implantar modelos na GPU exige que escolhas uma das seguintes localizações. Os exemplos usados neste artigo assumem o uso de GPU serverless.

Arquitetura de implantação

Quando executa az containerapp compose create, a CLI traduz elementos de compose focados em agentes para os recursos Azure Container Apps apropriados. Dois componentes críticos no Compose for Agents são o model runner e o gateway MCP, responsável por disponibilizar o modelo e as ferramentas MCP à sua aplicação.

Ferramentas de protocolo de contexto de modelo (MCP)

O Azure Container Apps executa uma variante do gateway MCP do Docker como uma aplicação contentor própria. Utiliza identidade gerida atribuída pelo sistema para adicionar ou remover dinamicamente os contentores de ferramentas MCP dentro do ambiente. Esta configuração aparece como contentores separados na aplicação mcp-gateway. O gateway para a comunicação com ferramentas MCP está limitado à rede. Os servidores MCP Stdio são encapsulados para funcionar como servidores MCP baseados em SSE em aplicações Azure Container. Docker for Agents em Azure Container Apps suporta atualmente os 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 através do modelador do Docker. No Azure Container Apps, o contentor model-runner-config implementado como parte da aplicação models gere a configuração. Garante que o modelo correto seja obtido e configurado antes que a sua aplicação de software possa interagir com ele. A configuração é passada para o contentor de configuração do modelo através da MODEL_CONFIG variável.

Compoir ficheiros

Podes usar o mesmo ficheiro compose para desenvolvimento e implementação local. Para alcançar este objetivo, adicione a x-azure-deployment diretiva. O Compose do Docker ignora esta diretiva, mas é usada durante a implementação nas aplicações Azure Container. Aqui estão alguns exemplos prontos para serem implementados para rever. Estes exemplos têm todas as seguintes secções em comum para GPU serverless e para implementar a versão Azure Container Apps 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 utilização

Siga os passos abaixo para configurar o seu ambiente e implementar as suas aplicações usando os seus ficheiros compose existentes.

Instalação do Compose para agentes

Nesta fase, esta funcionalidade requer a instalação de dois pacotes. Uma vez instalados, estes pacotes fornecem as capacidades explicadas. Siga estes passos:

# 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

Usar o Compose para os agentes

Comece com um dos ficheiros preparados aqui localizados. Depois 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

Definições padrão do agente

Aplicações criadas sem definições explícitas de agente recebem as seguintes definições por defeito:

DiscoveryMode = Auto, que deteta automaticamente as capacidades e dependências do agente.
IsAgent = false, indicando que a aplicação não atua como agente a menos que esteja explicitamente configurada.

Estes padrões garantem um comportamento consistente para todas as aplicações de contentores no seu ambiente.

Desinstalar e voltar atrás

Para voltar à versão estável da extensão da app container:

# 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 resolução de problemas

Atrasos ocasionais na disponibilidade de imagens: Por vezes, uma imagem criada localmente não está imediatamente disponível na plataforma. Reimplante ou reinicie a aplicação para resolver o problema. O erro é o seguinte:

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

Questões de identidades geridas: Ao reimplantar, poderá ver esta mensagem. Este erro ocorre porque a identidade é reatribuída ao mcp-gateway. Ignora a mensagem se o teu gateway estiver a funcionar 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 inalcançáveis: Confirme que o nome do gateway omite o número da porta e corresponde exatamente ao valor injetado em MCP_GATEWAY_URL. Não reintroduza manualmente portas removidas durante a implementação.
Ferramentas de gateway MCP: Verifique se a aplicação mcp-gateway tem vários contentores implementados. Se sim, as coisas deverão estar a funcionar corretamente.
Modelos não provisionados: Revise os model-runner-config registos de contentores da models aplicação para verificar problemas de autenticação ao puxar modelos. Obtenha os modelos disponíveis executando curl http://YOUR_MODELS_ENDPOINT/models.
Relatar problemas: Relate problemas com a extensão no GitHub oficial de Container Apps.

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

Advertência

Estas limitações aplicam-se durante a pré-visualização pública e podem mudar antes da disponibilidade geral.

Apenas um wrapper MCP baseado em SSE por ficheiro compose é suportado.
Atualmente, volumes e redes não são suportados.
As mensagens de registo nem sempre estão corretas.

Comentários

Esta página foi útil?

Last updated on 2026-04-03