Agent Framework-program med egen värd

Med självvärdering kan du köra en Agent Framework-agent eller ett arbetsflöde i din egen ASP.NET Core program, container, tjänst eller körning. Ditt program styr routning, identitet, auktorisering, begärandeprincip, lagring, distribution och skalning. Lägg till protokollintegreringar till värden baserat på de klienter som du behöver stöd för.

Använd det här alternativet när du behöver integrera en agentslutpunkt med din befintliga programinfrastruktur. Om du vill att Microsoft Foundry ska köra agenten åt dig, se Foundry Hosted Agents. Om du behöver utlösare för Azure Functions eller beständig körning, se Durable Extension.

Important

De .NET värdpaketen är förhandsversioner. Installera förhandsversioner uttryckligen och granska versionsinformationen innan du uppdaterar en produktionsmiljö.

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

Vad värdhjälparna tillhandahåller

Paketet Microsoft.Agents.AI.Hosting integrerar agenter och arbetsflöden med den .NET allmänna värden:

• AddAIAgent registrerar en namngiven AIAgent med beroendeinmatning.
• AddWorkflow registrerar ett namngivet arbetsflöde. Kedja AddAsAIAgent för att göra arbetsflödet tillgängligt för protokollintegreringar via standardagentgränssnittet.
• IHostedAgentBuilder konfigurerar värdtjänster som är associerade med agenten.
• AgentSessionStore om du vill kan du läsa in och spara instanser med ett fortsättnings-ID AgentSession som tillhandahålls av program eller protokoll.

Värdpaketet är inte en HTTP-server eller ett protokollregister. Ditt program väljer värdbaserade agenter och arbetsflöden, konfigurerar deras tjänster och lägger till de protokollslutpunkter som behövs.

Spara värdbaserade sessioner

Sessionspersistence är opt-in. Utan en konfigurerad AgentSessionStorekan protokollintegreringar skapa en ny session för varje begäran, men kan inte återställa serverägda sessionstillstånd från en tidigare begäran.

För utveckling eller ett program med en enda process konfigurerar du det inbyggda minnesinterna arkivet:

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

Inställningen withIsolation är false endast lämplig när en betrodd användare eller process äger sessionsnamnområdet. InMemoryAgentSessionStore förlorar alla sessioner när processen avslutas och delar inte tillstånd mellan programinstanser.

För varaktig eller distribuerad värd implementerar AgentSessionStore och registrerar du den med WithSessionStore. Ett arkiv implementerar asynkrona åtgärder för att spara, hämta och ta bort. Den tar emot ägandet AIAgent och ett ogenomskinlig sessionslagrings-ID och måste returnera en oberoende AgentSession instans från varje get-åtgärd.

AgentSessionStore historikleverantörer har olika syften. Ett sessionsarkiv bevarar det AgentSession som valts av en värdbaserad begäran. En historikprovider styr var konversationsmeddelanden lagras. När historiken hålls i sessionstillstånd bevaras även den historiken om sessionen bevaras. en extern historikprovider lagrar meddelanden separat.

Integrera med ASP.NET Core

Det delade värdpaketet använder .NET generisk värd- och beroendeinmatning. För en HTTP-server skapar du ett ASP.NET Core-program och lägger till protokollspecifika paket för de slutpunkter som du vill exponera. Dessa paket löser namngivna AIAgent instanser från beroendeinmatning och lägger till ASP.NET Core routningsmappningar.

Ditt program ansvarar fortfarande för pipelinen för mellanprogram, autentisering, auktorisering, validering av begäranden, tillåtna modellalternativ och varaktig lagring. En icke-HTTP-värd kan använda delade värdtjänster utan att lägga till ASP.NET Core protokollslutpunkter.

Lägga till protokoll till servern

Välj de protokollintegreringar som programmet behöver:

Protokoll	Integration
OpenAI-kompatibla slutpunkter	Chattslutpunkter och svarskompatibla HTTP-slutpunkter
A2A	Agent-till-agent-identifiering, meddelanden och uppgiftsslutpunkter
AG-UI	Slutpunkter för händelseströmning för webbagentprogram

Varje protokoll definierar sin egen fortsättningsidentifierare och slutpunktsbeteende. Behåll autentisering, auktorisering, sessionsägarskap och varaktig lagring i infrastrukturen för delade program i stället för att omimplementera dem för varje slutpunkt.

Fortsättning av säker session

Ett fortsättnings-ID identifierar en session som ska återupptas. det bevisar inte att anroparen äger den sessionen. Omfånget bevarade sessioner av en autentiserad användare, klientorganisation eller annan auktoriseringsgräns innan klienthanterade ID:er accepteras.

För ASP.NET Core program som använder anspråksbaserad autentisering installerar du förhandsversionspaketetMicrosoft.Agents.AI.Hosting.AspNetCore, registrerar den anspråksbaserade isoleringsprovidern och håller isoleringen aktiverad i sessionsarkivet:

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

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

Som standard UseClaimsBasedAgentIsolation använder anspråket ClaimTypes.NameIdentifier . Konfigurera endast ett annat anspråk när det är stabilt och unikt för varje anropare som hanteras av butiken. Isoleringsprovidern autentiserar inte begäranden. konfigurera ASP.NET Core autentisering och auktorisering separat. Med standardbeteendet för strikt isolering misslyckas sessionsåtkomsten när det aktuella huvudkontot inte tillhandahåller det konfigurerade anspråket.

För en icke-HTTP-värd eller en annan innehavarmodell registrerar du en anpassad AgentIsolationKeyProvider. Standard- WithInMemorySessionStore() och WithSessionStore(...) överlagringarna omsluter det konfigurerade arkivet i IsolationKeyScopedAgentSessionStore.

Nästa steg

Lägga till en OpenAI-kompatibel slutpunkt

Gå djupare:

• Värdagenter med A2A
• Skapa webbagentprogram med AG-UI
• Foundry Hosted Agents

Note

Protokollhjälpare med självbetjäning är för närvarande inte tillgängliga för Go.

Självhostning låter dig köra en Agent Framework-agent eller ett arbetsflöde i din egen webbapplikation, container, tjänst eller körmiljö. Ditt program styr routning, identitet, auktorisering, begärandeprincip, lagring, distribution och skalning. Lägg till en eller flera protokollintegreringar till servern baserat på de klienter som du behöver stöd för.

Använd det här alternativet när du behöver integrera en agentslutpunkt med din befintliga programinfrastruktur. Om du vill att Microsoft Foundry ska köra agenten åt dig, se Foundry Hosted Agents. Om du behöver utlösare för Azure Functions eller beständig körning, se Durable Extension.

Utformningen av dessa paket är sådan att det ger maximal flexibilitet för utvecklaren. Det innebär att om du vill skapa en värd som exponerar en agent med svars-API:et och missbrukar parametrarna för andra ändamål (dvs. mappa temperature till top_p) kan du göra det. Om du inte vill lagra sessioner kan du göra det. Om du vill låta anroparen styra hela agentkörningen kan du också göra det. Vi kommer inte att stå i vägen, vi erbjuder hjälpmedel för de vanligaste fallen och låter dig ansvara för resten, så att du kan bygga den exakta värdmiljö du behöver.

Important

agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2aoch agent-framework-hosting-mcp är förhandsversioner Python paket. Installera förhandsversioner uttryckligen och granska versionsinformationen innan du uppdaterar en produktionsmiljö.

pip install --pre agent-framework-hosting

Vad värdhjälparna tillhandahåller

Det allmänna värdpaketet ger delat körningstillstånd för en programägd server:

• AgentState parkopplar ett agentmål med en SessionStore och skapar sessioner när programmet väljer en ny nyckel.
• SessionStore lagrar, hämtar och tar bort sessioner med ett programvalt ID. Dess standardlagring är lokal för processen och har ingen utrensningsprincip.
• WorkflowState löser ett arbetsflödesmål. Ditt program äger kontrollpunktslagring och eventuell mappning från ett klientfortsättnings-ID till en kontrollpunkt.

AgentState är inte ett server- eller protokollregister. Din applikation väljer en auktoriserad sessionsnyckel, fastställer målet och sparar sluttillståndet efter körning. Den kan använda samma mål- och delade programinfrastruktur för en eller flera protokollslutpunkter.

Anpassa sessionslagring

SessionStore är en liten asynkron lagringsklass med getmetoderna , setoch delete . Standardimplementeringen håller sessioner i processminnet. Underklassa den och åsidosätt dessa metoder för att lagra AgentSession objekt i Redis, en databas, bloblagring eller ett annat programägt arkiv och skicka sedan instansen till AgentState(session_store=...).

SessionStore och historikleverantörer lagrar separata delar av en agents konversation. Ett sessionsarkiv sparar ett sessionsobjekt per sessions-ID, inklusive sessionsmetadata och providertillstånd. En dedikerad HistoryProvider lagrar konversationen separat, vanligtvis som en post per meddelande. Den här separationen rekommenderas för varaktiga värdar eftersom det i allmänhet är effektivare att lägga till enskilda meddelanden än att skriva om ett växande sessionsobjekt efter varje tur. En historikprovider definieras per agent genom att den önskade historikproviderklassen skickas till parametern context_providers .

Note

Standardhistorikprovidern: InMemoryHistoryProvider är undantaget: den lagrar hela konversationen i AgentSession.state. När providern används SessionStore bevaras konversationen i sessionsobjektet. För längre konversationer eller produktionslagring använder du en dedikerad historikprovider så att sessionsarkivet kan fokusera på enkelt sessionstillstånd.

Ta med ditt eget ramverk eller klientbibliotek

Värdpaketen är inte kopplade till ett webbramverk eller klientbibliotek. Exemplen använder FastAPI och aiogram eftersom de ger kortfattade körbara exempel, inte för att hjälparna behöver dem.

• För HTTP-slutpunkter använder du routnings- och begärande-/svars-API:er för ditt programramverk, till exempel FastAPI, Starlette, Django, Flask, Azure Functions eller något annat ramverk.
• För protokollklienter som Telegram använder du alla klientbibliotek som kan tillhandahålla en protokolluppdatering och köra de åtgärder som skapas av hjälpen.

Programmet väljer sitt ramverk och klientbibliotek. Agent Framework-paketen konverterar endast protokolldata och hanterar valfritt körningstillstånd. De registrerar inte routter, autentiserar anropare, auktoriserar åtkomst till status, väljer tillåtna modellalternativ eller tillhandahåller beständig lagring.

Lägga till protokoll till servern

Välj en eller flera protokollintegreringar:

Protokoll	Paket och integrering
OpenAI-svar	agent-framework-hosting-responses
Telegram	agent-framework-hosting-telegram
A2A	agent-framework-a2a eller agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

Varje protokollsida beskriver dess konfiguration. De är dock utformade för att du ska kunna skapa en enda värd med ett eller flera protokoll aktiverade och ett anropsbart mål. antingen en agent eller ett arbetsflöde. Eftersom vi inte begränsar dig till ett enda webbramverk kan du välja det du vill använda och enkelt konfigurera värden för dessa protokoll.

Fortsättning av säker session

Behandla varje identifierare som tillhandahålls av protokollet som otillförlitliga indata. Innan du använder ett ID för att läsa in en session, kontrollpunkt, uppgift eller annat tillstånd:

1. Autentisera anroparen.
2. Ge anroparen behörighet att komma åt det refererade tillståndet.
3. Partitionera beständigt tillstånd efter den autentiserade tenanten, användaren eller arbetsytan.
4. Bevara sessions- och kontrollpunktstillståndet först när körningen eller strömmen har slutförts.

Det här självhanteringsmönstret gör att din applikation bara behöver implementera de protokollslutpunkter och principer den behöver; det försöker inte implementera hela API-ytan för varje protokoll som stöds.

Nästa steg

Lägg till openAI-svarsprotokollet

Gå djupare:

• Telegram
• A2A
• MCP
• Foundry Hosted Agents