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".

Important

Die .NET Hostingpakete sind Vorabversionen. Installieren Sie Vorabversionen explizit, und überprüfen Sie die Versionshinweise, bevor Sie eine Produktionsbereitstellung aktualisieren.

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.

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.

Beispielsweise kann das OpenAI-Hostingpaket einen konfigurierten Agent über einen Antwortendpunkt verfügbar machen:

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();

Eine vollständige Konfiguration finden Sie unter OpenAI-kompatible Endpunkte .

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:

Protocol Integration
OpenAI-kompatible Endpunkte Chatabschlusse und antwortenkompatible HTTP-Endpunkte
A2A Agent-zu-Agent-Ermittlung, Messaging- und Aufgabenendpunkte
AG-UI Event-Streaming-Endpunkte für Web-Agent-Anwendungen

Beibehalten gehosteter Sitzungen

AgentSessionStore Persistenz ist für Hosting-Integrationen, die sie verwenden, optional und muss ausdrücklich aktiviert werden. Ohne einen konfigurierten Speicher können diese Integrationen eine neue Sitzung für jede Anforderung erstellen, aber den Sitzungsstatus des Servers nicht aus einer früheren Anforderung wiederherstellen.

Important

MAF enthält keinen allgemein verwendbaren persistenten Sitzungsspeicher. Stellen Sie für die Produktion eine AgentSessionStore Implementierung bereit, die durch den für Ihre Anwendung geeigneten Speicher unterstützt wird.

Registrieren Sie Ihre dauerhafte Implementierung mit Abhängigkeitsinjektion, und übergeben Sie sie an den gehosteten Agent. Sie können den speicherinternen Speicher während der Entwicklung bedingt verwenden:

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>());
}

In diesem Beispiel ist MyAgentSessionStore die von Ihrer Anwendung bereitgestellte dauerhafte Implementierung. Der Entwicklungszweig setzt eine lokale Umgebung mit einem vertrauenswürdigen Benutzer voraus und ist der einzige Pfad, der die Isolation deaktiviert. Der Produktionszweig behält das Standardisolationsverhalten bei; konfigurieren Sie einen Isolationsschlüsselanbieter, wie in der Fortsetzung der sicheren Sitzung beschrieben.

InMemoryAgentSessionStore verliert alle Sitzungen, wenn der Prozess beendet wird und den Status nicht über Anwendungsinstanzen hinweg teilt. Implementieren Sie Ihr eigenes AgentSessionStore mit persistenter Speicherung, um Sitzungen beizubehalten.

Ein AgentSessionStore implementiert asynchrone Speicher-, Abrufen- und Löschvorgänge. Sie erhält die zugehörige AIAgent und eine undurchsichtige Fortsetzungs-ID, die von einer Hostingintegration oder einer anwendungseigenen Route ausgewählt wird, und muss bei jedem get-Vorgang eine unabhängige AgentSession-Instanz zurückgeben. Behandeln Sie die Fortsetzungs-ID in benutzerdefinierten Speichern als opaken Schlüssel; wie die ID interpretiert wird, hängt vom Protokoll ab.

Eine dauerhafte Implementierung weist die folgende Struktur auf. Ersetzen Sie jeden Stub durch Vorgänge für Ihr ausgewähltes Speichersystem:

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();
    }
}

Schlüsseldatensätze sowohl durch agent.Id als auch durch die undurchsichtige sessionStoreId. GetSessionAsync muss bei jedem Aufruf eine unabhängige Sitzungsinstanz zurückgeben; verwenden Sie beim Speichern serialisierter Zustände die Sitzungsserialisierungs-APIs des besitzenden Agenten. Beibehaltene Sitzungen können vertrauliche Daten enthalten, sodass sie mit entsprechenden Zugriffssteuerungen und Verschlüsselung geschützt werden.

AgentSessionStore speichert den vollständigen AgentSession, der von einer gehosteten Anforderung ausgewählt wurde, nicht nur Konversationsnachrichten. Je nach Agenten-Stack kann eine Sitzung eine vom Dienst verwaltete Konversations-ID, einen vom Framework verwalteten Chatverlauf, den Zustand des Speichers oder Kontextanbieters, Nachrichten in der Warteschlange, ausstehende Genehmigungen und andere Zustände enthalten, die über mehrere Ausführungen hinweg erhalten bleiben müssen.

Verlaufsanbieter legen fest, wo Konversationsnachrichten gespeichert werden. Wenn der Verlauf im Sitzungszustand gespeichert wird, wird beim Persistieren der Sitzung auch dieser Verlauf persistent gespeichert. Ein externer Verlaufsanbieter speichert Nachrichten separat; die Sitzung kann einen Verweis oder einen zugehörigen Anbieterstatus beibehalten.

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. Der IsolationKeyScopedAgentSessionStore ruft von AgentIsolationKeyProvider einen Isolationsschlüssel ab, kombiniert ihn mit der Protokollfortsetzungs-ID und übergibt die resultierende bereichsbezogene Kennung an den zugrunde liegenden Speicher. Daher wird dieselbe Fortsetzungs-ID unter zwei verschiedenen Isolationsschlüsseln in zwei verschiedene gespeicherte Sitzungen aufgelöst, und ein Anrufer kann nur Sitzungen abrufen, die mit dem Isolationsschlüssel des Anrufers gespeichert wurden.

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:

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

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

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

Hinzufügen eines openAI-kompatiblen Endpunkts

Gehen Sie tiefer:

Note

Self-Hosting-Protokollhilfsprogramme sind derzeit nicht für Go verfügbar.

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.

Important

agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2a und agent-framework-hosting-mcp sind Vorabversionen von Python-Paketen. Installieren Sie Vorabversionen explizit, und überprüfen Sie die Versionshinweise, bevor Sie eine Produktionsbereitstellung aktualisieren.

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. Eine dedizierte 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 Session-Objekts nach jedem Austausch. Ein Verlaufsanbieter wird pro Agent definiert, indem die gewünschte Verlaufsanbieterklasse an den Parameter übergeben wird context_providers .

Note

Der Standard-Verlaufsanbieter: InMemoryHistoryProvider ist die Ausnahme: Er speichert die vollständige Konversation in AgentSession.state. Wenn dieser Anbieter verwendet wird, SessionStore wird die Unterhaltung innerhalb des Sitzungsobjekts beibehalten. Verwenden Sie für längere Konversationen oder für die Datenspeicherung im Produktivbetrieb einen dedizierten Anbieter für den Verlauf, damit der Sitzungsspeicher auf den schlanken Sitzungszustand fokussiert bleibt.

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:

Protocol Paket und Integration
OpenAI-Antworten agent-framework-hosting-responses
Telegramm agent-framework-hosting-telegram
A2A agent-framework-a2a oder agent-framework-hosting-a2a
MCP agent-framework-hosting-mcp

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

Hinzufügen des OpenAI-Antwortprotokolls

Gehen Sie tiefer:

  • Last updated on