Compartir a través de

Implementación de Docker Compose para agentes en la versión preliminar de Azure Container Apps

En este artículo se muestra cómo implementar aplicaciones en Azure Container Apps mediante Compose for Agents de Docker. Esta característica mantiene el archivo de configuración que ya usa localmente y le permite implementarlo en aplicaciones de contenedor. La extensión az-cli de la aplicación contenedora traduce el archivo de configuración a aplicaciones de Azure Container Apps y administra las identidades, el escalado y el ciclo de vida del modelo.

En este artículo, aprenderá a:

  • Comprenda los recursos específicos del agente creados en Azure Container Apps.
  • Revise los archivos de configuración de ejemplo adaptados para Azure Container Apps.
  • Implemente un archivo de redacción con la CLI de Azure y compruebe el entorno.
  • Solucione problemas y obtenga información sobre las limitaciones actuales.

Importante

La compatibilidad con Docker Compose para agentes en Azure Container Apps se encuentra en versión preliminar pública. Las características y el comportamiento pueden cambiar sin previo aviso.

Prerrequisitos

  • CLI de Azure 2.70.0 o posterior con la versión containerapp de la extensión 1.2.0b5+ai.compose o posterior instalada (consulte las instrucciones de instalación).
  • Una suscripción de Azure con permisos para crear recursos de Azure Container Apps.
  • Un archivo de Docker Compose para agentes. Puede empezar desde los ejemplos en el repositorio docker/compose-for-agents .
  • Instalación de Docker (para la compilación local)
  • Un entorno de Azure Container Apps listo para implementaciones. Cree uno con az containerapp env create si todavía no dispone de un entorno. La implementación de modelos en GPU requiere que elija una de las siguientes ubicaciones. Los ejemplos usados en este artículo suponen el uso de GPU sin servidor.

Arquitectura de implementación

Al ejecutar az containerapp compose create, la CLI traduce los elementos de composición enfocados en el agente en los recursos de Azure Container Apps apropiados. Dos componentes críticos de Compose for Agents son el ejecutor de modelos y la puerta de enlace de MCP, responsable de hacer que el modelo y las herramientas de MCP estén disponibles para la aplicación.

Herramientas del protocolo de contexto de modelo (MCP)

Azure Container Apps ejecuta una variante de la puerta de enlace MCP de Docker como su propia aplicación contenedora. Usa la identidad administrada asignada por el sistema para agregar o quitar contenedores de herramientas de MCP en el entorno dinámicamente. Esta configuración aparece como contenedores independientes en la aplicación mcp-gateway. La puerta de enlace a la comunicación de herramientas de MCP está limitada a la red. Los servidores MCP de Stdio se encapsulan para ejecutarse como servidores MCP basados en SSE en Azure Container Apps. Docker para agentes en Azure Container Apps admite actualmente los siguientes servidores MCP de Stdio: AppSignal, BigQuery, Confluence, DuckDuckGo, Fetch, Filesystem, Git, Google Drive, Jira, MongoDB, MySQL, Notion, Playwright, PostgreSQL, SequentialThinking, Slack, SQLite, Supabase, Time, Twist.

Models

Los modelos se sirven a través del ejecutor de modelos de Docker. En Azure Container Apps, el contenedor model-runner-config implementado como parte de la aplicación models controla la configuración. Garantiza que el modelo correcto se extraiga y configure antes de que la aplicación pueda interactuar con él. La configuración se pasa al contenedor de configuración del modelo a través de la MODEL_CONFIG variable .

Redacción de archivos

Puede usar el mismo archivo de composición para el desarrollo y la implementación locales. Para lograr este objetivo, agregue la x-azure-deployment directiva . Compose de Docker omite esta directiva, pero se usa durante la implementación en Azure Container Apps. Estos son algunos ejemplos listos para implementar para su revisión. Estos ejemplos tienen todas las secciones siguientes en común para GPU sin servidor e implementar la versión de Azure Container Apps de 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:
  ...

Otras x-azure-deployment opciones son:

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

Instalación y uso

Siga los pasos siguientes para configurar el entorno e implementar las aplicaciones mediante los archivos de redacción existentes.

Instalación de Compose para agentes

En esta fase, esta característica requiere la instalación de dos paquetes. Una vez instalado, estos paquetes proporcionan las funcionalidades que se explican. Siga estos pasos:

# 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

Uso de Compose para agentes

Comience con uno de los archivos preparados que se encuentran aquí. A continuación, siga las instrucciones:

# 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

Valores predeterminados de configuración del agente

Las aplicaciones creadas sin la configuración explícita del agente reciben los siguientes valores predeterminados:

  • DiscoveryMode = Auto, que detecta automáticamente las funcionalidades y las dependencias del agente.
  • IsAgent = false, que indica que la aplicación no actúa como agente a menos que se configure explícitamente.

Estos valores predeterminados garantizan un comportamiento coherente para todas las aplicaciones de contenedor de su entorno.

Desinstalar y volver atrás

Para volver a la versión estable de la extensión de la aplicación contenedora:

# 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

Solución de problemas conocidos

  • Retrasos ocasionales en la disponibilidad de imágenes: a veces una imagen compilada localmente no está disponible inmediatamente en la plataforma. Vuelva a implementar o reinicie la aplicación para corregir el problema. El error tiene el siguiente aspecto:

    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 identidad administrada: al volver a implementar, es posible que vea este mensaje. Este error se produce porque la identidad se reasigna a mcp-gateway. Ignore el mensaje si la puerta de enlace funciona correctamente.

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

  • Direcciones URL de puerta de enlace inaccesibles: confirme que el nombre de host de la puerta de enlace omite el número de puerto y coincide con el valor insertado en MCP_GATEWAY_URL. No vuelva a introducir manualmente los puertos quitados durante la implementación.

  • Herramientas de puerta de enlace de MCP: compruebe si la aplicación mcp-gateway tiene varios contenedores implementados. Si es así, las cosas deben funcionar correctamente.

  • Modelos no aprovisionados: revise los model-runner-config registros de contenedor de la models aplicación para comprobar si hay problemas de autenticación al extraer modelos. Obtenga los modelos disponibles ejecutando curl http://YOUR_MODELS_ENDPOINT/models.

  • Informe de problemas: informe de problemas con la extensión en el GitHub oficial de Container Apps.

Limitaciones de vista previa

Advertencia

Estas limitaciones se aplican durante la versión preliminar pública y pueden cambiar antes de la disponibilidad general.

  • Solo se admite una envoltura MCP basada en SSE por archivo de composición.
  • Actualmente no se admiten volúmenes y redes.
  • Los mensajes de registro no siempre son correctos.
  • Last updated on