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

Si exploras agentes hospedados con un agente de IA para programación, Microsoft Foundry Skill puede ayudarte a relacionar estos conceptos con tareas de implementación, implementación en producción y operaciones.

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.
Controle los recursos informáticos - especifique la CPU y la memoria del entorno aislado de su 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.
Ejecute tareas de larga duración de forma resiliente - preserve el trabajo en curso del agente durante interrupciones del proceso y vuelva a emitir los resultados transmitidos en streaming a los clientes que se reconectan.

Cómo funciona

Tú empaquetas tu agente como una imagen de contenedor y lo subes al Azure Container Registry. Al implementar, el servicio del agente extrae la imagen, asigna una Microsoft Entra ID dedicada (identidad del agente) y expone un punto de conexión dedicado para el agente.

En tiempo de ejecución, Agent Service aprovisiona recursos de computación para la sesión y redirige las solicitudes a su contenedor. El código del agente gestiona esas solicitudes y puede invocar modelos de Foundry, herramientas de Toolbox y servicios de Azure de nivel inferior usando la identidad del agente. La plataforma controla el escalado, la persistencia del estado de sesión, la observabilidad y la administración del ciclo de vida.

En el diagrama siguiente se muestra cómo se divide la responsabilidad. Usted es el propietario del código que se ejecuta dentro del entorno de pruebas. La plataforma es propietaria del punto de conexión, la identidad, el escalado y el estado de la sesión que lo rodean.

Importante

Al usar agentes hospedados con otros productos y servicios de Microsoft, debe leer toda la documentación pertinente para estos productos y servicios y comprender los riesgos y consideraciones de cumplimiento relacionados.

Si usa el Agente hospedado con cualquier servidor, agente, código o modelos directos que no sean de Azure ("Sistemas de terceros"), lo haga en su propio riesgo. Los sistemas de terceros son Productos que no son Microsoft en virtud de los términos del producto Microsoft y se rigen por sus propios términos de licencia de terceros. Usted es responsable de cualquier uso y costos asociados.

Se recomienda revisar todos los datos que se comparten y reciben de sistemas de terceros y ser conscientes de las prácticas de terceros para controlar, compartir, conservar y ubicación de los datos. Del mismo modo, si se conecta a servicios y características de Microsoft ajenos a Foundry o se integra con ellos, es importante revisar sus prácticas de tratamiento de datos. Es su responsabilidad gestionar si sus datos se transferirán fuera de los límites geográficos y de cumplimiento normativo de su organización, así como cualquier implicación relacionada, y garantizar que se concedan los permisos, límites y aprobaciones adecuados.

Es responsable de revisar y probar cuidadosamente las aplicaciones que compile en el contexto de sus casos de uso específicos y de tomar todas las decisiones y personalizaciones adecuadas. Esto incluye implementar sus propias mitigaciones de IA responsables, como metaprompts, filtros de contenido u otros sistemas de seguridad, y garantizar que las aplicaciones cumplan los estándares de calidad, confiabilidad, seguridad y confiabilidad adecuados. Consulte la nota de transparencia del servicio Foundry Agent.

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 Respuestas, Invocaciones e Invocaciones (WebSocket) están disponibles en todas las regiones que admiten agentes hospedados.

¿Qué protocolo debo usar?

Escenario	Protocolo	Por qué
Bot de chat o asistente conversacionales	Respuestas	La plataforma administra el historial de conversaciones, los eventos de streaming y el ciclo de vida de la sesión; use cualquier SDK compatible con OpenAI como cliente.
Preguntas y respuestas de varios turnos con RAG o herramientas	Respuestas	Subprocesos con identificadores de conversación integrados y control de resultados de herramientas.
Procesamiento en segundo plano o asincrónico	Respuestas	`background: true` con sondeo y cancelación administrados por la plataforma. Seleccione esta opción por separado si el manejador debe recuperarse tras una interrupción de un proceso.
Agente publicado en Teams o Microsoft 365	Respuestas + Actividad	El protocolo de respuestas (Responses) gestiona la lógica del agente; mientras que la plataforma conecta automáticamente estas respuestas con el protocolo de actividad (Activity) para enviarlos al canal.
Receptor de webhook (GitHub, Stripe, Jira, etc.)	Invocaciones	El sistema externo envía su propio formato de carga: no se puede cambiar para que coincida con /responses.
Procesamiento no conversacional (clasificación, extracción, lote)	Invocaciones	La entrada es datos estructurados, no un mensaje de chat. Entrada de JSON arbitrario, salida de JSON arbitrario.
Protocolo de streaming personalizado (AG-UI, etc.)	Invocaciones	AG-UI y otros protocolos de interfaz de agente no son compatibles con OpenAI y necesita un control directo de SSE.
Puente de protocolo (GitHub Copilot, sistemas propietarios)	Invocaciones	El autor de la llamada tiene su propio protocolo que no se asigna a /responses.
Agente de voz en tiempo real (entrada de micrófono, salida de voz)	Invocaciones (WebSocket)	Streaming bidireccional a través de una única conexión persistente. Empareja con Pipecat, LiveKit o Voice Live en tu contenedor. Consulte Crear un agente de voz.

Sugerencia

¿No estoy seguro? Comience con respuestas. Siempre puede agregar más adelante un endpoint de invocaciones; un agente alojado puede admitir ambos protocolos simultáneamente.

El protocolo que elija determina la carga útil que recibe su contenedor y qué parte de la sesión, la transmisión en tiempo real y el ciclo de vida en segundo plano gestiona la plataforma por usted. Un solo agente puede admitir más de un protocolo, por lo que esta opción no es permanente. Use el siguiente árbol de decisión para elegir un punto de partida.

Comparación de protocolos

	Respuestas	Invocaciones
Mejor para	La mayoría de los agentes: la plataforma administra el historial de conversaciones, el ciclo de vida de streaming y la ejecución en segundo plano	Agentes que necesitan control HTTP total, cargas personalizadas o flujos de trabajo asincrónicos de ejecución prolongada
Carga útil	Contrato /responses compatible con OpenAI	JSON arbitrario a través de /invocaciones: se define el esquema
SDK de cliente	Cualquier SDK compatible con OpenAI (Python, JS, C#) funciona de forma predeterminada.	Cliente personalizado: define el contrato.
Historial de sesiones	Administrado por la plataforma mediante el identificador de conversación	Tú administras sesiones (en memoria, Cosmos DB, etc.)
Streaming	ResponseEventStream administrado por la plataforma con eventos de ciclo de vida	SSE sin procesar: se da formato a los eventos y se escriben directamente
Segundo plano/de larga duración	Modo en segundo plano integrado y sondeo; recuperación resiliente opcional de respuestas almacenadas en segundo plano	Tareas robustas en el SDK de AgentServer; defines puntos de conexión de consulta o streaming

El modo en segundo plano y la ejecución resistente resuelven diferentes problemas. El modo en segundo plano permite que el trabajo continúe una vez que se devuelva la solicitud inicial. La ejecución resistente conserva el trabajo después de que se detenga el proceso de hospedaje. Para conocer las responsabilidades del modelo de recuperación y de la aplicación, consulte Resilience for long-running hosted agents (Resistencia para agentes hospedados de larga duración).

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/{project}/agents/{name}/punto de conexión/protocols/invocations_ws?api-version=v1
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 la versión del agente. Establezca esta definición en el servicio azure.ai.agent en azure.yaml al usar azd, o a través de protocol_versions al usar el SDK.

Hay dos identidades implicadas:

Identidad	Ámbito	Propósito
Microsoft Entra ID (identidad del agente, por agente)	Creado automáticamente en tiempo de implementación	La identidad con la que se autentica el contenedor del agente en tiempo de ejecución. Se usa para la invocación de modelos, el acceso a herramientas y los servicios Azure de bajada.
Identidad administrada de proyecto (a nivel de proyecto)	Asignado por el sistema en el proyecto Foundry	Lo usa la plataforma para las operaciones de infraestructura (por ejemplo, Lector del repositorio del Registro de Contenedores en el registro de contenedores). No la identidad en tiempo de ejecución del agente.

La identidad del agente puede acceder a la inferencia de modelos a través del punto de conexión del proyecto y al almacenamiento de sesión de forma predeterminada. Para los recursos externos (por ejemplo, su propio Azure Storage), asigne roles de RBAC manualmente al Microsoft Entra ID del agente. Para obtener más información, consulte Acceso del agente más allá de los valores predeterminados.

Cuando se integra a través de canales 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 llamar a servicios posteriores en nombre del usuario utilizando los permisos delegados de este, sujetos 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: puede configurar el tiempo de espera de inactividad por versión del agente de 5 a 60 minutos, con un valor predeterminado de 15 minutos. Si no llega ninguna solicitud dentro de esa ventana, la plataforma desaprovisiona el proceso y conserva el estado de sesión. La plataforma elimina permanentemente una sesión 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

Estado	¿Qué ocurre?
Activo	La computación está en funcionamiento. Las solicitudes se enrutan a este sistema. $HOME y el contenido de /files están disponibles.
Inactivo	No hay solicitudes para el tiempo de espera de inactividad configurado. La plataforma retira los recursos de cómputo y conserva el estado de la sesión ($HOME, `/files`).
Reanudación	Se vuelve a hacer referencia al mismo identificador de sesión. La plataforma aprovisiona nuevos recursos computacionales y restaura el estado persistido.

El cómputo sigue a la sesión, no a la petición individual. La plataforma aprovisiona un espacio aislado cuando se inicia una sesión y lo libera cuando transcurre el tiempo de espera de inactividad configurado después de la solicitud más reciente. Cuando se reanuda la sesión, la plataforma restaura $HOME y /files, por lo que el código encuentra los archivos que escribió anteriormente. En el diagrama siguiente se muestra cómo se mueve una solicitud a través de estos estados.

Seguridad y control de datos

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

Importante

Use sistemas de terceros en su propio riesgo e implemente siempre las mitigaciones de inteligencia artificial responsables adecuadas. Usted es responsable de gestionar todos los datos que podrían salir de los límites geográficos y de cumplimiento normativo de su organización. Obtenga más informació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. La versión es una instantánea de la imagen de contenedor, la asignación de recursos, las variables de entorno y la configuración del protocolo. Para actualizar el agente, cree e implemente una nueva versión.

Un punto de conexión del agente sirve una versión a la vez y enruta 100% de su tráfico a esa versión. No se admite la división de tráfico entre versiones.

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 tienen acceso completo a las herramientas administradas por Foundry, incluidas Code Interpreter, Web Search (con Grounding con Bing Custom Search), Búsqueda de Azure AI, OpenAPI, MCP, A2A, habilidades y más. Conectas estas herramientas mediante un endpoint MCP de Toolbox aprovisionado en tu proyecto de Foundry, en lugar de añadirlas directamente a la definición del agente. El kit de herramientas ofrece autenticación consolidada para la transferencia de identidad mediante OAuth, la identidad del agente, la autenticación basada en claves, entre otros métodos. Si usa Microsoft Agent Framework, conéctese mediante FoundryToolbox en Python o AddFoundryToolboxes en .NET en lugar de un cliente MCP genérico. Otros entornos de ejecución se conectan mediante bibliotecas cliente MCP estándar. Para obtener más información, consulte Curate intent-based toolbox in Foundry (Curar cuadro de herramientas basado en intenciones en Foundry).

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:

Unidad Central de Procesamiento (CPU)	Memoria
0,5 vCPU	1 GiB
1 vCPU	2 GiB
2 vCPU	4 GiB

Almacenamiento de sesión

Cada sesión tiene un valor persistente $HOME. La plataforma conserva su contenido cuando desaprovisiona los recursos de proceso tras el tiempo de espera de inactividad configurado. La plataforma restaura los contenidos cuando se reanuda la sesión, por lo que los archivos escritos bajo $HOME sobreviven a los periodos de inactividad. La plataforma escribe los archivos cargados a través del /files punto de conexión en $HOME, donde comparten el mismo almacenamiento. Cada sesión tiene un presupuesto total de disco de hasta 20 GiB en 1 vCPU o mayor, lo que se reduce proporcionalmente para niveles de CPU más pequeños. La plataforma reserva aproximadamente 20% de ese presupuesto para uso del sistema y no está visible ni 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 espacio aislado de máquina virtual para cada sesión a petición y mantiene su proceso activo mientras continúan las solicitudes. Cada solicitud restablece el temporizador de inactividad. Cuando vence el tiempo de inactividad configurado tras la solicitud más reciente, la plataforma desaprovisiona los recursos de computación del entorno aislado y persiste el estado de la sesión.

El tiempo de espera de inactividad puede ser de 5 a 60 minutos y el valor predeterminado es de 15 minutos. La plataforma elimina permanentemente una sesión después de 30 días de inactividad. No hay ningún recuento de réplicas para configurar y no hay ningún grupo intermedio para ajustar el tamaño.

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:

Abra el recurso de App Insights en el portal de Azure y seleccione Investigate>Performance.
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.

Nota

Los proyectos de Foundry creados después del 25 de junio de 2026 admiten una Azure Container Registry privada (protegida por la red) para la imagen del agente. Los proyectos creados antes de esa fecha requieren que el registro permanezca accesible a través de su punto de conexión público. Los proyectos existentes no se ven afectados. Para obtener más información, consulta Limitaciones.

Límites, precios y disponibilidad

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 Australia
Sur de Brasil
Centro de Canadá
Canada East
Central US
East US
Este de EE. UU. 2
Centro de Francia
Centro-oeste de Alemania
Norte de Italia
Este de Japón
Oeste de Japón
Centro de Corea del Sur
Centro-norte de EE. UU.
Este de Noruega
Centro de Polonia
Norte de Sudáfrica
Centro-sur de EE. UU.
Sur de la India
Sudeste asiático
Centro de España
Centro de Suecia
Norte de Suiza
Switzerland West
Norte de Emiratos Árabes Unidos
UK South
UK West
Centro-oeste de EE. UU.
West Europe
Oeste de EE. UU.
Oeste de EE. UU. 3