Aplikace Agent Framework s vlastním hostováním

Vlastní hostování umožňuje spouštět agenta nebo pracovní postup rozhraní Agent Framework ve vlastní aplikaci ASP.NET Core, kontejneru, službě nebo prostředí runtime. Vaše aplikace řídí směrování, identitu, autorizaci, zásady požadavků, úložiště, nasazení a škálování. Do hostitele přidejte integrace protokolů podle klientů, které potřebujete podporovat.

Tuto možnost použijte, pokud potřebujete integrovat koncový bod agenta se stávající infrastrukturou aplikace. Pokud chcete, aby Microsoft Foundry spouštěl agenta za vás, viz agenti hostovaní ve Foundry. Pokud potřebujete aktivační události Azure Functions nebo dlouhodobé spouštění, přečtěte si Durable Extension.

Důležité

.NET hosting balíčky jsou ve verzi před vydáním. Před aktualizací produkčního nasazení nainstalujte předběžné verze a před aktualizací produkčního nasazení si přečtěte poznámky k verzi.

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

Co poskytují pomocní správci hostingu

Balíček Microsoft.Agents.AI.Hosting integruje agenty a pracovní postupy s obecným hostitelem .NET:

• AddAIAgent zaregistruje pojmenovanou AIAgent pomocí vstřikování závislostí.
• AddWorkflow zaregistruje pojmenovaný pracovní postup. Propojte AddAsAIAgent, aby byl pracovní postup dostupný pro integrace s protokoly prostřednictvím standardního rozhraní agenta.
• IHostedAgentBuilder nakonfiguruje služby hostování spojené s tímto agentem.
• AgentSessionStore volitelně načte a uloží AgentSession instance podle ID pokračování zadaného aplikací nebo protokolu.

Hostitelský balíček není serverEM HTTP ani registrem protokolu. Vaše aplikace vybere hostované agenty a pracovní postupy, nakonfiguruje jejich služby a přidá koncové body protokolu, které potřebuje.

Integrujte se s ASP.NET Core

Sdílený hostitelský balíček používá .NET obecného hostitele a injektáž závislostí. Pro server HTTP vytvořte ASP.NET Core aplikaci a přidejte balíčky specifické pro protokol pro koncové body, které chcete zveřejnit. Tyto balíčky přeloží pojmenované AIAgent instance z injektáže závislostí a přidají mapování tras ASP.NET Core.

Například hostingový balíček OpenAI může zpřístupnit nakonfigurovaného agenta prostřednictvím koncového bodu Responses:

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

Kompletní konfiguraci najdete v tématu Koncové body kompatibilní s OpenAI .

Vaše aplikace zůstává zodpovědná za kanál middlewaru, ověřování, autorizaci, ověření požadavku, povolené možnosti modelu a trvalé úložiště. Hostitel, který není hostitelem HTTP, může používat sdílené hostitelské služby bez přidání koncových bodů protokolu ASP.NET Core.

Přidání protokolů na server

Zvolte integrace protokolů, které vaše aplikace potřebuje:

Protokol	Integration
Koncové body kompatibilní s OpenAI	HTTP endpointy kompatibilní s Chat Completions a Responses
A2A	Zjišťování agenta k agentům, zasílání zpráv a koncové body úloh
AG-UI	Endpointy pro streamování událostí pro aplikace webového agenta

Zachování hostovaných relací

AgentSessionStore Perzistence je volitelná pro hostingové integrace, které ji používají. Bez nakonfigurovaného úložiště můžou tyto integrace vytvořit novou relaci pro každou žádost, ale nemůžou obnovit stav relace vlastněné serverem z dřívějšího požadavku.

Důležité

MAF neobsahuje trvalé úložiště relací pro obecné účely. V produkčním prostředí zadejte implementaci podporovanou AgentSessionStore úložištěm, které je vhodné pro vaši aplikaci.

Zaregistrujte odolnou implementaci pomocí injektáže závislostí a předejte ji hostovaným agentům. Během vývoje můžete úložiště v paměti používat podmíněně:

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

V tomto příkladu MyAgentSessionStore je vaše trvalá implementace poskytovaná aplikací. Vývojová větev předpokládá místní prostředí s jedním důvěryhodným uživatelem a je jedinou cestou, která zakazuje izolaci. Produkční větev zachovává výchozí chování izolace; nakonfigurujte poskytovatele klíče izolace, jak je popsáno v Bezpečné pokračování relace.

InMemoryAgentSessionStore ztratí všechny relace, když se proces ukončí a nesdílí stav napříč instancemi aplikace. Implementujte vlastní AgentSessionStore s trvalým úložištěm, abyste si zachovali relace.

AgentSessionStore implementuje asynchronní operace pro ukládání, získávání a odstraňování. Přijímá vlastníka AIAgent a neprůhledné ID pokračování vybrané hostitelskou integrací nebo trasou spravovanou aplikací a při každé operaci get musí vrátit nezávislou instanci AgentSession. S ID pokračování zacházejte ve vlastních úložištích jako s neprůhledným klíčem; interpretace tohoto ID závisí na konkrétním protokolu.

Odolná implementace má následující strukturu. Nahraďte každý zástupný prvek operacemi pro zvolený úložný systém:

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

Záznamy klíčů pomocí obou agent.Id a neprůhledného sessionStoreId. GetSessionAsync musí při každém volání vrátit samostatnou instanci relace; při ukládání serializovaného stavu použijte rozhraní API vlastnícího agenta pro serializaci relace. Perzistentní relace mohou obsahovat citlivá data, proto by měly být chráněny odpovídajícím řízením přístupu a šifrováním.

AgentSessionStore ukládá celý AgentSession vybraný hostovaným požadavkem, nejen zprávy v konverzaci. V závislosti na stacku agenta může relace obsahovat ID konverzace spravované službou, historii konverzace spravovanou frameworkem, stav paměti nebo poskytovatele kontextu, zprávy zařazené do fronty, čekající schválení a další stav, který se musí zachovat mezi jednotlivými spuštěními.

Poskytovatelé historie určují, kde se ukládají zprávy konverzace. Pokud je historie uchovávána ve stavu relace, při perzistenci relace se zachová i tato historie. Externí poskytovatel historie ukládá zprávy samostatně; relace může uchovávat odkaz nebo související stav poskytovatele.

Zabezpečené pokračování relace

ID pokračování identifikuje relaci, která se má obnovit; neprokazuje, že volající danou relaci vlastní. Před přijetím ID poskytnutých klientem omezte perzistentní relace podle ověřeného uživatele, tenanta nebo jiné autorizační hranice. IsolationKeyScopedAgentSessionStore získá klíč izolace z AgentIsolationKeyProvider, zkombinuje jej s identifikátorem pokračování protokolu a výsledný identifikátor v daném oboru platnosti předá podkladovému úložišti. V důsledku toho stejné ID pokračování se dvěma různými klíči izolace odpovídá dvěma různým uloženým relacím a volající může načíst pouze relace uložené s klíčem izolace daného volajícího.

Pro aplikace ASP.NET Core, které používají ověřování založené na deklaracích identity, nainstalujte balíček předběžné verze Microsoft.Agents.AI.Hosting.AspNetCore, zaregistrujte poskytovatele izolace založeného na deklaracích identity a v úložišti relací ponechte izolaci povolenou:

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

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

Ve výchozím nastavení UseClaimsBasedAgentIsolation používá deklaraci ClaimTypes.NameIdentifier. Nakonfigurujte další deklaraci identity pouze v případech, kdy je stabilní a jedinečná pro všechny volající obsluhované úložištěm. Zprostředkovatel izolace neověřuje požadavky; nakonfigurujte ověřování a autorizaci ASP.NET Core samostatně. Při výchozím striktním režimu izolace přístup k relaci selže, pokud aktuální objekt zabezpečení neposkytuje nakonfigurovaný claim.

Pro hostitele, který nepoužívá protokol HTTP, nebo pro jiný model tenantů zaregistrujte vlastní AgentIsolationKeyProvider. Výchozí přetížení WithInMemorySessionStore() a WithSessionStore(...) zabalí nakonfigurované úložiště do IsolationKeyScopedAgentSessionStore.

Další kroky

Přidání koncového bodu kompatibilního s OpenAI

Jděte hlouběji:

• Hostování agentů pomocí A2A
• Vytvářejte aplikace webového agenta pomocí AG-UI
• Hostovaní agenti Foundry

Poznámka:

Pomocné nástroje pro protokol vlastního hostování nejsou v současnosti pro Go k dispozici.

Vlastní hostování vám umožňuje spustit agenta nebo pracovní postup v Agent Framework ve vaší vlastní webové aplikaci, kontejneru, službě nebo běhovém prostředí. Vaše aplikace řídí směrování, identitu, autorizaci, zásady požadavků, úložiště, nasazení a škálování. Přidejte na tento server jednu nebo více integrací protokolu na základě klientů, které potřebujete podporovat.

Tuto možnost použijte, pokud potřebujete integrovat koncový bod agenta se stávající infrastrukturou aplikace. Pokud chcete, aby Microsoft Foundry spouštěl agenta za vás, viz agenti hostovaní ve Foundry. Pokud potřebujete aktivační události Azure Functions nebo dlouhodobé spouštění, přečtěte si Durable Extension.

Návrh těchto balíčků je takový, že umožňuje maximální flexibilitu pro vývojáře. To znamená, že pokud chcete vytvořit host, který zpřístupňuje agenta pomocí rozhraní Responses API, a zneužijete parametry k jiným účelům (tj. namapujete temperature na top_p), můžete to udělat. Pokud nechcete ukládat relace, je to možné; a pokud chcete, aby volající řídil celý běh agenta, i to je možné. Nebudeme vám stát v cestě, nabízíme pomocné nástroje pro běžné případy a za zbytek ponecháváme odpovědnost na vás, abyste si mohli vytvořit přesně takový host, jaký potřebujete.

Důležité

agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2aa agent-framework-hosting-mcp jsou předběžné Python balíčky. Před aktualizací produkčního nasazení nainstalujte předběžné verze a před aktualizací produkčního nasazení si přečtěte poznámky k verzi.

pip install --pre agent-framework-hosting

Co poskytují pomocní správci hostingu

Obecný hostitelský balíček poskytuje sdílený stav spuštění pro server vlastněný aplikací:

• AgentState spáruje cíl agenta s SessionStore a vytvoří relace, když aplikace vybere nový klíč.
• SessionStore ukládá, načítá a odstraňuje relace podle ID vybrané aplikace. Jeho výchozí úložiště je lokální pro proces a nemá žádnou strategii vytěsňování.
• WorkflowState řeší cíl pracovního postupu. Vaše aplikace spravuje úložiště kontrolních bodů i veškeré mapování mezi identifikátorem pokračování klienta a kontrolním bodem.

AgentState není registr serveru nebo protokolu. Vaše aplikace vybere autorizovaný klíč relace, určí cíl a uloží stav po dokončení běhu. Může používat stejnou cílovou a sdílenou aplikační infrastrukturu pro jeden nebo několik koncových bodů protokolu.

Přizpůsobení úložiště relací

SessionStore je malá asynchronní třída úložiště s get, seta delete metody. Výchozí implementace uchovává relace v paměti procesu. Vytvořte z ní podtřídu a přepište tyto metody tak, aby ukládaly objekty AgentSession do Redis, databáze, úložiště objektů blob nebo jiného úložiště vlastněného aplikací, a potom předejte instanci do AgentState(session_store=...).

SessionStore a poskytovatelé historie uchovávají samostatné části konverzace agenta. Úložiště relací ukládá jeden objekt relace na ID relace, včetně metadat relace a stavu zprostředkovatele. Vyhrazené HistoryProvider ukládá konverzaci odděleně, obvykle jako jeden záznam na zprávu. Toto oddělení se doporučuje pro trvalé hostitele, protože připojování jednotlivých zpráv je obecně efektivnější než přepsání rostoucího objektu relace po každém turnu. Poskytovatel historie je definován pro každého agenta předáním požadované třídy poskytovatele historie do parametru context_providers.

Poznámka:

Výchozí zprostředkovatel historie: InMemoryHistoryProvider je výjimkou: ukládá úplnou konverzaci do AgentSession.state. Při použití tohoto poskytovatele SessionStore uchovává konverzaci v objektu relace. U delších konverzací nebo produkčního úložiště použijte vyhrazeného poskytovatele historie, aby úložiště relací zůstalo zaměřené na jednoduchý stav relace.

Použijte vlastní framework nebo klientskou knihovnu

Hostitelské balíčky nejsou svázané s webovou architekturou ani klientskou knihovnou. Ukázky používají FastAPI a aiogram, protože poskytují stručné spustitelné příklady, nikoli proto, že je pomocné funkce vyžadují.

• V případě koncových bodů HTTP použijte rozhraní API směrování a požadavků a odpovědí vaší aplikační architektury, jako jsou FastAPI, Starlette, Django, Flask, Azure Functions nebo jiná architektura.
• U klientů protokolu, jako je například Telegram, použijte libovolnou klientskou knihovnu, která dokáže dodat aktualizaci protokolu a provést operace vytvořené pomocnou funkcí.

Aplikace vybere svou architekturu a klientskou knihovnu; Balíčky Agent Framework převádějí pouze data protokolu a spravují volitelný stav spuštění. Neregistrují trasy, neověřují identitu volajících, neautorizují přístup ke stavu, nevybírají povolené možnosti modelu ani neposkytují perzistentní úložiště.

Přidání protokolů na server

Zvolte jednu nebo více integrací protokolu:

Protokol	Balíček a integrace
Odpovědi OpenAI	agent-framework-hosting-responses
Telegram	agent-framework-hosting-telegram
A2A	agent-framework-a2a nebo agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

Každá stránka protokolu popisuje nastavení. Jsou však navrženy tak, aby vám umožnily vytvořit jednoho hostitele s jedním nebo více povolenými protokoly a volatelným cílem; buď agent, nebo pracovní postup. Vzhledem k tomu, že vás neomezujeme na jednu webovou architekturu, můžete si vybrat ten, který chcete, a nastavit hostitele s těmito protokoly snadno.

Zabezpečené pokračování relace

Zacházet s každým identifikátorem zadaným protokolem jako s nedůvěryhodným vstupem. Před použitím ID pro načtení relace, kontrolního bodu, úkolu nebo jiného stavu:

1. Ověřte volajícího.
2. Oprávněte volajícího k přístupu k odkazovanému stavu.
3. Rozdělte trvalý stav podle ověřeného tenanta, uživatele nebo pracovního prostoru.
4. Uložte stav relace a kontrolního bodu až po dokončení běhu nebo streamu.

Tento model samoobslužného hostování umožňuje vaší aplikaci implementovat pouze koncové body protokolu a zásady, které potřebuje. nepokouší se implementovat kompletní povrch rozhraní API všech podporovaných protokolů.

Další kroky

Přidání protokolu Odpovědí OpenAI

Jděte hlouběji:

• Telegram
• A2A
• MCP
• Hostovaní agenti Foundry