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. Encadena AddAsAIAgent para que el flujo de trabajo esté disponible para las integraciones con protocolos a través de la interfaz estándar del agente.
• 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.

Integración con ASP.NET Core

El paquete de hospedamiento compartido utiliza el host genérico de .NET y la inyecció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 las instancias denominadas AIAgent mediante inyección de dependencias y agregan asignaciones de rutas de ASP.NET Core.

Por ejemplo, el paquete de hospedamiento de OpenAI puede exponer un agente configurado a través de un punto de conexión de respuestas:

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

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

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

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

Consulte Puntos de conexión compatibles con OpenAI para obtener una configuración completa.

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 no HTTP puede usar los servicios de hospedaje compartido sin añadir extremos de protocolo de ASP.NET Core.

Adición de protocolos al servidor

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

Mantener sesiones alojadas

AgentSessionStore la persistencia es opcional para las integraciones de alojamiento que la utilizan. Sin un almacén configurado, esas integraciones 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.

Registra tu implementación duradera con inyección de dependencias y pásala al agente hospedado. Puede usar el almacén en memoria condicionalmente durante el desarrollo:

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

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

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

En este ejemplo, MyAgentSessionStore es la implementación persistente proporcionada por la aplicación. La rama de desarrollo supone un entorno local con un usuario de confianza y es la única ruta de acceso que deshabilita el aislamiento. La rama de producción mantiene el comportamiento de aislamiento predeterminado; configure un proveedor de claves de aislamiento como se describe en Continuación de sesión segura.

InMemoryAgentSessionStore pierde todas las sesiones cuando se cierra el proceso y no comparte el estado entre las instancias de la aplicación. Implemente el suyo propio AgentSessionStore con almacenamiento persistente para conservar las sesiones.

Un AgentSessionStore implementa operaciones asincrónicas de guardado, recuperación y eliminación. Recibe el AIAgent propietario y un ID de continuación opaco seleccionado por una integración de hospedamiento o una ruta propiedad de la aplicación, y debe devolver una instancia AgentSession independiente de cada operación get. Trata el ID de continuación como una clave opaca en los almacenes personalizados; la forma en que se interpreta el ID depende del protocolo.

Una implementación duradera tiene la siguiente estructura. Reemplace cada stub por las operaciones correspondientes a su sistema de almacenamiento elegido:

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

Indexa los registros tanto por agent.Id como por el sessionStoreId opaco. GetSessionAsync debe devolver una instancia de sesión independiente en cada llamada; use las API de serialización de sesión del agente propietario al almacenar el estado serializado. Las sesiones persistentes pueden contener datos confidenciales, por lo que los protegen con los controles de acceso y el cifrado adecuados.

AgentSessionStore conserva el AgentSession completo seleccionado por una solicitud hospedada, no solo los mensajes de la conversación. Dependiendo de la pila de agentes, una sesión puede contener un identificador de conversación administrado por el servicio, un historial de chat administrado por el marco de trabajo, el estado de la memoria o del proveedor de contexto, mensajes en cola, aprobaciones pendientes y otros estados que deben conservarse entre ejecuciones.

Los proveedores de historial controlan dónde se almacenan los mensajes de conversación. Cuando el historial se almacena en el estado de la sesión, al persistir la sesión también se persiste ese historial. Un proveedor de historial externo almacena los mensajes por separado; la sesión puede conservar un estado de referencia o proveedor relacionado.

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. Delimite las sesiones persistentes por usuario autenticado, tenant u otro límite de autorización antes de aceptar identificadores enviados por el cliente. El IsolationKeyScopedAgentSessionStore obtiene una clave de aislamiento de AgentIsolationKeyProvider, la combina con el identificador de continuación del protocolo y pasa el identificador de ámbito resultante al almacén subyacente. Como resultado, el mismo identificador de continuación con dos claves de aislamiento distintas corresponde a dos sesiones almacenadas diferentes, y un llamador solo puede recuperar las sesiones guardadas con la clave de aislamiento de ese llamador.

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

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

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

De forma predeterminada, UseClaimsBasedAgentIsolation usa la declaración ClaimTypes.NameIdentifier. Configura otra reclamación solo cuando sea estable y única para todos los solicitantes atendidos 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 predeterminado de aislamiento estricto, el acceso a la sesión falla cuando la identidad actual no proporciona la declaración configurada.

Para un host que no sea HTTP o para otro modelo de tenencia, registre un AgentIsolationKeyProvider personalizado. Las sobrecargas predeterminadas de WithInMemorySessionStore() y WithSessionStore(...) envuelven el almacén configurado en IsolationKeyScopedAgentSessionStore.

Pasos siguientes

Vaya más profundamente:

• Aloja 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