Anwendungen für selbstgehostete Agent-Frameworks

Mit Self-Hosting können Sie einen Agent Framework-Agent oder -Workflow in Ihrer eigenen ASP.NET Core Anwendung, Container, Dienst oder Laufzeit ausführen. Ihre Anwendung steuert Routing, Identität, Autorisierung, Anforderungsrichtlinie, Speicher, Bereitstellung und Skalierung. Fügen Sie dem Host Protokollintegrationen basierend auf den Clients hinzu, die Sie unterstützen müssen.

Verwenden Sie diese Option, wenn Sie einen Agentendpunkt in Ihre vorhandene Anwendungsinfrastruktur integrieren müssen. Wenn Sie möchten, dass Microsoft Foundry den Agent für Sie ausführt, lesen Sie foundry Hosted Agents. Wenn Sie Azure Functions Trigger oder dauerhafte Ausführung benötigen, lesen Sie "Durable Extension".

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

Was die Hostinghilfsprogramme bereitstellen

Das Microsoft.Agents.AI.Hosting Paket integriert Agents und Workflows in den .NET generischen Host:

• AddAIAgent registriert einen Benannten AIAgent mit Abhängigkeitsinjektion.
• AddWorkflow registriert einen benannten Workflow. Kette AddAsAIAgent , um den Workflow über die Standard-Agent-Schnittstelle für Protokollintegrationen verfügbar zu machen.
• IHostedAgentBuilder konfiguriert Hostingdienste, die diesem Agent zugeordnet sind.
• AgentSessionStore lädt und speichert AgentSession Instanzen optional anhand einer von der Anwendung oder dem Protokoll bereitgestellten Fortsetzungs-ID.

Das Hostingpaket ist kein HTTP-Server oder keine Protokollregistrierung. Ihre Anwendung wählt die gehosteten Agents und Workflows aus, konfiguriert ihre Dienste und fügt die benötigten Protokollendpunkte hinzu.

Beibehalten gehosteter Sitzungen

Die Sitzungspersistenz muss explizit aktiviert werden. Ohne eine konfigurierte AgentSessionStoreProtokollintegration kann für jede Anforderung eine neue Sitzung erstellt werden, der servereigene Sitzungsstatus kann jedoch von einer früheren Anforderung nicht wiederhergestellt werden.

Konfigurieren Sie für die Entwicklung oder für eine Anwendung mit einem einzelnen Prozess den integrierten In-Memory-Speicher:

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

Das Festlegen von withIsolation auf false ist nur dann geeignet, wenn ein vertrauenswürdiger Benutzer oder Prozess den Sitzungs-Namespace besitzt. InMemoryAgentSessionStore verliert alle Sitzungen, wenn der Prozess beendet wird und den Status nicht über Anwendungsinstanzen hinweg teilt.

Für persistentes oder verteiltes Hosting implementieren Sie AgentSessionStore und registrieren es mit WithSessionStore. Ein Speicher implementiert asynchrone Speicher-, Abrufen- und Löschvorgänge. Sie erhält das zugehörige AIAgent und eine opake Session-Store-ID und muss bei jedem get-Vorgang eine unabhängige AgentSession-Instanz zurückgeben.

AgentSessionStore und Verlaufsanbieter dienen verschiedenen Zwecken. Ein Sitzungsspeicher speichert die von einer gehosteten Anfrage ausgewählte AgentSession. Ein Verlaufs-Provider legt fest, wo Nachrichten einer Konversation gespeichert werden. Wenn der Verlauf im Sitzungszustand gespeichert ist, wird beim Persistieren der Sitzung auch dieser Verlauf persistiert; ein externer Verlaufsanbieter speichert Nachrichten separat.

Integration mit ASP.NET Core

Das Shared-Hosting-Paket verwendet den generischen Host von .NET und die Abhängigkeitsinjektion. Erstellen Sie für einen HTTP-Server eine ASP.NET Core Anwendung, und fügen Sie die protokollspezifischen Pakete für die Endpunkte hinzu, die Sie verfügbar machen möchten. Diese Pakete lösen benannte AIAgent-Instanzen über Dependency Injection auf und fügen ASP.NET-Core-Routenzuordnungen hinzu.

Ihre Anwendung bleibt für die Middlewarepipeline, Authentifizierung, Autorisierung, Anforderungsüberprüfung, zulässige Modelloptionen und dauerhaften Speicher verantwortlich. Ein Nicht-HTTP-Host kann die gemeinsamen Hostingdienste verwenden, ohne ASP.NET Core Protokollendpunkte hinzuzufügen.

Hinzufügen von Protokollen zu Ihrem Server

Wählen Sie die Protokollintegrationen aus, die Ihre Anwendung benötigt:

Jedes Protokoll definiert einen eigenen Fortsetzungsbezeichner und ein Endpunktverhalten. Behalten Sie Authentifizierung, Autorisierung, Sitzungsbesitz und dauerhaften Speicher in der freigegebenen Anwendungsinfrastruktur bei, anstatt sie für jeden Endpunkt erneut zu verwenden.

Sichere Sitzungsfortsetzung

Eine Fortsetzungs-ID identifiziert eine Fortsetzungssitzung, die fortgesetzt werden soll; es beweist nicht, dass der Aufrufer diese Sitzung besitzt. Persistierte Sitzungen einem authentifizierten Benutzer, einem Mandanten oder einer anderen Autorisierungsgrenze zuordnen, bevor vom Client bereitgestellte IDs akzeptiert werden.

Installieren Sie für ASP.NET Core Anwendungen, die die anspruchsbasierte Authentifizierung verwenden, das Microsoft.Agents.AI.Hosting.AspNetCore Vorabversionspaket, registrieren Sie den anspruchsbasierten Isolationsanbieter, und lassen Sie die Isolation im Sitzungsspeicher aktiviert:

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

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

Standardmäßig verwendet UseClaimsBasedAgentIsolation den ClaimTypes.NameIdentifier Anspruch. Konfigurieren Sie einen anderen Anspruchstyp nur, wenn dieser bei allen vom Store bedienten Aufrufern stabil und eindeutig ist. Der Isolationsanbieter authentifiziert keine Anforderungen; konfigurieren Sie ASP.NET Core Authentifizierung und Autorisierung separat. Bei dem standardmäßigen strikten Isolationsverhalten schlägt der Sitzungszugriff fehl, wenn der aktuelle Prinzipal den konfigurierten Anspruch nicht bereitstellt.

Registrieren Sie für einen Nicht-HTTP-Host oder ein anderes Mandantenmodell einen benutzerdefinierten AgentIsolationKeyProvider. Die standardmäßigen WithInMemorySessionStore()- und WithSessionStore(...)-Überladungen packen den konfigurierten Speicher in IsolationKeyScopedAgentSessionStore ein.

Nächste Schritte

Gehen Sie tiefer:

• Agenten mit A2A hosten
• Erstellen von Web-Agent-Anwendungen mit AG-UI
• In Foundry gehostete Agenten

Mit Self-Hosting können Sie einen Agent Framework-Agent oder -Workflow in Ihrer eigenen Webanwendung, Container, Dienst oder Laufzeit ausführen. Ihre Anwendung steuert Routing, Identität, Autorisierung, Anforderungsrichtlinie, Speicher, Bereitstellung und Skalierung. Fügen Sie diesem Server basierend auf den Clients, die Sie unterstützen müssen, eine oder mehrere Protokollintegrationen hinzu.

Verwenden Sie diese Option, wenn Sie einen Agentendpunkt in Ihre vorhandene Anwendungsinfrastruktur integrieren müssen. Wenn Sie möchten, dass Microsoft Foundry den Agent für Sie ausführt, lesen Sie foundry Hosted Agents. Wenn Sie Azure Functions Trigger oder dauerhafte Ausführung benötigen, lesen Sie "Durable Extension".

Das Design dieser Pakete ist so, dass die maximale Flexibilität für den Entwickler möglich ist. Dies bedeutet, dass Sie, wenn Sie einen Host erstellen möchten, der einen Agent über die Responses API bereitstellt, und die Parameter für andere Zwecke zweckentfremden (d. h. temperature auf top_p abbilden), dies tun können. Wenn Sie keine Sitzungen speichern möchten, können Sie das tun. Wenn Sie dem Anrufer die vollständige Steuerung des gesamten Agentenlaufs ermöglichen möchten, können Sie auch das tun. Wir stehen Ihnen nicht im Weg, bieten Hilfsmittel für die gängigen Fälle und legen den Rest in Ihre Verantwortung, damit Sie exakt den Host erstellen können, den Sie benötigen.

pip install --pre agent-framework-hosting

Was die Hostinghilfsprogramme bereitstellen

Das generische Hostingpaket stellt den Status der gemeinsamen Ausführung für einen anwendungseigenen Server bereit:

• AgentState koppelt ein Agentziel mit einer SessionStore und erstellt Sitzungen, wenn die Anwendung einen neuen Schlüssel auswählt.
• SessionStore speichert, ruft Sitzungen anhand einer von der Anwendung ausgewählten ID ab und löscht sie. Sein Standardspeicher ist prozesslokal und verfügt über keine Verdrängungsstrategie.
• WorkflowState ermittelt ein Workflowziel. Ihre Anwendung besitzt den Prüfpunktspeicher und jede Zuordnung von einer Client-Fortsetzungs-ID zu einem Prüfpunkt.

AgentState ist kein Server oder keine Protokollregistrierung. Ihre Anwendung wählt einen autorisierten Sitzungsschlüssel aus, löst das Ziel auf und speichert den Status nach der Ausführung. Sie kann dieselbe Zielinfrastruktur und dieselbe gemeinsam genutzte Anwendungsinfrastruktur für einen oder mehrere Protokollendpunkte verwenden.

Anpassen des Sitzungsspeichers

SessionStore ist eine kleine asynchrone Speicherklasse mit get, setund delete Methoden. Die Standardimplementierung behält Sitzungen im Prozessspeicher bei. Leiten Sie eine Unterklasse davon ab und überschreiben Sie diese Methoden, um AgentSession-Objekte in Redis, einer Datenbank, einem Blobspeicher oder einem anderen anwendungseigenen Datenspeicher zu speichern, und übergeben Sie dann die Instanz an AgentState(session_store=...).

SessionStore und Verlaufsanbieter speichern getrennte Teile einer Konversation eines Agenten. Ein Sitzungsspeicher speichert ein Sitzungsobjekt pro Sitzungs-ID, einschließlich Sitzungsmetadaten und Anbieterstatus. Ein dedizierter HistoryProvider speichert die Unterhaltung separat, in der Regel als einen Datensatz pro Nachricht. Diese Trennung wird für persistente Hosts empfohlen, da das Anhängen einzelner Nachrichten im Allgemeinen effizienter ist als das Neuschreiben eines wachsenden Sitzungsobjekts nach jedem Austausch. Ein Verlaufsanbieter wird pro Agent definiert, indem die gewünschte Verlaufsanbieterklasse an den Parameter übergeben wird context_providers .

Verwenden Sie Ihr eigenes Framework oder Ihre eigene Clientbibliothek

Die Hostingpakete sind nicht an ein Webframework oder eine Clientbibliothek gebunden. Die Beispiele verwenden FastAPI und aiogram da sie präzise runnable Beispiele bereitstellen, nicht weil die Hilfsprogramme sie benötigen.

• Verwenden Sie für HTTP-Endpunkte die Routing- und Anforderungs-/Antwort-APIs Ihres Anwendungsframeworks, z. B. FastAPI, Starlette, Django, Flask, Azure Functions oder ein anderes Framework.
• Verwenden Sie für Protokollclients wie Telegram jede Clientbibliothek, die eine Protokollaktualisierung bereitstellen und die vom Hilfsprogramm erstellten Vorgänge ausführen kann.

Die Anwendung wählt das Framework und die Clientbibliothek aus; Das Agent Framework-Paket konvertiert nur Protokolldaten und verwaltet optionalen Ausführungszustand. Sie registrieren keine Routen, authentifizieren keine Anrufer, autorisieren keinen Zugriff auf den Zustand, wählen keine zulässigen Modelloptionen aus und stellen keine dauerhafte Speicherung bereit.

Hinzufügen von Protokollen zu Ihrem Server

Wählen Sie eine oder mehrere Protokollintegrationen aus:

Jede Protokollseite beschreibt die Einrichtung. Sie sind jedoch so konzipiert, dass Sie einen einzelnen Host mit einem oder mehreren aktivierten Protokollen und einem aufrufbaren Ziel erstellen können. entweder ein Agent oder ein Workflow. Da wir Sie nicht auf ein Webframework beschränken, können Sie das gewünschte Webframework auswählen und den Host mit diesen Protokollen problemlos einrichten.

Sichere Sitzungsfortsetzung

Behandeln Sie jeden vom Protokoll bereitgestellten Bezeichner als nicht vertrauenswürdige Eingabe. Bevor Sie eine ID zum Laden einer Sitzung, eines Prüfpunkts, einer Aufgabe oder eines anderen Zustands verwenden:

1. Authentifizieren sie den Anrufer.
2. Autorisieren Sie den Aufrufer für den Zugriff auf den Referenzstatus.
3. Persistenten Zustand nach dem authentifizierten Mandanten, Benutzer oder Arbeitsbereich partitionieren.
4. Speichern Sie den Sitzungs- und Prüfpunktstatus nur, nachdem die Ausführung oder der Datenstrom abgeschlossen wurde.

Mit diesem Self-Hosting-Muster kann Ihre Anwendung nur die benötigten Protokollendpunkte und Richtlinien implementieren. es wird nicht versucht, die vollständige API-Oberfläche jedes unterstützten Protokolls zu implementieren.

Nächste Schritte

Gehen Sie tiefer:

• Telegramm
• A2A
• MCP
• In Foundry gehostete Agenten