AG-UI Integráció az Ügynök-keretrendszerrel

Az AG-UI egy protokoll, amellyel webes AI-ügynökalkalmazásokat hozhat létre olyan speciális funkciókkal, mint a valós idejű streamelés, az állapotkezelés és az interaktív felhasználói felületi összetevők. Az Ügynök-keretrendszer AG-UI integrációja zökkenőmentes kapcsolatot biztosít az ügynökök és a webügyfelek között.

Mi az AG-UI?

AG-UI egy szabványosított protokoll az AI-ügynökök interfészeinek létrehozásához, amelyek a következőt biztosítják:

• Távoli ügynök üzemeltetése: AI-ügynökök üzembe helyezése több ügyfél által elérhető webszolgáltatásként
• Valós idejű streamelés: Ügynökválaszok streamelése Server-Sent események (SSE) használatával azonnali visszajelzés céljából
• Szabványos kommunikáció: Konzisztens üzenetformátum megbízható ügynök-interakciókhoz
• Munkamenet-kezelés: Több kérés beszélgetési környezetének karbantartása
• Speciális funkciók: Emberi közreműködéssel történő jóváhagyások, állapotszinkronizálás és egyedi felhasználói felület megjelenítése

Mikor érdemes használni a AG-UI

A következő esetekben érdemes AG-UI használnia:

• Az AI-ügynökökkel kommunikáló webes vagy mobilalkalmazások létrehozása
• Ügynökök üzembe helyezése több egyidejű felhasználó által elérhető szolgáltatásként
• Az ügynök válaszainak valós idejű streamelése azonnali felhasználói visszajelzések küldéséhez
• Jóváhagyási munkafolyamatok implementálása, amelyekben a felhasználók végrehajtás előtt megerősítik a műveleteket
• Állapot szinkronizálása az ügyfél és a kiszolgáló között az interaktív élmény érdekében
• Egyéni felhasználói felületi összetevők renderelése ügynökeszköz-hívások alapján

AG-UI forgatókönyvek

AG-UI hét bemutatóforgatókönyvet határoz meg. A MAF támogatása az SDK-tól függően változik; az aktuális támogatási szinthez és megvalósítási útmutatóhoz használja az oldal nyelvspecifikus szakaszát.

1. Ügynöki csevegés: Egyszerű streamelési csevegés automatikus eszközhívással
2. Háttéreszköz renderelése: A háttérrendszeren végrehajtott eszközök az ügyfélnek streamelt eredményekkel
3. Human in the Loop: Függvény-jóváhagyási kérések a felhasználó megerősítéséhez
4. Agentic Generative UI: Aszinkron eszközök hosszú ideig tartó műveletekhez előrehaladási frissítésekkel
5. Eszközalapú Generatív felhasználói felület: Eszközhívások alapján renderelt egyéni felhasználói felületi összetevők
6. Megosztott állapot: Kétirányú állapot szinkronizálása az ügyfél és a kiszolgáló között
7. Prediktív állapotfrissítések: Az eszköz argumentumainak streamelése optimista állapotfrissítésként

Ügynök felhasználói felületének létrehozása a CopilotKittel

A CopilotKit gazdag felhasználói felületi összetevőket biztosít az ügynök felhasználói felületeinek létrehozásához a standard AG-UI protokoll alapján. A CopilotKit támogatja a streamelt csevegőfelületeket, a frontend & háttéreszköz-hívásokat, az emberi beavatkozásokat, a generatív felhasználói felületet, a megosztott állapotot és még sok mást. Példákat láthat a CopilotKit által a AG-UI Dojo mintaalkalmazásban támogatott különböző ügynök felhasználói felületi forgatókönyvekre.

Ha egy CopilotKit React előtérrendszert szeretne csatlakoztatni egy Agent Framework AG-UI háttérrendszerhez, regisztrálja a végpontot HttpAgent a CopilotKit-futtatókörnyezetben. Ez lehetővé teszi, hogy a CopilotKit előtérbeli eszközei AG-UI ügyféleszközökként haladjanak át, és minden AG-UI funkció (streamelés, jóváhagyások, állapotszinkronizálás) automatikusan működjön.

A CopilotKit segítségével az ügynök képességeire összpontosíthat, miközben csiszolt felhasználói élményt nyújt anélkül, hogy újra feltalálja a kereket. Az Microsoft Agent Framework és a CopilotKit használatának első lépéseiről a CopilotKit Microsoft Agent Framework-integrációja dokumentációjában olvashat.

.NET-integráció

A .NET integráció egy MAF-et AIAgent tesz elérhetővé AG-UI HTTP-végpontként. Az üzemeltetési adapter átalakítja az ügynök válaszfolyamát AG-UI eseményekké; az ügynök alapvető viselkedése, például az eszközök végrehajtása és jóváhagyása továbbra is a MAF része marad.

A .NET integrációval:

• Az ügynök szövegének továbbítása Server-Sent Events (SSE) használatával.
• Jelenítse meg a backend- és frontend eszközhívásokat AG-UI-eseményekként.
• Küldjön MAF-eszköz-jóváhagyási kéréseket az ügyfélnek, és küldje vissza a döntést.
• Adatcsere kliensállapot, állapotképek és delták, valamint továbbított tulajdonságok.
• A tárolt munkamenetek folytatása a AG-UI threadIdhasználatával.
• Azonos végponton keresztül ügynökökké konvertált munkafolyamatokat tehet közzé.

AG-UI ügyfelek döntik el, hogyan jelenítsék meg a szöveget, az eszközt, a jóváhagyást és az állapoteseményeket.

Architecture

A C# üzemeltetési csomag egy ASP.NET Core végpontot ad hozzá egy szokásos MAF-ügynök köré:

AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent

MapAGUIServer a AG-UI kérést a MAF-üzenetekhez és a futtatási beállításokhoz igazítja. Ezután átalakítja az ügynök streamelési válaszát AG-UI eseményekké a AG-UI .NET SDK használatával.

Telepítés

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

Következő lépések

Az AG-UI használatának első lépései

Kapcsolódó erőforrások

• Az Ügynök-keretrendszer áttekintése
• AG-UI protokoll dokumentációja
• Microsoft Agent Framework-adattár

AG-UI és közvetlen ügynökhasználat

Bár közvetlenül az alkalmazásban futtathat ügynököket az Agent Framework run és run(..., stream=True) a metódusok használatával, AG-UI további képességeket biztosít:

Funkció	Közvetlen ügynök használata	AG-UI integráció
Deployment	Beágyazás az alkalmazásba	Távoli szolgáltatás HTTP-en keresztül
Ügyfélhozzáférés	Egyetlen alkalmazás	Több ügyfél (web, mobil)
Streaming	Folyamatban lévő aszinkron iteráció	Server-Sent események (SSE)
Állapotkezelés	Alkalmazás által felügyelt	Kétirányú protokollszintű szinkronizálás
Szálkörnyezet	Alkalmazás által felügyelt	Protokoll által felügyelt szálazonosítók
Jóváhagyási munkafolyamatok	Egyéni megvalósítás	Beépített protokolltámogatás

Architektúra áttekintése

A AG-UI integráció tiszta, moduláris architektúrát használ:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Kulcsösszetevők

• FastAPI-végpont: olyan HTTP-végpont, amely kezeli az SSE-adatfolyamot, a konfigurálható életben tartó megjegyzéseket és a kérések útválasztását
• AgentFrameworkAgent: Egyszerűsített burkoló, amely az Agent Framework-ügynököket AG-UI protokollhoz igazítja
• Vezénylők: Különböző végrehajtási folyamatok kezelése (alapértelmezett, human-in-the-loop, állapotkezelés)
• Event Bridge: Átalakítja az Ügynök-keretrendszer eseményeit AG-UI protokolleseményekké
• Üzenetadapterek: Kétirányú átalakítás a AG-UI és az Agent Framework üzenetformátumai között
• Megerősítő stratégiák: Bővíthető stratégiák tartományspecifikus megerősítési üzenetekhez

Hogyan valósul meg az Agent Framework az AG-UI-ban

Agent Framework fogalmainak AG-UI-ra való leképezése segít a hatékony integrációk megvalósításában.

Ügynök-keretrendszer fogalma	AG-UI egyenértékű	Description
Agent	Ügynöki végpont	Minden ügynök HTTP-végponttá válik
agent.run()	HTTP POST-kérelem	Az ügyfél HTTP-en keresztül küld üzeneteket
agent.run(..., stream=True)	Kiszolgáló által küldött események	Válaszok streamelése SSE-en keresztül
Ügynök válaszfrissítései	AG-UI események	TEXT_MESSAGE_CONTENT, stb TOOL_CALL_START.
Függvényeszközök (@tool)	Háttéreszközök	A kiszolgálón hajtják végre, az eredmények pedig az ügyfélhez streamelődnek
Eszközjóváhagyási mód	Ember a folyamatban	Jóváhagyási kérelmek/válaszok protokollon keresztül
Beszélgetési előzmények	Szálkezelés	threadId fenntartja a környezetet a kérések között

Telepítés

Telepítse a AG-UI integrációs csomagot:

pip install agent-framework-ag-ui --pre

Ez az alapvető ügynök-keretrendszert és AG-UI integrációs összetevőket is telepíti.

Következő lépések

AG-UI integráció első lépései:

1. Első lépések: Az első AG-UI kiszolgáló és ügyfél létrehozása
2. Háttéreszköz renderelése: Függvényeszközök hozzáadása az ügynökökhöz
3. Munkafolyamatok: Többügynöki munkafolyamatok AG-UI-n keresztül láthatóvá tétele
4. Human-in-the-Loop: Jóváhagyási munkafolyamatok implementálása
5. MCP-alkalmazások kompatibilitása: AZ MCP-alkalmazások használata a AG-UI végponttal
6. Állapotkezelés: Az állapot szinkronizálása az ügyfél és a kiszolgáló között

További források

• Az Ügynök-keretrendszer dokumentációja
• AG-UI protokoll dokumentációja
• AG-UI Dojo-alkalmazás – Példaalkalmazás az Agent Framework integrációját szemléltetve
• CopilotKit MAF-integráció – A CopilotKit React előtérrendszereinek csatlakoztatása AG-UI háttérrendszerekhez
• Agent Framework GitHub-adattár

A Go támogatja az AG-UI-t a provider/aguiprovider révén, szerverek és kliensek esetében is.

import "github.com/microsoft/agent-framework-go/provider/aguiprovider"

mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))

if err := http.ListenAndServe(":8888", mux); err != nil {
    log.Fatal(err)
}

Tip

Tekintse meg a AG-UI Go-példákat a teljes kiszolgáló- és ügyfélmintákhoz.