Applications Agent Framework auto-hébergées

L’auto-hébergement vous permet d’exécuter un agent Agent Framework ou un workflow dans votre propre application, conteneur, service ou runtime ASP.NET Core. Votre application contrôle le routage, l’identité, l’autorisation, la stratégie de demande, le stockage, le déploiement et la mise à l’échelle. Ajoutez des intégrations de protocole à l’hôte en fonction des clients que vous devez prendre en charge.

Utilisez cette option lorsque vous devez intégrer un point de terminaison d’agent à votre infrastructure d’application existante. Si vous souhaitez que Microsoft Foundry exécute l’agent pour vous, consultez Agents hébergés de Foundry. Si vous avez besoin de déclencheurs Azure Functions ou de l’exécution durable, consultez l’extension Durable.

Important

Les packages d’hébergement .NET sont préversions. Installez des versions préliminaires explicitement et passez en revue les notes de publication avant de mettre à jour un déploiement de production.

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

Que fournissent les helpers d’hébergement

Le Microsoft.Agents.AI.Hosting package intègre des agents et des flux de travail à l’hôte générique .NET :

  • AddAIAgent inscrit un nom AIAgent avec l’injection de dépendances.
  • AddWorkflow inscrit un flux de travail nommé. Chaîne AddAsAIAgent pour rendre le flux de travail disponible pour les intégrations de protocole via l’interface de l’agent standard.
  • IHostedAgentBuilder configure les services d’hébergement associés à cet agent.
  • AgentSessionStore charge et enregistre éventuellement des AgentSession instances par un ID de continuation fourni par une application ou un protocole.

Le package d’hébergement n’est pas un serveur HTTP ni un registre de protocole. Votre application sélectionne les agents hébergés et les flux de travail, configure leurs services et ajoute les points de terminaison de protocole dont elle a besoin.

Conserver les sessions hébergées

La persistance de session est opt-in. Sans configuration AgentSessionStore, les intégrations de protocole peuvent créer une session pour chaque requête, mais ne peuvent pas récupérer l’état de session appartenant au serveur à partir d’une requête antérieure.

Pour le développement ou une application à processus unique, configurez le magasin intégré en mémoire :

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

false La définition withIsolation est appropriée uniquement lorsqu’un utilisateur ou un processus approuvé possède l’espace de noms de session. InMemoryAgentSessionStore perd toutes les sessions lorsque le processus quitte et ne partage pas l’état entre les instances d’application.

Pour un hébergement durable ou distribué, implémentez et inscrivez-le AgentSessionStore auprès WithSessionStorede . Un magasin implémente des opérations d’enregistrement, d’obtention et de suppression asynchrones. Il reçoit le propriétaire AIAgent et un ID de magasin de sessions opaques, et doit retourner une instance indépendante AgentSession de chaque opération get.

AgentSessionStore et les fournisseurs d’historique servent des objectifs différents. Un magasin de sessions conserve l’option AgentSession sélectionnée par une demande hébergée. Un fournisseur d’historique contrôle l’emplacement où les messages de conversation sont stockés. Lorsque l’historique est conservé dans l’état de session, la persistance de la session conserve également cet historique ; un fournisseur d’historique externe stocke les messages séparément.

Intégrer à ASP.NET Core

Le package d’hébergement partagé utilise l'.NET hôte générique et l’injection de dépendances. Pour un serveur HTTP, créez une application ASP.NET Core et ajoutez les packages spécifiques au protocole pour les points de terminaison que vous souhaitez exposer. Ces packages résolvent les instances nommées AIAgent à partir de l’injection de dépendances et ajoutent ASP.NET Core mappages de routage.

Votre application reste responsable de son pipeline d’intergiciels, de l’authentification, de l’autorisation, de la validation des demandes, des options de modèle autorisées et du stockage durable. Un hôte non HTTP peut utiliser les services d’hébergement partagé sans ajouter de points de terminaison de protocole ASP.NET Core.

Ajouter des protocoles à votre serveur

Choisissez les intégrations de protocole dont votre application a besoin :

Protocol Integration
Points de terminaison compatibles OpenAI Saisie semi-automatique des conversations et points de terminaison HTTP compatibles avec les réponses
A2A Découverte, messagerie et points de terminaison de tâche de l’agent à agent
AG-UI Points de terminaison de streaming d’événements pour les applications d’agent web

Chaque protocole définit son propre identificateur de continuation et son comportement de point de terminaison. Conservez l’authentification, l’autorisation, la propriété de session et le stockage durable dans l’infrastructure d’application partagée plutôt que de les réexémettre pour chaque point de terminaison.

Continuation de session sécurisée

Un ID de continuation identifie une session à reprendre ; il ne prouve pas que l’appelant possède cette session. Étendue des sessions persistantes par un utilisateur authentifié, un locataire ou une autre limite d’autorisation avant d’accepter les ID fournis par le client.

Pour ASP.NET Core applications qui utilisent l’authentification basée sur les revendications, installez le package de préversionMicrosoft.Agents.AI.Hosting.AspNetCore, inscrivez le fournisseur d’isolation basé sur les revendications et conservez l’isolation activée sur le magasin de sessions :

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

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

Par défaut, UseClaimsBasedAgentIsolation utilise la ClaimTypes.NameIdentifier revendication. Configurez une autre revendication uniquement lorsqu’elle est stable et unique sur chaque appelant servi par le magasin. Le fournisseur d'isolation n'authentifie pas les demandes ; configurez ASP.NET Core l’authentification et l’autorisation séparément. Avec le comportement d’isolation strict par défaut, l’accès à la session échoue lorsque le principal actuel ne fournit pas la revendication configurée.

Pour un hôte non HTTP ou un autre modèle de location, inscrivez un modèle personnalisé AgentIsolationKeyProvider. La valeur par défaut WithInMemorySessionStore() et WithSessionStore(...) les surcharges encapsulent le magasin configuré dans IsolationKeyScopedAgentSessionStore.

Étapes suivantes

Ajouter un point de terminaison compatible OpenAI

Aller plus loin :

Note

Les utilitaires de protocole pour l’auto-hébergement ne sont actuellement pas disponibles pour Go.

L’auto-hébergement vous permet d’exécuter un agent Agent Framework ou un flux de travail dans votre propre application web, conteneur, service ou runtime. Votre application contrôle le routage, l’identité, l’autorisation, la stratégie de demande, le stockage, le déploiement et la mise à l’échelle. Ajoutez une ou plusieurs intégrations de protocole à ce serveur en fonction des clients que vous devez prendre en charge.

Utilisez cette option lorsque vous devez intégrer un point de terminaison d’agent à votre infrastructure d’application existante. Si vous souhaitez que Microsoft Foundry exécute l’agent pour vous, consultez Agents hébergés de Foundry. Si vous avez besoin de déclencheurs Azure Functions ou de l’exécution durable, consultez l’extension Durable.

La conception de ces packages est telle qu’elle permet une flexibilité maximale pour le développeur. Cela signifie que si vous souhaitez générer un hôte qui expose un agent avec l’API Réponses et abusez des paramètres à d’autres fins (par exemple mapper temperature à top_p), vous pouvez le faire. Si vous ne souhaitez pas stocker les sessions, c’est possible. Si vous souhaitez que l’appelant contrôle l’intégralité de l’exécution de l’agent, c’est également possible. Nous ne vous imposons aucune contrainte : nous fournissons des assistants pour les cas courants et vous laissons gérer le reste afin que vous puissiez créer exactement l’hôte nécessaire.

Important

agent-framework-hosting, , agent-framework-hosting-responses, agent-framework-hosting-telegramagent-framework-a2a, , agent-framework-hosting-a2aet agent-framework-hosting-mcp sont préversion Python packages. Installez des versions préliminaires explicitement et passez en revue les notes de publication avant de mettre à jour un déploiement de production.

pip install --pre agent-framework-hosting

Que fournissent les helpers d’hébergement

Le package d’hébergement générique fournit un état d’exécution partagé pour un serveur appartenant à l’application :

  • AgentState associe une cible d’agent à un SessionStore et crée des sessions lorsque l’application sélectionne une nouvelle clé.
  • SessionStore stocke, récupère et supprime des sessions par un ID sélectionné par l’application. Son stockage par défaut est local au processus et n’a pas de stratégie d’éviction.
  • WorkflowState résout une cible de flux de travail. Votre application gère le stockage des points de contrôle ainsi que toute correspondance entre un identifiant de continuation du client et un point de contrôle.

AgentState n’est pas un serveur ou un registre de protocoles. Votre application sélectionne une clé de session autorisée, résout la cible et enregistre l’état post-exécution. Il peut utiliser la même infrastructure d’application cible et partagée pour un ou plusieurs points de terminaison de protocole.

Personnaliser le stockage de session

SessionStore est une petite classe de stockage asynchrone avec get, setet delete des méthodes. L’implémentation par défaut conserve les sessions en mémoire du processus. Sous-classez-la et remplacez ces méthodes pour stocker AgentSession des objets dans Redis, une base de données, un stockage d’objets blob ou un autre magasin appartenant à l’application, puis passez l’instance à AgentState(session_store=...).

SessionStore et les fournisseurs d’historique stockent de façon persistante des parties distinctes d’une conversation d’un agent. Un magasin de sessions enregistre un objet de session par ID de session, y compris les métadonnées de session et l’état du fournisseur. Un espace dédié HistoryProvider stocke la conversation séparément, généralement sous la forme d’un enregistrement par message. Cette séparation est recommandée pour les hôtes durables, car l’ajout de messages individuels est généralement plus efficace que la réécriture d’un objet de session croissant après chaque tour. Un fournisseur d’historique est défini par agent, en passant la classe de fournisseur d’historique souhaitée au context_providers paramètre.

Note

Fournisseur d’historique par défaut : InMemoryHistoryProvider est l’exception : il stocke la conversation complète dans AgentSession.state. Lorsque ce fournisseur est utilisé, SessionStore conserve la conversation à l’intérieur de l’objet de session. Pour les conversations plus longues ou le stockage de production, utilisez un fournisseur d’historique dédié afin que le stockage des sessions puisse être consacré à un état de session léger.

Apportez votre propre infrastructure ou bibliothèque cliente

Les packages d’hébergement ne sont pas liés à un framework web ou à une bibliothèque cliente. Les exemples utilisent FastAPI et aiogram afin de proposer des exemples concis et exécutables, et non parce que les fonctions utilitaires l’exigent.

  • Pour les points de terminaison HTTP, utilisez les API de routage et de requête/réponse de votre infrastructure d’application, telles que FastAPI, Starlette, Django, Flask, Azure Functions ou un autre framework.
  • Pour les clients de protocole tels que Telegram, utilisez n’importe quelle bibliothèque cliente qui peut fournir une mise à jour de protocole et exécuter les opérations produites par l’assistance.

L’application sélectionne son framework et sa bibliothèque cliente ; Les packages Agent Framework convertissent uniquement les données de protocole et gèrent l’état d’exécution facultatif. Ils n’inscrivent pas les itinéraires, n’authentifient pas les appelants, n’autorisent pas l’accès à l’état, ne sélectionnent pas les options de modèle autorisées et ne fournissent pas de stockage durable.

Ajouter des protocoles à votre serveur

Choisissez une ou plusieurs intégrations de protocole :

Protocol Package et intégration
Réponses OpenAI agent-framework-hosting-responses
Télégramme agent-framework-hosting-telegram
A2A agent-framework-a2a ou agent-framework-hosting-a2a
MCP agent-framework-hosting-mcp

Chaque page de protocole décrit sa configuration. Toutefois, ils sont conçus pour vous permettre de créer un hôte unique avec un ou plusieurs protocoles activés et une cible pouvant être appelée ; un agent ou un flux de travail. Étant donné que nous ne vous limitons pas à un framework web, vous pouvez choisir celui souhaité et configurer l’hôte avec ces protocoles avec facilité.

Continuation de session sécurisée

Traitez chaque identificateur fourni par le protocole comme une entrée non approuvée. Avant d’utiliser un ID pour charger une session, un point de contrôle, une tâche ou un autre état :

  1. Authentifiez l’appelant.
  2. Autoriser l’appelant à accéder à l’état référencé.
  3. Partitionnez l’état persistant par locataire, utilisateur ou espace de travail authentifié.
  4. Conserver l’état de session et de point de contrôle uniquement une fois l’exécution ou le flux terminé.

Ce modèle d’auto-hébergement permet à votre application d’implémenter uniquement les points de terminaison de protocole et les stratégies dont elle a besoin ; elle ne tente pas d’implémenter la surface d’API complète de chaque protocole pris en charge.

Étapes suivantes

Ajouter le protocole Réponses OpenAI

Aller plus loin :

  • Last updated on