Zelfgehoste Agent Framework-toepassingen

Met selfhosting kunt u een Agent Framework-agent of -werkstroom uitvoeren in uw eigen ASP.NET Core toepassing, container, service of runtime. Uw toepassing bepaalt routering, identiteit, autorisatie, aanvraagbeleid, opslag, implementatie en schalen. Voeg protocolintegraties toe aan de host op basis van de clients die u moet ondersteunen.

Gebruik deze optie wanneer u een agenteindpunt moet integreren met uw bestaande toepassingsinfrastructuur. Als u wilt dat Microsoft Foundry de agent voor u uitvoert, raadpleegt u Foundry Hosted Agents. Als u triggers voor Azure Functions of duurzame uitvoeringen nodig hebt, raadpleegt u Durable Extension.

Belangrijk

De .NET hostingpakketten zijn vooraf beschikbaar. Installeer voorlopige versies expliciet en bekijk releaseopmerkingen voordat u een productie-implementatie bijwerkt.

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

Wat de hosting-helpers bieden

Het Microsoft.Agents.AI.Hosting pakket integreert agents en werkstromen met de .NET algemene host:

• AddAIAgent registreert een benoemde naam AIAgent met afhankelijkheidsinjectie.
• AddWorkflow registreert een benoemde werkstroom. Keten AddAsAIAgent om de werkstroom beschikbaar te maken voor protocolintegraties via de standaardagentinterface.
• IHostedAgentBuilder hiermee configureert u hostingservices die aan die agent zijn gekoppeld.
• AgentSessionStore laadt en slaat optioneel AgentSession instanties op met behulp van een continuation-ID die door een toepassing of protocol is opgegeven.

Het hostingpakket is geen HTTP-server of protocolregister. Uw toepassing selecteert de gehoste agents en werkstromen, configureert hun services en voegt de protocoleindpunten toe die nodig zijn.

Integreren met ASP.NET Core

Het gedeelde hostingpakket maakt gebruik van de .NET algemene host- en afhankelijkheidsinjectie. Voor een HTTP-server maakt u een ASP.NET Core toepassing en voegt u de protocolspecifieke pakketten toe voor de eindpunten die u beschikbaar wilt maken. Deze pakketten halen instanties met de naam AIAgent op uit dependency injection en voegen ASP.NET Core-routertoewijzingen toe.

Het OpenAI-hostingpakket kan bijvoorbeeld een geconfigureerde agent beschikbaar maken via een eindpunt voor antwoorden:

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

Zie OpenAI-compatibele eindpunten voor volledige configuratie.

Uw toepassing blijft verantwoordelijk voor de middleware-pijplijn, verificatie, autorisatie, aanvraagvalidatie, toegestane modelopties en duurzame opslag. Een niet-HTTP-host kan gebruikmaken van de gedeelde hostingservices zonder ASP.NET Core protocoleindpunten toe te voegen.

Protocollen toevoegen aan uw server

Kies de protocolintegraties die uw toepassing nodig heeft:

protocol	Integration
OpenAI-compatibele eindpunten	HTTP-eindpunten compatibel met Chat Completions en Responses
A2A	Agent-naar-agent-detectie, berichten en taakeindpunten
AG-UI	Gebeurtenisstreaming-eindpunten voor webagenttoepassingen

Gehoste sessies behouden

AgentSessionStore gegevenspersistentie moet expliciet worden ingeschakeld voor hostingintegraties die hiervan gebruikmaken. Zonder een geconfigureerd archief kunnen deze integraties een nieuwe sessie maken voor elke aanvraag, maar kunnen ze de sessiestatus van een eerdere aanvraag niet herstellen.

Belangrijk

MAF bevat geen duurzaam sessiearchief voor algemeen gebruik. Geef voor productie een AgentSessionStore implementatie op die wordt ondersteund door opslag die geschikt is voor uw toepassing.

Registreer uw duurzame implementatie met afhankelijkheidsinjectie en geef deze door aan de gehoste agent. U kunt het in-memory archief voorwaardelijk gebruiken tijdens de ontwikkeling:

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 dit voorbeeld is MyAgentSessionStore de duurzame implementatie die door uw toepassing wordt geleverd. De ontwikkeltak gaat uit van een lokale omgeving met één vertrouwde gebruiker en is de enige optie waarbij isolatie wordt uitgeschakeld. De productiebranch behoudt het standaardisolatiegedrag; configureert u een provider voor isolatiesleutels, zoals beschreven in de voortzetting van een beveiligde sessie.

InMemoryAgentSessionStore verliest alle sessies wanneer het proces wordt afgesloten en de status niet deelt tussen toepassingsexemplaren. Implementeer uw eigen AgentSessionStore met persistente opslag om sessies te behouden.

Een AgentSessionStore implementeert asynchrone bewerkingen voor opslaan, ophalen en verwijderen. Het ontvangt de bijbehorende AIAgent en een niet-transparante continuatie-id die is gekozen door een hostingintegratie of een route die eigendom is van de toepassing, en het moet bij elke get-bewerking een onafhankelijk AgentSession-exemplaar retourneren. Beschouw de continuation-ID als een niet-transparante sleutel in aangepaste opslaglocaties; hoe de ID wordt geïnterpreteerd, is afhankelijk van het protocol.

Een duurzame implementatie heeft de volgende structuur. Vervang elke stub door bewerkingen voor het gekozen opslagsysteem:

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

Sleutelrecords door zowel agent.Id als door de ondoorzichtige sessionStoreId. GetSessionAsync moet bij elke aanroep een onafhankelijk sessie-exemplaar retourneren; gebruik de sessieserialisatie-API's van de bijbehorende agent bij het opslaan van de geserialiseerde toestand. Persistente sessies kunnen gevoelige gegevens bevatten, dus beveilig ze met de juiste toegangscontroles en versleuteling.

AgentSessionStore slaat de volledige AgentSession op die via een gehost verzoek is geselecteerd, niet alleen conversatieberichten. Afhankelijk van de stack van de agent kan een sessie een door de service beheerde gespreks-ID, door het framework beheerde chatgeschiedenis, geheugen- of contextproviderstatus, berichten in de wachtrij, goedkeuringen in afwachting en andere statusinformatie bevatten die tussen uitvoeringen behouden moet blijven.

Geschiedenisproviders bepalen waar gespreksberichten worden opgeslagen. Wanneer de geschiedenis in de sessiestatus wordt bewaard, blijft de sessie ook die geschiedenis behouden. Een externe geschiedenisprovider slaat berichten afzonderlijk op; de sessie kan een verwijzings- of gerelateerde providerstatus behouden.

Vervolg van beveiligde sessie

Een vervolg-id identificeert een sessie die moet worden hervat; het bewijst niet dat de beller eigenaar is van die sessie. Beperk opgeslagen sessies tot een geverifieerde gebruiker, tenant of andere autorisatiegrens voordat door de client aangeleverde ID's worden geaccepteerd. De IsolationKeyScopedAgentSessionStore krijgt een isolatiesleutel van AgentIsolationKeyProvider, combineert deze met de protocolcontinuatie-ID en geeft de resulterende ID met bereik door aan de onderliggende opslag. Als gevolg hiervan wordt dezelfde vervolg-id onder twee verschillende isolatiesleutels omgezet in twee verschillende opgeslagen sessies en kan een beller alleen sessies ophalen die zijn opgeslagen met de isolatiesleutel van die beller.

Voor ASP.NET Core toepassingen die gebruikmaken van verificatie op basis van claims, installeert u het prereleasepakketMicrosoft.Agents.AI.Hosting.AspNetCore, registreert u de isolatieprovider op basis van claims en houdt u isolatie ingeschakeld in het sessiearchief:

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

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

UseClaimsBasedAgentIsolation Standaard wordt de ClaimTypes.NameIdentifier claim gebruikt. Configureer alleen een andere claim wanneer deze stabiel en uniek is voor elke aanroeper die door de store wordt bediend. De isolatieprovider verifieert geen aanvragen; configureer ASP.NET Core verificatie en autorisatie afzonderlijk. Met het standaard strikte isolatiegedrag mislukt sessietoegang wanneer de huidige principal de geconfigureerde claim niet biedt.

Registreer een aangepaste AgentIsolationKeyProvider voor een niet-HTTP-host of een ander tenancymodel. De standaard-WithInMemorySessionStore() en WithSessionStore(...)-overloads wikkelen de geconfigureerde opslag in IsolationKeyScopedAgentSessionStore.

Volgende stappen 

Een openAI-compatibel eindpunt toevoegen

Ga dieper in:

• Hostagents met A2A
• Webagenttoepassingen bouwen met AG-UI
• Foundry-gehoste agents

Opmerking

Protocolhelpers voor self-hosting zijn momenteel niet beschikbaar voor Go.

Met selfhosting kunt u een Agent Framework-agent of -werkstroom uitvoeren in uw eigen webtoepassing, container, service of runtime. Uw toepassing bepaalt routering, identiteit, autorisatie, aanvraagbeleid, opslag, implementatie en schalen. Voeg een of meer protocolintegraties toe aan die server op basis van de clients die u moet ondersteunen.

Gebruik deze optie wanneer u een agenteindpunt moet integreren met uw bestaande toepassingsinfrastructuur. Als u wilt dat Microsoft Foundry de agent voor u uitvoert, raadpleegt u Foundry Hosted Agents. Als u triggers voor Azure Functions of duurzame uitvoeringen nodig hebt, raadpleegt u Durable Extension.

Het ontwerp van deze pakketten is zodanig dat de ontwikkelaar maximale flexibiliteit biedt. Dit betekent dat als u een host wilt bouwen die een agent beschikbaar stelt met de Responses API, en de parameters voor andere doeleinden wilt misbruiken (d.w.z. temperature toewijzen aan top_p), u dat kunt doen. Als u geen sessies wilt opslaan, kunt u dat doen als u wilt toestaan dat de beller de volledige uitvoering van de agent beheert, kunt u dat ook doen. We komen niet in de weg, we bieden helpers voor de veelvoorkomende gevallen en maken u verantwoordelijk voor de rest, zodat u de exacte host kunt bouwen die u nodig hebt.

Belangrijk

agent-framework-hosting, , agent-framework-hosting-responsesagent-framework-hosting-telegram, , agent-framework-a2a, en agent-framework-hosting-a2azijn agent-framework-hosting-mcp voorlopige Python pakketten. Installeer voorlopige versies expliciet en bekijk releaseopmerkingen voordat u een productie-implementatie bijwerkt.

pip install --pre agent-framework-hosting

Wat de hosting-helpers bieden

Het algemene hostingpakket biedt een gedeelde uitvoeringsstatus voor een server die eigendom is van een toepassing:

• AgentState koppelt een agentdoel aan een SessionStore en maakt sessies wanneer de toepassing een nieuwe sleutel selecteert.
• SessionStore slaat sessies op, haalt en verwijdert deze op basis van een door de toepassing geselecteerde id. Het standaardarchief is proces-lokaal en heeft geen verwijderingsbeleid.
• WorkflowState lost een werkstroomdoel op. Uw toepassing beheert de checkpointopslag en eventuele toewijzingen van een client-continuation-ID aan een checkpoint.

AgentState is geen server- of protocolregister. Uw toepassing selecteert een geautoriseerde sessiesleutel, lost het doel op en slaat de status na uitvoering op. Het kan dezelfde doel- en gedeelde toepassingsinfrastructuur gebruiken voor een of meer protocoleindpunten.

Sessieopslag aanpassen

SessionStore is een kleine asynchrone opslagklasse met get, seten delete methoden. De standaard implementatie houdt sessies in procesgeheugen. Leid hiervan een subklasse af en overschrijf die methoden om AgentSession-objecten op te slaan in Redis, een database, blobopslag of een andere opslag die eigendom is van de toepassing, en geef die instantie vervolgens door aan AgentState(session_store=...).

SessionStore en providers voor de gespreksgeschiedenis slaan afzonderlijke delen van een gesprek van een agent op. In een sessiearchief wordt één sessieobject per sessie-id opgeslagen, inclusief sessiemetagegevens en providerstatus. Een speciale HistoryProvider opslag slaat het gesprek afzonderlijk op, meestal als één record per bericht. Deze scheiding wordt aanbevolen voor duurzame hosts, omdat het toevoegen van afzonderlijke berichten over het algemeen efficiënter is dan het herschrijven van een groeiend sessieobject na elke beurt. Er wordt per agent een geschiedenisprovider gedefinieerd door de gewenste providerklasse voor geschiedenis door te geven aan de context_providers parameter.

Opmerking

De standaardgeschiedenisprovider: is de uitzondering: InMemoryHistoryProvider het volledige gesprek wordt opgeslagen in AgentSession.state. Wanneer deze provider wordt gebruikt, SessionStore blijft het gesprek in het sessieobject behouden. Gebruik voor langere gesprekken of productieopslag een toegewezen geschiedenisprovider, zodat het sessiearchief zich kan concentreren op de lichtgewicht sessiestatus.

Gebruik uw eigen framework of clientbibliotheek

De hostingpakketten zijn niet gekoppeld aan een webframework of clientbibliotheek. De voorbeelden gebruiken FastAPI en aiogram omdat ze beknopte runnable voorbeelden bieden, niet omdat de helpers ze nodig hebben.

• Gebruik voor HTTP-eindpunten de routerings- en aanvraag-/antwoord-API's van uw toepassingsframework, zoals FastAPI, Starlette, Django, Flask, Azure Functions of een ander framework.
• Gebruik voor protocolclients zoals Telegram elke clientbibliotheek die een protocolupdate kan leveren en de bewerkingen kan uitvoeren die door de helper worden geproduceerd.

De toepassing selecteert het framework en de clientbibliotheek; De Agent Framework-pakketten converteren alleen protocolgegevens en beheren optionele uitvoeringsstatus. Ze registreren geen routes, verifiëren bellers, autoriseren toegang tot status, kiezen toegestane modelopties of bieden duurzame opslag.

Protocollen toevoegen aan uw server

Kies een of meer protocolintegraties:

protocol	Pakket en integratie
OpenAI-antwoorden	agent-framework-hosting-responses
Telegram	agent-framework-hosting-telegram
A2A	agent-framework-a2a of agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

Op elke protocolpagina wordt de installatie beschreven. Ze zijn echter zodanig ontworpen dat u één host kunt bouwen met een of meer protocollen ingeschakeld en een aanroepbaar doel; een agent of een werkstroom. Omdat we u niet beperken tot één webframework, kunt u het gewenste framework kiezen en de host eenvoudig instellen met deze protocollen.

Vervolg van beveiligde sessie

Behandel elke door het protocol geleverde id als niet-vertrouwde invoer. Voordat u een id gebruikt om een sessie, controlepunt, taak of andere status te laden:

1. Verifieer de identiteit van de beller.
2. Autoriseren van de beller om toegang te krijgen tot de status waarnaar wordt verwezen.
3. Partitioneer de persistente status op basis van de geauthenticeerde tenant, gebruiker of werkruimte.
4. Sessie- en controlepuntstatus behouden pas nadat de uitvoering of stream is voltooid.

Met dit zelfhostingpatroon kan uw toepassing alleen de protocoleindpunten en -beleidsregels implementeren die nodig zijn; Er wordt niet geprobeerd het volledige API-oppervlak van elk ondersteund protocol te implementeren.

Volgende stappen 

Het OpenAI-antwoordprotocol toevoegen

Ga dieper in:

• Telegram
• A2A
• MCP
• Foundry-gehoste agents