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.

Important

Los paquetes de hospedaje .NET son versión preliminar. Instale las versiones preliminares explícitamente y revise las notas de la versión antes de actualizar una implementación de producción.

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 alojamiento compartido usa 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 alojamiento de OpenAI puede exponer un agente configurado a través de un extremo de Responses:

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:

Protocol Integration
Puntos de conexión compatibles con OpenAI Finalizaciones de chat y puntos de conexión HTTP compatibles con respuestas
A2A Detección, mensajería y puntos de conexión de tareas de agente a agente
AG-UI Puntos de conexión de streaming de eventos para aplicaciones de agente web

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.

Important

MAF no incluye un almacén de sesiones duradero de uso general. Para producción, proporcione una AgentSessionStore implementación respaldada por el almacenamiento adecuado para la aplicación.

Registre la implementación duradera con la inserción de dependencias y pásela 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 identificador de continuación opaco seleccionado por una integración de hospedaje o una ruta propiedad de la aplicación, y debe devolver, en cada operación get, una instancia independiente de AgentSession. Considere el identificador de continuación como una clave opaca en almacenamientos personalizados; la forma de interpretar el identificador 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();
    }
}

Registros de claves tanto por agent.Id como por el elemento opaco sessionStoreId. 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 la opción completa AgentSession seleccionada por una solicitud hospedada, no solo los mensajes de conversación. En función de la pila del agente, una sesión puede contener un identificador de conversación administrado por el servicio, el historial de chat administrado por el marco, el estado de memoria o del proveedor de contexto, los mensajes en cola, las aprobaciones pendientes y otro estado que debe sobrevivir 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 con á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. 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 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

Adición de un punto de conexión compatible con OpenAI

Vaya más profundamente:

Note

Los asistentes de protocolo de autohospedaje no están disponibles actualmente para Go.

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.

Important

agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2ay agent-framework-hosting-mcp son paquetes de Python preliminares. Instale las versiones preliminares explícitamente y revise las notas de la versión antes de actualizar una implementación de producción.

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. La aplicación es responsable del almacenamiento de puntos de control y de cualquier asignación entre un identificador de continuación de 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. Subclase y invalide esos métodos para almacenar AgentSession objetos en Redis, una base de datos, un almacenamiento de blobs u otro almacén propiedad de la aplicación y, a continuación, pase la instancia a AgentState(session_store=...).

SessionStore y los proveedores de historial conservan 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 .

Note

El proveedor de historial predeterminado: InMemoryHistoryProvider es la excepción: almacena la conversación completa en AgentSession.state. Cuando se usa ese proveedor, SessionStore conserva la conversación dentro del objeto de sesión. Para conversaciones más largas o para almacenamiento en producción, use un proveedor de historial dedicado para que el almacén de sesión pueda seguir centrado en un estado de sesión ligero.

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:

Protocol Paquete e integración
Respuestas de OpenAI agent-framework-hosting-responses
Telegrama agent-framework-hosting-telegram
A2A agent-framework-a2a o agent-framework-hosting-a2a
MCP agent-framework-hosting-mcp

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. Conservar el estado de sesión y punto de comprobación solo después de que se haya completado la ejecución o secuencia.

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

Adición del protocolo de respuestas de OpenAI

Vaya más profundamente:

  • Last updated on