Aplicaciones de Agent Framework autohospedadas

El autohospedaje le permite ejecutar un agente o un flujo de trabajo de Agent Framework en su propia aplicación de ASP.NET Core, contenedor, servicio o tiempo de ejecución. La aplicación controla el enrutamiento, la identidad, la autorización, la directiva de solicitud, el almacenamiento, la implementación y el escalado. Agregue integraciones de protocolo al host en función de los clientes que necesite admitir.

Use esta opción cuando necesite integrar un punto de conexión de agente con la infraestructura de aplicaciones existente. Si desea que Microsoft Foundry ejecute el agente para usted, consulte Agentes hospedados de Foundry. Si necesita desencadenadores de Azure Functions o ejecución durable, consulte Extensión Durable.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

Qué proporcionan los asistentes de hospedaje

El Microsoft.Agents.AI.Hosting paquete integra agentes y flujos de trabajo con el host genérico .NET:

• AddAIAgent registra un objeto denominado AIAgent con inserción de dependencias.
• AddWorkflow registra un flujo de trabajo con nombre. Cadena AddAsAIAgent para que el flujo de trabajo esté disponible para las integraciones de protocolo a través de la interfaz del agente estándar.
• IHostedAgentBuilder configura los servicios de hospedaje asociados a ese agente.
• AgentSessionStore opcionalmente, carga y guarda AgentSession instancias mediante un identificador de continuación proporcionado por la aplicación o el protocolo.

El paquete de hospedaje no es un servidor HTTP ni un registro de protocolo. La aplicación selecciona los agentes y flujos de trabajo hospedados, configura sus servicios y agrega los puntos de conexión de protocolo que necesita.

Conservar sesiones hospedadas

La persistencia de la sesión es opcional. Sin una integración de protocolo configurada AgentSessionStore, las integraciones de protocolo pueden crear una nueva sesión para cada solicitud, pero no pueden recuperar el estado de sesión propiedad del servidor de una solicitud anterior.

Para el desarrollo o una aplicación de proceso único, configure el almacén integrado en memoria:

builder.AddAIAgent("weather-agent", (_, _) => agent)
    .WithInMemorySessionStore(withIsolation: false);

Establecer withIsolation en false es adecuado solo cuando un usuario o proceso de confianza posee el espacio de nombres de sesión. InMemoryAgentSessionStore pierde todas las sesiones cuando se cierra el proceso y no comparte el estado entre las instancias de la aplicación.

Para hospedaje duradero o distribuido, implemente AgentSessionStore y regístrelo con WithSessionStore. Un almacén implementa operaciones asincrónicas de guardado, obtención y eliminación. Recibe el propietario AIAgent y un identificador de almacén de sesión opaco, y debe devolver una instancia independiente AgentSession de cada operación get.

AgentSessionStore y los proveedores de historial sirven para diferentes propósitos. Un almacén de sesiones conserva el AgentSession seleccionado por una solicitud hospedada. Un proveedor de historial controla dónde se almacenan los mensajes de conversación. Cuando el historial se mantiene en estado de sesión, la conservación de la sesión también conserva ese historial; Un proveedor de historial externo almacena los mensajes por separado.

Integración con ASP.NET Core

El paquete de hospedaje compartido usa el .NET host genérico y la inserción de dependencias. Para un servidor HTTP, cree una aplicación de ASP.NET Core y agregue los paquetes específicos del protocolo para los puntos de conexión que desea exponer. Esos paquetes resuelven instancias con nombre AIAgent de la inserción de dependencias y agregan ASP.NET Core asignaciones de rutas.

La aplicación sigue siendo responsable de su canalización de middleware, autenticación, autorización, validación de solicitudes, opciones de modelo permitidas y almacenamiento duradero. Un host que no es HTTP puede usar los servicios de hospedaje compartidos sin agregar puntos de conexión de protocolo ASP.NET Core.

Adición de protocolos al servidor

Elija las integraciones de protocolo que necesita la aplicación:

Cada protocolo define su propio identificador de continuación y comportamiento del punto de conexión. Mantenga la autenticación, la autorización, la propiedad de la sesión y el almacenamiento duradero en la infraestructura de aplicaciones compartidas en lugar de volver a implementarlos para cada punto de conexión.

Continuación de sesión segura

Un identificador de continuación identifica una sesión que se va a reanudar; no demuestra que el autor de la llamada posee esa sesión. Ámbito de las sesiones persistentes por un usuario autenticado, inquilino u otro límite de autorización antes de aceptar identificadores proporcionados por el cliente.

Para ASP.NET Core aplicaciones que usan la autenticación basada en notificaciones, instale el paquete de versión Microsoft.Agents.AI.Hosting.AspNetCore preliminar, registre el proveedor de aislamiento basado en notificaciones y mantenga habilitado el aislamiento en el almacén de sesiones:

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

builder.AddAIAgent("weather-agent", (_, _) => agent)
    .WithInMemorySessionStore();

De forma predeterminada, UseClaimsBasedAgentIsolation usa la ClaimTypes.NameIdentifier notificación . Configure otra notificación solo cuando sea estable y única en cada llamador servido por el almacén. El proveedor de aislamiento no autentica las solicitudes; configure ASP.NET Core autenticación y autorización por separado. Con el comportamiento de aislamiento estricto predeterminado, se produce un error en el acceso a la sesión cuando la entidad de seguridad actual no proporciona la notificación configurada.

Para un host que no sea HTTP u otro modelo de inquilino, registre un personalizado AgentIsolationKeyProvider. Los valores predeterminados WithInMemorySessionStore() y WithSessionStore(...) sobrecargas encapsulan el almacén configurado en IsolationKeyScopedAgentSessionStore.

Pasos siguientes

Vaya más profundamente:

• Hosts de agentes con A2A
• Compilación de aplicaciones de agente web con AG-UI
• Agentes alojados de Foundry

El autohospedaje permite ejecutar un agente o un flujo de trabajo de Agent Framework en su propia aplicación web, contenedor, servicio o tiempo de ejecución. La aplicación controla el enrutamiento, la identidad, la autorización, la directiva de solicitud, el almacenamiento, la implementación y el escalado. Agregue una o varias integraciones de protocolos a ese servidor en función de los clientes que necesite admitir.

Use esta opción cuando necesite integrar un punto de conexión de agente con la infraestructura de aplicaciones existente. Si desea que Microsoft Foundry ejecute el agente para usted, consulte Agentes hospedados de Foundry. Si necesita desencadenadores de Azure Functions o ejecución durable, consulte Extensión Durable.

El diseño de estos paquetes es tal que permite la máxima flexibilidad para el desarrollador. Esto significa que, si quiere crear un host que exponga un agente con la Responses API y usar indebidamente los parámetros para otros fines (es decir, asignar temperature a top_p), puede hacerlo. Si no desea almacenar sesiones, puede hacerlo, si desea permitir que el autor de la llamada controle la ejecución completa del agente, también puede hacerlo. No nos interpondremos: ofrecemos utilidades para los casos habituales y dejamos el resto en sus manos, para que pueda crear el host exacto que necesita.

pip install --pre agent-framework-hosting

Qué proporcionan los asistentes de hospedaje

El paquete de hospedaje genérico proporciona el estado de ejecución compartido para un servidor propiedad de la aplicación:

• AgentState empareja un destino de agente con SessionStore y crea sesiones cuando la aplicación selecciona una nueva clave.
• SessionStore almacena, recupera y elimina sesiones mediante un identificador seleccionado por la aplicación. Su almacén predeterminado es process-local y no tiene ninguna directiva de expulsión.
• WorkflowState determina un destino del flujo de trabajo. Tu aplicación es responsable del almacenamiento de los puntos de control y de cualquier asignación entre un ID de continuación del cliente y un punto de control.

AgentState no es un servidor ni un registro de protocolo. La aplicación selecciona una clave de sesión autorizada, resuelve el destino y guarda el estado posterior a la ejecución. Puede usar la misma infraestructura de aplicaciones compartidas y de destino para uno o varios puntos de conexión de protocolo.

Personalización del almacenamiento de sesión

SessionStore es una pequeña clase de almacenamiento asincrónica con getmétodos , sety delete . La implementación predeterminada mantiene las sesiones en la memoria del proceso. Crea una subclase y sobrescribe esos métodos para almacenar objetos AgentSession en Redis, una base de datos, un almacenamiento de blobs u otro almacén propiedad de la aplicación; a continuación, pasa la instancia a AgentState(session_store=...).

Los proveedores de historial SessionStore y persisten partes independientes de una conversación del agente. Un almacén de sesiones guarda un objeto de sesión por identificador de sesión, incluidos los metadatos de sesión y el estado del proveedor. Un dedicado HistoryProvider almacena la conversación por separado, normalmente como un registro por mensaje. Esta separación se recomienda para hosts duraderos porque anexar mensajes individuales suele ser más eficaz que volver a escribir un objeto de sesión creciente después de cada turno. Un proveedor de historial se define por agente pasando la clase de proveedor de historial deseada al context_providers parámetro .

Traiga su propio marco o biblioteca cliente

Los paquetes de hospedaje no están vinculados a un marco web ni a una biblioteca cliente. Los ejemplos usan FastAPI y aiogram , dado que proporcionan ejemplos ejecutables concisos, no porque los asistentes los requieren.

• Para los puntos de conexión HTTP, use las API de enrutamiento y solicitud y respuesta del marco de la aplicación, como FastAPI, Starlette, Django, Flask, Azure Functions u otro marco.
• Para clientes de protocolo como Telegram, use cualquier biblioteca cliente que pueda proporcionar una actualización de protocolo y ejecutar las operaciones producidas por el asistente.

La aplicación selecciona su marco y biblioteca cliente; Los paquetes de Agent Framework solo convierten los datos de protocolo y administran el estado de ejecución opcional. No registran rutas, autentican a quienes realizan las llamadas, autorizan el acceso al estado, eligen las opciones de modelo permitidas ni proporcionan almacenamiento duradero.

Adición de protocolos al servidor

Elija una o varias integraciones de protocolo:

Cada página de protocolo describe su configuración. Sin embargo, están diseñados para permitirle crear un único host con uno o varios protocolos habilitados y un destino invocable; ya sea un agente o un flujo de trabajo. Puesto que no le limitamos a un marco web, puede elegir el que desee y configurar el host con esos protocolos con facilidad.

Continuación de sesión segura

Trate cada identificador proporcionado por el protocolo como entrada que no es de confianza. Antes de usar un identificador para cargar una sesión, un punto de control, una tarea u otro estado:

1. Autentíquese al autor de la llamada.
2. Autorice al autor de la llamada para acceder al estado al que se hace referencia.
3. Divida el estado persistente por tenant autenticado, usuario o espacio de trabajo.
4. Persiste el estado de la sesión y del punto de control solo una vez que la ejecución o la transmisión haya finalizado.

Este patrón de autohospedaje permite a la aplicación implementar solo los puntos de conexión de protocolo y las directivas que necesita; no intenta implementar la superficie de API completa de todos los protocolos admitidos.

Pasos siguientes

Vaya más profundamente:

• Telegrama
• A2A
• MCP
• Agentes alojados de Foundry