Önkiszolgáló Agent Framework-alkalmazások

A saját üzemeltetés lehetővé teszi, hogy egy Agent Framework-ügynököt vagy -munkafolyamatot a saját ASP.NET Core-alkalmazásában, tárolójában, szolgáltatásában vagy futtatókörnyezetében futtasson. Az alkalmazás szabályozza az útválasztást, az identitást, az engedélyezést, a kérelemházirendet, a tárolást, az üzembe helyezést és a skálázást. Adja hozzá a protokollintegrációkat a kiszolgálóhoz azoknak a klienseknek megfelelően, amelyeket támogatnia kell.

Ezt a lehetőséget akkor használja, ha integrálnia kell egy ügynökvégpontot a meglévő alkalmazásinfrastruktúrával. Ha azt szeretné, hogy Microsoft Foundry futtassa az ügynököt, olvassa el a Foundry által üzemeltetett ügynökök című témakört. Ha Azure Functions eseményindítókra vagy tartós végrehajtásra van szüksége, tekintse meg a Durable Extension című témakört.

Important

A .NET üzemeltetési csomagok előzetes kiadásúak. Az előzetes verziókat csak kifejezetten telepítse, és egy éles telepítés frissítése előtt tekintse át a kiadási megjegyzéseket.

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

Mit nyújtanak az üzemeltetési segítők?

A Microsoft.Agents.AI.Hosting csomag integrálja az ügynököket és a munkafolyamatokat a .NET általános gazdagépkörnyezetébe:

• AddAIAgent egy függőséginjektálással elnevezett AIAgent nevet regisztrál.
• AddWorkflow nevű munkafolyamatot regisztrál. Lánccal AddAsAIAgent elérhetővé teheti a munkafolyamatot a protokollintegrációk számára a standard ügynökfelületen keresztül.
• IHostedAgentBuilder konfigurálja az adott ügynökhöz társított üzemeltetési szolgáltatásokat.
• AgentSessionStore opcionálisan betölti és menti a AgentSession példányokat egy alkalmazás vagy protokoll által megadott folytatási azonosító használatával.

Az üzemeltetési csomag nem HTTP-kiszolgáló vagy protokollregisztrációs adatbázis. Az alkalmazás kiválasztja az üzemeltetett ügynököket és munkafolyamatokat, konfigurálja a szolgáltatásaikat, és hozzáadja a szükséges protokollvégpontokat.

Integráció az ASP.NET Core-ral

A megosztott tárhelycsomag a .NET Generic Hostot és függőséginjektálást használja. HTTP-kiszolgáló esetén hozzon létre egy ASP.NET Core alkalmazást, és adja hozzá a protokollspecifikus csomagokat a közzéteendő végpontokhoz. Ezek a csomagok feloldják az elnevezett AIAgent példányokat a függőséginjektálásból, és ASP.NET Core útvonalleképezéseket adnak hozzá.

Az OpenAI-üzemeltetési csomag például egy konfigurált ügynököt egy Válaszvégponton keresztül tehet közzé:

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

A teljes konfigurációért tekintse meg az OpenAI-kompatibilis végpontokat .

Az alkalmazás továbbra is felelős a köztes szoftveres folyamatért, a hitelesítésért, az engedélyezésért, a kérelemérvényesítésért, az engedélyezett modellbeállításokért és a tartós tárolásért. A nem HTTP-gazdagépek ASP.NET Core protokollvégpontok hozzáadása nélkül használhatják a megosztott üzemeltetési szolgáltatásokat.

Protokollok hozzáadása a kiszolgálóhoz

Válassza ki az alkalmazás által igényelt protokollintegrációkat:

Protocol	Integration
OpenAI-kompatibilis végpontok	Csevegés befejezései és válaszokkal kompatibilis HTTP-végpontok
A2A	Ügynökről ügynökre felderítés, üzenetkezelés és feladatvégpontok
AG-UI	Eseménystreamelési végpontok webügynök-alkalmazásokhoz

Hosztolt munkamenetek megőrzése

AgentSessionStore A perzisztencia külön engedélyezhető az azt használó üzemeltetési integrációk esetén. Konfigurált tároló nélkül ezek az integrációk minden kéréshez létrehozhatnak egy új munkamenetet, de nem tudják helyreállítani a kiszolgáló által birtokolt munkamenet állapotát egy korábbi kérésből.

Important

A MAF nem tartalmaz általános célú tartós munkamenet-tárolót. Éles használathoz adjon meg egy, az alkalmazásához megfelelő tárolóra épülő AgentSessionStore implementációt.

Regisztrálja a tartós megvalósítást függőséginjektálással, és adja át a üzemeltetett ügynöknek. A memóriabeli tárolót feltételesen használhatja a fejlesztés sorá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>());
}

Ebben a példában MyAgentSessionStore az alkalmazás által biztosított tartós implementáció. A fejlesztési ág egy megbízható felhasználóval rendelkező helyi környezetet feltételez, és ez az egyetlen elérési út, amely letiltja az elkülönítést. Az éles ág megtartja az alapértelmezett izolációs viselkedést; konfiguráljon egy izolációskulcs-szolgáltatót a Biztonságos munkamenet-folytatás című részben leírtak szerint.

InMemoryAgentSessionStore Elveszíti az összes munkamenetet, amikor a folyamat kilép, és nem osztja meg az állapotot az alkalmazáspéldányok között. A munkamenetek megőrzéséhez saját, perzisztens tárolással rendelkező AgentSessionStore-t valósíthat meg.

Az AgentSessionStore aszinkron mentési, beolvasási és törlési műveleteket implementálja. Megkapja a tulajdonosi AIAgent és egy átlátszatlan folytatási azonosítót, amelyet egy üzemeltetési integráció vagy egy alkalmazás által birtokolt útvonal választ ki, és minden egyes lekérési műveletből egy független AgentSession példányt kell visszaadnia. Kezelje a folytatási azonosítót átlátszatlan kulcsként az egyéni tárolókban; az azonosító értelmezése protokollspecifikus.

A tartós megvalósítás a következő struktúrával rendelkezik. Cserélje le az egyes csonkokat a választott tárolórendszer műveleteire:

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

Kulcsrekordok mind a agent.Id, mind a nem átlátszó sessionStoreId szerint. GetSessionAsync minden híváshoz egy független munkamenet-példányt kell visszaadnia; szerializált állapot tárolásakor használja a tulajdonosügynök munkamenet-szerializálási API-jait. A megőrzött munkamenetek bizalmas adatokat tartalmazhatnak, ezért megfelelő hozzáférés-vezérléssel és titkosítással védhetik őket.

AgentSessionStore megőrzi a hosztolt kérés által kiválasztott teljes AgentSession állapotot, nem csak a beszélgetési üzeneteket. Az alkalmazott ügynökveremtől függően egy munkamenet tartalmazhat egy szolgáltatás által felügyelt beszélgetésazonosítót, a keretrendszer által felügyelt csevegési előzményeket, memóriát vagy a kontextusszolgáltató állapotát, sorba állított üzeneteket, jóváhagyásra váró elemeket és egyéb állapotot, amelynek több futás között is fenn kell maradnia.

Az előzményszolgáltatók szabályozzák a beszélgetési üzenetek tárolásának helyét. Ha az előzmények munkamenet-állapotban lesznek tárolva, a munkamenet megőrzése is megőrzi ezt az előzményt. Egy külső előzményszolgáltató külön tárolja az üzeneteket; a munkamenet megőrizhet egy hivatkozási vagy kapcsolódó szolgáltatói állapotot.

Biztonságos munkamenet-folytatás

A folytatási azonosító azonosítja a folytatandó munkamenetet; ez nem bizonyítja, hogy a hívóé a munkamenet. Az ügyfél által megadott azonosítók elfogadása előtt a tárolt munkameneteket korlátozza hitelesített felhasználóra, bérlőre vagy más jogosultsági határra. A IsolationKeyScopedAgentSessionStore lekéri a(z) AgentIsolationKeyProvider elkülönítési kulcsát, egyesíti azt a protokoll-folytatási azonosítóval, és átadja az eredményül kapott hatókör-azonosítót az alapul szolgáló tárolónak. Ennek eredményeképpen ugyanaz a folytatási azonosító két különböző elkülönítési kulcs alatt két különböző tárolt munkamenetre oldódik fel, és egy hívó csak a saját elkülönítési kulcsával mentett munkameneteket kérheti le.

Az igényalapú hitelesítést használó ASP.NET Core alkalmazásokhoz telepítse a kiadás előtti Microsoft.Agents.AI.Hosting.AspNetCore csomagot, regisztrálja az igényalapú elkülönítési szolgáltatót, és tartsa engedélyezve az elkülönítést a munkamenettárolóban:

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

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

Alapértelmezés szerint a UseClaimsBasedAgentIsolation a ClaimTypes.NameIdentifier jogcímet használja. Konfiguráljon egy másik jogcímet csak akkor, ha az stabil és egyedi az áruház által kiszolgált összes hívónál. Az elkülönítési szolgáltató nem hitelesíti a kéréseket; ASP.NET Core hitelesítést és engedélyezést külön konfigurálhatja. Az alapértelmezett szigorú elkülönítési viselkedés esetén a munkamenet-hozzáférés meghiúsul, ha az aktuális tag nem adja meg a konfigurált jogcímet.

Nem HTTP-alapú gazdagép vagy más bérlőségi modell esetén regisztráljon egyéni AgentIsolationKeyProvider-t. A(z) WithInMemorySessionStore() és WithSessionStore(...) alapértelmezett túlterhelt változatai a konfigurált tárolót a(z) IsolationKeyScopedAgentSessionStore elembe csomagolják.

Következő lépések

OpenAI-kompatibilis végpont hozzáadása

Mélyedjen el:

• Hosztügynökök A2A-val
• Webügynök-alkalmazások létrehozása AG-UI használatával
• Foundry által üzemeltetett ügynökök

Note

A saját üzemeltetésű protokollsegédek jelenleg nem érhetők el a Go nyelvhez.

A saját üzemeltetés lehetővé teszi, hogy Agent Framework-ügynököt vagy munkafolyamatot futtasson saját webalkalmazásában, tárolójában, szolgáltatásában vagy futtatókörnyezetében. Az alkalmazás szabályozza az útválasztást, az identitást, az engedélyezést, a kérelemházirendet, a tárolást, az üzembe helyezést és a skálázást. Adjon hozzá egy vagy több protokollintegrációt a kiszolgálóhoz a támogatni kívánt ügyfelek alapján.

Ezt a lehetőséget akkor használja, ha integrálnia kell egy ügynökvégpontot a meglévő alkalmazásinfrastruktúrával. Ha azt szeretné, hogy Microsoft Foundry futtassa az ügynököt, olvassa el a Foundry által üzemeltetett ügynökök című témakört. Ha Azure Functions eseményindítókra vagy tartós végrehajtásra van szüksége, tekintse meg a Durable Extension című témakört.

Ezeknek a csomagoknak a kialakítása olyan, amely maximális rugalmasságot biztosít a fejlesztő számára. Ez azt jelenti, hogy ha olyan hosztot szeretne létrehozni, amely a Responses API-n keresztül elérhetővé tesz egy ágenst, és a paramétereket más célokra használja (azaz a temperature elemet a top_p elemhez rendeli), ezt megteheti. Ha nem szeretné tárolni a munkameneteket, ezt is megteheti; ha pedig engedélyezni szeretné, hogy a hívó fél vezérelje a teljes ügynökfutást, azt is megteheti. Nem akadályozunk, segédeszközöket biztosítunk a gyakori esetekhez, a többi pedig rád hárul, hogy pontosan olyan gazdagépet építhess, amilyenre szükséged van.

Important

agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2a és agent-framework-hosting-mcp előzetes kiadású Python-csomagok. Az előzetes verziókat csak kifejezetten telepítse, és egy éles telepítés frissítése előtt tekintse át a kiadási megjegyzéseket.

pip install --pre agent-framework-hosting

Mit nyújtanak az üzemeltetési segítők?

Az általános üzemeltetési csomag megosztott végrehajtási állapotot biztosít egy alkalmazás tulajdonában lévő kiszolgálóhoz:

• AgentState egy SessionStore-gyel párosít össze egy ügynök célpontot, és munkameneteket hoz létre, amikor az alkalmazás új kulcsot választ ki.
• SessionStore egy alkalmazás által kiválasztott azonosító tárolja, lekéri és törli a munkameneteket. Az alapértelmezett tároló folyamatalapú, és nincs kiürítési szabályzata.
• WorkflowState felold egy munkafolyamat-célt. Az alkalmazás kezeli az ellenőrzőpontok tárolását, valamint az ügyfél-folytatási azonosító és az ellenőrzőpont közötti leképezést.

AgentState nem kiszolgáló- vagy protokollregisztrációs adatbázis. Az alkalmazás kiválaszt egy engedélyezett munkamenetkulcsot, feloldja a célpontot, és elmenti a futás utáni állapotot. Ugyanazt a cél- és megosztott alkalmazásinfrastruktúrát használhatja egy vagy több protokollvégponthoz.

Munkamenet-tároló testreszabása

SessionStoreegy kis méretű aszinkron tárolóosztály get, set és delete metódusokkal. Az alapértelmezett implementáció megőrzi a munkameneteket a folyamat memóriájában. Származtassa belőle, és írja felül ezeket a metódusokat, hogy a(z) AgentSession objektumokat Redisben, adatbázisban, blobtárolóban vagy egy másik, az alkalmazás tulajdonában lévő tárolóban tárolja, majd adja át a példányt a(z) AgentState(session_store=...) számára.

SessionStore és az előzményszolgáltatók az ügynökbeszélgetések különálló részeit is megőrzik. A munkamenet-tárolók munkamenet-azonosítónként egy munkamenet-objektumot mentenek, beleértve a munkamenet metaadatait és a szolgáltató állapotát. Egy dedikált HistoryProvider külön tárolja a beszélgetést, általában üzenetenként egy-egy rekordban. Ez az elkülönítés hosszan futó gazdagépeken ajánlott, mert az egyes üzenetek külön-külön történő hozzáfűzése általában hatékonyabb, mint egy növekvő munkamenet-objektum minden egyes váltás utáni újraírása. Az előzménykezelő szolgáltató ügynökönként adható meg a kívánt előzménykezelő szolgáltatóosztály context_providers paraméterben történő megadásával.

Note

Az alapértelmezett előzményszolgáltató: InMemoryHistoryProvider ez a kivétel: a teljes beszélgetést AgentSession.stateebben tárolja. A szolgáltató használata SessionStore esetén a beszélgetés megmarad a munkamenet-objektumon belül. Hosszabb beszélgetésekhez vagy éles környezetben való tároláshoz használjon dedikált előzménykezelőt, hogy a munkamenettár továbbra is a könnyű munkamenet-állapotra összpontosíthasson.

Saját keretrendszer vagy ügyfélkódtár használata

Az üzemeltetési csomagok nincsenek webes keretrendszerhez vagy ügyfélkódtárhoz kötve. A minták a FastAPI-t használják, és aiogram mivel tömör, futtatható példákat nyújtanak, nem azért, mert a segítők igénylik őket.

• HTTP-végpontok esetén használja az alkalmazás-keretrendszer útválasztási és kérés-/válasz API-jait, például FastAPI, Starlette, Django, Flask, Azure Functions vagy más keretrendszert.
• Protokollügyfelek, például a Telegram esetében használjon minden olyan ügyfélkódtárat, amely képes protokollfrissítést biztosítani és végrehajtani a segítő által létrehozott műveleteket.

Az alkalmazás kiválasztja a keretrendszerét és az ügyféloldali kódtárat; Az Agent Framework-csomagok csak a protokolladatokat konvertálják, és kezelik az opcionális végrehajtási állapotot. Nem regisztrálnak útvonalakat, nem hitelesítik a hívókat, engedélyezik az állapothoz való hozzáférést, nem választják ki az engedélyezett modellbeállításokat, és nem biztosítanak tartós tárterületet.

Protokollok hozzáadása a kiszolgálóhoz

Válasszon egy vagy több protokollintegrációt:

Protocol	Csomag és integráció
OpenAI-válaszok	agent-framework-hosting-responses
Telegram	agent-framework-hosting-telegram
A2A	agent-framework-a2a vagy agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

Minden protokolloldal leírja a beállítását. Ezeket azonban úgy tervezték, hogy lehetővé tegyék egyetlen gazdagép létrehozását egy vagy több protokoll engedélyezésével és egy meghívható célponttal, amely lehet akár ügynök, akár munkafolyamat. Mivel nem korlátozzuk Önt egyetlen webes keretrendszer használatára sem, kiválaszthatja azt, amelyiket szeretné, és könnyedén beállíthatja a gazdagépet ezekhez a protokollokhoz.

Biztonságos munkamenet-folytatás

Minden protokoll által megadott azonosítót ne megbízható bemenetként kezeljen. Mielőtt azonosítót használ egy munkamenet, ellenőrzőpont, feladat vagy egyéb állapot betöltéséhez:

1. Hitelesítse a hívót.
2. Engedélyezze a hívónak, hogy hozzáférjen a hivatkozott állapothoz.
3. Ossza fel a tartós állapotot a hitelesített bérlő, felhasználó vagy munkaterület szerint.
4. A munkamenet és az ellenőrzőpont állapotát csak a futtatás vagy a stream befejezése után mentse.

Ez az önkiszolgáló minta lehetővé teszi, hogy az alkalmazás csak azokat a protokollvégpontokat és szabályzatokat implementálja, amelyekre szüksége van; nem próbálja meg implementálni az összes támogatott protokoll teljes API-felületét.

Következő lépések

Az OpenAI-válaszok protokoll hozzáadása

Mélyedjen el:

• Telegram
• A2A
• MCP
• Foundry által üzemeltetett ügynökök