¿Qué son los agentes hospedados?

Al compilar aplicaciones agente mediante marcos de código abierto, normalmente se administran muchos problemas transversales: contenedorización, configuración del servidor web, seguridad, persistencia de memoria, escalado, instrumentación y reversión de versiones. Estas tareas se vuelven aún más difíciles en entornos de nube heterogéneos.

Los agentes hospedados en Foundry Agent Service resuelven estos desafíos para los usuarios de Microsoft Foundry. Los agentes hospedados llaman a los modelos del catálogo de modelos de Foundry para realizar el razonamiento, mientras que tu código personalizado gestiona la orquestación. Mediante este uso de esta plataforma administrada, puede implementar y operar agentes de inteligencia artificial de forma segura y a gran escala. Puede usar el código de agente personalizado o un marco de agente preferido con una implementación y administración simplificadas.

Cuándo usar agentes hospedados

Elija agentes hospedados en lugar de agentes basados en instrucciones cuando necesite lo siguiente:

• Traiga su propio código: use cualquier marco (Agent Framework, LangGraph, Kernel semántico o código personalizado) en lugar de definiciones únicamente basadas en solicitudes.
• Usar protocolos personalizados: acepte webhooks o cargas que no sean de OpenAI a través del protocolo de Invocaciones.
• Controlar los recursos de computación : especifique la CPU y memoria para el sandbox del agente.
• Ejecuta cargas de trabajo con estado: conserva los archivos y el estado a lo largo de las transiciones a través de $HOME y el endpoint /files.

Cómo funciona

Tú empaquetas tu agente como una imagen de contenedor y lo subes al Azure Container Registry. Al implementar, Agent Service extrae la imagen, aprovisiona los recursos de cómputo, asigna un Microsoft Entra ID dedicado (identidad del agente) y expone un punto de conexión dedicado. Durante el tiempo de ejecución, el código del agente gestiona las solicitudes de los clientes y puede llamar a modelos de Foundry, herramientas de Toolbox y servicios posteriores de Azure mediante su identidad de agente. La plataforma controla el escalado, la persistencia del estado de sesión, la observabilidad y la administración del ciclo de vida.

Conceptos clave

Agentes hospedados

Los agentes hospedados son aplicaciones de IA en contenedores que se ejecutan en Agent Service. A diferencia de los agentes basados en mensajes, que se definen completamente a través de avisos y configuración de herramientas en el portal de Foundry, los agentes hospedados son su propio código empaquetado como una imagen de contenedor. Elija el framework, controle el comportamiento del tiempo de ejecución e implemente la imagen en la infraestructura administrada por Microsoft.

La plataforma administra automáticamente el ciclo de vida del contenedor en función de la actividad, aprovisionando recursos al crear una versión y desaprovisionando cuando se alcanza el tiempo de espera de inactividad.

Modelo de aislamiento

Los agentes hospedados se ejecutan en espacios aislados de máquina virtual por cada sesión. Cada sesión habilita un espacio aislado dedicado con un sistema de archivos persistente ($HOME y /files), que permite reducir recursos a cero manteniendo la sesión activa y asegurando un tiempo de arranque estable. Las sesiones se aíslan entre sí y el estado se restaura automáticamente cuando una sesión se reanuda después de estar inactiva.

Protocolos: Respuestas, invocaciones e invocaciones (WebSocket)

Los contenedores del agente hospedado pueden exponer uno o varios protocolos. Cada protocolo lo proporciona una biblioteca ligera que controla el servidor HTTP o WebSocket, las comprobaciones de estado y la integración de OpenTelemetry. Los protocolos de respuestas e invocaciones están disponibles en todas las regiones que admiten agentes hospedados.

¿Qué protocolo debo usar?

Comparación de protocolos

Protocolos adicionales

Los agentes hospedados también admiten el protocolo Activity para Teams e integración de canales de Microsoft 365. Al usar el protocolo de respuestas en la lógica del agente y al publicar en canales de Microsoft 365 como Teams, la plataforma conecta automáticamente las respuestas al protocolo de actividad para distribuirlas al canal; no se tiene que hacer ninguna otra conexión aparte. El protocolo A2A admite la delegación de agente a agente. Los protocolos admitidos se pueden combinar en un solo agente.

Identidad y punto de conexión del agente

Cada agente hospedado implementado en un proyecto de Foundry obtiene su propio Microsoft Entra ID dedicado (identidad del agente) y su propio punto de conexión dedicado, ambos creados automáticamente al implementarse. No es necesario configurar las identidades administradas ni el enrutamiento manualmente.

El punto de conexión está disponible inmediatamente después de la implementación: la publicación no es necesaria para el acceso mediante programación:

• Respuestas: {project_endpoint}/agents/{name}/endpoint/protocols/openai/responses
• Invocaciones: {project_endpoint}/agents/{name}/endpoint/protocols/invocations
• Invocaciones (WebSocket): wss://{account}.services.ai.azure.com/api/projects/agents/endpoint/protocols/invocations_ws?project_name={project}&agent_name={name}
• A2A (versión preliminar): {project_endpoint}/agents/{name}/endpoint/protocols/a2a

Los puntos de conexión que están activos dependen de los protocolos declarados en la definición de versión del agente (establecido en agent.yaml al usar azd o a través de container_protocol_versions cuando se usa el SDK).

Hay dos identidades implicadas:

Al implementar con azd, el rol de RBAC necesario (usuario de Foundry en el nivel de la cuenta) se asigna automáticamente a Microsoft Entra ID del agente. En el caso de los recursos externos (por ejemplo, su propio Azure Storage), asigne RBAC manualmente al Microsoft Entra ID del agente.

Cuando se integra a través de canales de Microsoft 365 (por ejemplo, Teams), los agentes hospedados pueden funcionar en dos modos de identidad en función de cómo se invocan:

• Escenarios invocados por el usuario (interactivo): si hay un token de usuario presente, la plataforma admite flujos de OAuth 2.0 on-Behalf-Of (OBO). En este caso, el agente puede invocar servicios posteriores en nombre del usuario usando los permisos delegados del usuario, con sujeción a las directivas de inquilino de Microsoft Entra ID.

• Escenarios autónomos o en segundo plano: Si no hay ningún token de usuario disponible, el agente se autentica con su propio identificador de Microsoft Entra ID (identidad del agente), normalmente a través de una identidad administrada, para acceder a los servicios posteriores.

En ambos casos, el agente conserva su Microsoft Entra ID dedicada para la autenticación, la autorización y la auditabilidad. Para obtener más información, consulte Conceptos de identidad del agente y aplicaciones del agente.

Sesiones y conversaciones

Los agentes hospedados usan sesiones y conversaciones para administrar el estado. El funcionamiento depende del protocolo.

Sesiones

Un identificador de sesión identifica una sesión lógica con estado persistente, incluidos $HOME y archivos cargados a través del punto de conexión /files. La plataforma aprovisiona recursos de computación a petición y restaura el estado persistente en dichos recursos.

• Persistencia de estado: $HOME y el contenido de /files se conservan en turnos y en períodos de inactividad. Cuando los recursos de computación quedan inactivos y se vuelven a activar (en una infraestructura nueva o existente), el estado de la sesión se restaura automáticamente.
• Aislamiento: cada sesión está aislada de otras sesiones.
• Ciclo de vida automático: las sesiones se crean en el primer uso. La plataforma aprovisiona y desaprovisiona recursos computacionales automáticamente.
• Duración de la sesión: el tiempo de espera de inactividad es de 15 minutos, si no llega ninguna solicitud dentro de esa ventana, la plataforma desaprovisiona el proceso y conserva el estado de sesión. Una sesión se elimina permanentemente después de 30 días de inactividad.
• API de administración de sesiones: enumera las sesiones, finaliza sesiones y carga o descarga de archivos por sesión.

Conversaciones

Un identificador de conversación es un registro duradero del historial de conversaciones (mensajes, llamadas a herramientas y respuestas) almacenados en Foundry.

• Persistencia: el historial de conversaciones se almacena en Foundry y se conserva independientemente del estado de proceso.
• Acceso entre canales: los usuarios pueden acceder a la misma conversación desde el área de juegos, la API, Teams u otros canales publicados.

Cómo funcionan las sesiones y las conversaciones con cada protocolo

Protocolo de respuestas: el identificador de conversación es el concepto principal. La plataforma administra automáticamente el historial de conversaciones y asocia un identificador de sesión a cada conversación. La plataforma devuelve el identificador de sesión al cliente, que puede usarlo para cargar archivos a través del punto de conexión /files, lo que hace que esos archivos estén disponibles para el proceso de la conversación.

Protocolo de invocaciones: el identificador de sesión es el concepto principal. El cliente administra el identificador de sesión directamente para mantener el estado entre interacciones. El cliente puede cargar contenido a través del punto de conexión /files mediante el identificador de sesión para que esté disponible para la sesión. No hay ningún historial de conversaciones administrado por la plataforma: administra el estado en su propio código.

Ciclo de vida de cómputo de sesión

Seguridad y control de datos

Trate un agente hospedado como el código de la aplicación de producción.

• No coloque secretos en imágenes de contenedor ni variables de entorno. Use identidades administradas y conexiones y almacene secretos en un almacén de secretos administrados. Para obtener instrucciones, consulte Set up a Key Vault connection.
• Ten cuidado con herramientas y servidores que no son de Microsoft. Si el agente llama a herramientas respaldadas por servicios no proporcionados por Microsoft, algunos datos pueden ser transferidos a esos servicios. Revise las directivas de uso compartido, retención y ubicación de datos para cualquier servicio que no sea de Microsoft que se conecte.

Detalles de la plataforma

Control de versiones

Cada llamada para crear una versión genera una versión del agente inmutable, una instantánea de la imagen de contenedor, la asignación de recursos, las variables de entorno y la configuración del protocolo. Las implementaciones hacen referencia a una versión específica. Actualiza tu agente creando una nueva versión y la plataforma la despliega. Tenga en cuenta que las solicitudes para crear la versión del agente sin ningún cambio en los parámetros de versión del agente, como la imagen de contenedor, las variables de entorno, etc., no darán lugar a que se cree una nueva versión. Puede dividir el tráfico entre versiones con implementaciones ponderadas para admitir implementaciones controladas y mediante entornos paralelos (azul-verde).

Las variables de entorno son el mecanismo principal para pasar la configuración al contenedor en tiempo de ejecución (por ejemplo, el punto de conexión del proyecto, el nombre de implementación del modelo y la configuración personalizada). Se establecen por versión y son inmutables una vez creada la versión.

Observability

Los agentes hospedados proporcionan observabilidad integrada. La plataforma inserta automáticamente una cadena de conexión de Application Insights en el contenedor del agente a través de variables de entorno. Los agentes que utilizan las bibliotecas de protocolo emiten trazas de OpenTelemetry de forma predeterminada, las cuales aparecen en el recurso vinculado de Application Insights en Investigar>Búsqueda de transacciones o Rendimiento.

Para obtener instrucciones de configuración y análisis, consulte Habilitación del seguimiento en el proyecto.

Cuadro de herramientas en Foundry

Los agentes hospedados acceden a las herramientas administradas por Foundry (Intérprete de código, Búsqueda web, Búsqueda de Azure AI, OpenAPI, conexiones MCP personalizadas, A2A) a través de un punto de conexión MCP de Toolbox aprovisionado en el proyecto foundry. El código del agente se conecta a este punto de conexión mediante bibliotecas cliente de MCP estándar; la plataforma no inserta herramientas automáticamente. Para obtener más información, consulte Curate intent-based toolbox in Foundry (Curar cuadro de herramientas basado en intenciones en Foundry). Recomendamos a los clientes que usen el cuadro de herramientas en Foundry para conectar las herramientas en el agente hospedado, con la función de autenticación unificada en métodos como el paso de identidad de OAuth, la identidad del agente, la autenticación basada en claves, entre otros.

Compatibilidad con idiomas

Los agentes hospedados admiten Python y C#. Puede usar cualquier marco de trabajo del agente: las bibliotecas de protocolos son independientes del marco de trabajo. Para obtener ejemplos con Microsoft Agent Framework, LangGraph y código personalizado, consulte el repositorio foundry-samples.

Tamaños de espacio aislado

Los entornos aislados del agente alojado admiten las siguientes combinaciones de CPU y memoria:

Almacenamiento de sesión

Cada sesión tiene un valor persistente $HOME. Su contenido se conserva cuando el entorno de cómputo se desasigna tras 15 minutos de inactividad y se restaura cuando se reanuda la sesión, por lo que los archivos escritos en $HOME sobreviven a los períodos de inactividad. Los archivos cargados a través del /files punto de conexión se escriben en $HOME y comparten el mismo almacenamiento. A cada sesión se le asigna una cuota total de disco de hasta 20 GiB con 1 vCPU o más, que se reduce proporcionalmente en los niveles inferiores de CPU. Aproximadamente 20% de ese presupuesto está reservado para uso del sistema y no está visible o disponible para el agente. El resto se comparte entre la imagen de contenedor, $HOME y cualquier otra ubicación grabable del contenedor.

Escalado y dimensionamiento adecuado

Los agentes hospedados escalan por sesión, no por réplica. La plataforma crea un nuevo sandbox aislado por VM para cada sesión bajo demanda, lo mantiene en ejecución durante toda la sesión (tiempo de inactividad máximo de 15 minutos y duración máxima de 30 días) y lo elimina cuando finaliza la sesión. No hay ningún recuento de réplicas para configurar y no hay ningún grupo intermedio para ajustar el tamaño. El número de espacios aislados simultáneos está limitado por la cuota de sesiones activas para la suscripción y la región (el valor predeterminado es 50 y puede ajustarse a través del Soporte técnico de Microsoft).

Dado que cada sesión se ejecuta en su propio espacio aislado, los valores de cpu y memoria establecidos en una versión del agente describen una sola sesión, no la superficie agregada del agente. La facturación se basa en la CPU más la memoria consumida en todas las sesiones activas, por lo que el sobredimensionamiento multiplica el coste por la simultaneidad.

Para ajustar el tamaño, ejecute una carga de trabajo representativa e inspeccione el uso de recursos en el recurso vinculado de Application Insights:

1. Abra el recurso de App Insights en el portal de Azure y seleccione Investigate>Performance.
2. Revise la CPU, la memoria disponible, la tasa de solicitudes y la duración media de la solicitud a lo largo del intervalo de tiempo que ha probado.

Compare los picos observados con la cpu y la memoria asignadas. Si los picos sostenidos superan aproximadamente el 70 % de la asignación, aumente la asignación de la siguiente versión del agente; si los picos se mantienen muy por debajo, reduzca la asignación para reducir el coste. Vuelva a probar siempre después de un cambio, ya que cada nueva versión es inmutable.

Redes privadas

Los agentes hospedados admiten la implementación en recursos de Foundry aislados de red y pueden usar un Azure Virtual Network proporcionado por el cliente para el tráfico saliente. Esto permite a los agentes de las implementaciones de Foundry aisladas de red llegar a recursos privados, como bases de datos o API internas. Para obtener más información, consulte Configuración de redes virtuales.

Límites, precios y disponibilidad (versión preliminar)

Los agentes hospedados están actualmente disponibles en versión preliminar.

Limitaciones durante la versión preliminar

Precios

La facturación del entorno de ejecución de hospedaje administrado se basa en el consumo de recursos de CPU y memoria durante las sesiones activas. Para obtener las tarifas actuales, consulte la página precios de Foundry.

Disponibilidad de regiones

Los agentes hospedados están disponibles actualmente en las siguientes regiones:

• Este de EE. UU. 2
• Centro-norte de EE. UU.
• Centro de Suecia
• Centro de Canadá
• Canada East
• Sudeste asiático
• Centro de Polonia
• Norte de Sudáfrica
• Centro de Corea del Sur
• Sur de la India
• Sur de Brasil
• Oeste de EE. UU.
• Oeste de EE. UU. 3
• Este de Noruega
• Este de Japón
• Centro de Francia
• Centro-oeste de Alemania
• Norte de Suiza
• Centro de España
• Este de Australia

Pasos siguientes

Contenido relacionado

• Componentes en tiempo de ejecución del agente
• Ciclo de vida de desarrollo del agente
• Conceptos de identidad de agente en Microsoft Foundry
• Detección de herramientas en Foundry Tools
• documentación de Azure Container Registry