Első lépések az AG-UI

Ez az oktatóanyag bemutatja, hogyan hozhat létre kiszolgáló- és ügyfélalkalmazásokat a AG-UI protokollal az Agent Framework használatával. Megtudhatja, hogyan üzemeltethet egy ügynököt egy AG-UI végpont mögött, és hogyan csatlakoztathat egy ügyfelet interaktív beszélgetésekhez.

Mit fog felépíteni?

Az oktatóanyag végére a következőkre lesz szüksége:

  • HTTP-en keresztül elérhető AI-ügynököt üzemeltető AG-UI-kiszolgáló
  • Egy ügyfélalkalmazás, amely a kiszolgálóhoz csatlakozik, és a válaszokat streameli
  • A AG-UI protokoll és az Agent Framework működésének ismertetése

Prerequisites

  • .NET 8 vagy újabb
  • Egy ASP.NET Core projekt
  • Konfigurált MAF AIAgent

A példa Azure OpenAI-t használ, de MapAGUIServer bármely MAF-ügynökkel működik.

AG-UI-kiszolgáló létrehozása

Telepítse az üzemeltetési csomagot:

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

Regisztrálja az AG-UI-tárhelyet, és rendelje hozzá az ügynökét:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUIServer();

AIAgent agent = CreateAgent();

WebApplication app = builder.Build();
app.MapAGUIServer("/", agent);
await app.RunAsync();

MapAGUIServer fogadja az AG-UI RunAgentInput kéréseket, és az ügynök válaszát AG-UI-eseményekként SSE-n (server-sent events) keresztül továbbítja.

Futtassa a kiszolgálót az ügyfél példája által használt URL-címen:

dotnet run --urls http://localhost:8888

Tip

Tekintse meg a .NET első lépéseket bemutató mintát, amely egy teljes kiszolgálót és konzolos ügyfelet mutat be.

Csatlakozás .NET ügyféllel

Az AG-UI .NET SDK biztosítja a AGUIChatClient elemet, amely megvalósítja a IChatClient elemet, és adaptálható egy MAF-ügynökhöz:

dotnet add package AGUI.Client --prerelease
dotnet add package Microsoft.Agents.AI --prerelease

using AGUI.Abstractions;
using AGUI.Client;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

using HttpClient httpClient = new() { BaseAddress = new Uri("http://localhost:8888") };
AGUIChatClient chatClient = new(new AGUIChatClientOptions(httpClient, "/"));
AIAgent remoteAgent = chatClient.AsAIAgent();
AgentSession session = await remoteAgent.CreateSessionAsync();

List<AgentResponseUpdate> firstTurnUpdates = [];
await foreach (AgentResponseUpdate update in
    remoteAgent.RunStreamingAsync("Hello", session))
{
    firstTurnUpdates.Add(update);

    foreach (TextContent text in update.Contents.OfType<TextContent>())
    {
        Console.Write(text.Text);
    }
}

Az AG-UI protokollt megvalósító ügyféllel is csatlakozhat.

Beszélgetés folytonossága

Az AG-UI a folytatási kérelmek azonosítására a threadId és parentRunId elemeket használja. Ezek az azonosítók protokolladatok, nem hitelesítési hitelesítő adatok.

AGUIChatClient állapot nélküli. A kiszolgáló által kezelt beszélgetés folytatásához szerezze be az azonosítókat az első forduló RunStartedEvent eleméből, majd a következő kérésben adja meg ugyanazt a(z) threadId elemet és az előző runId elemet parentRunId értékként:

RunStartedEvent started = firstTurnUpdates
    .Select(update => update.AsChatResponseUpdate().RawRepresentation)
    .OfType<RunStartedEvent>()
    .FirstOrDefault()
    ?? throw new InvalidOperationException("The server didn't return a run-started event.");

ChatMessage nextMessage = new(ChatRole.User, "What did I just say?");
ChatClientAgentRunOptions continuationOptions = new()
{
    ChatOptions = new ChatOptions
    {
        RawRepresentationFactory = _ => new RunAgentInput
        {
            ThreadId = started.ThreadId,
            ParentRunId = started.RunId,
            Messages = new[] { nextMessage }.AsAGUIMessages().ToList(),
        },
    },
};

await foreach (AgentResponseUpdate update in
    remoteAgent.RunStreamingAsync([nextMessage], session, continuationOptions))
{
    // Process the continued response.
}

Egy folytatási kérésben csak az új üzeneteket küldje el. MapAGUIServer a(z) parentRunId használatával választja ki az üzemeltetett ügynök munkamenetét, a(z) threadId használatával pedig azonosítja a folytatott futtatást. Az üzemeltetett munkamenetek megőrzése nélkül minden kérés új kiszolgálói munkamenetet kap; az ügyfél ehelyett újraküldheti a beszélgetési előzményeket.

A kiszolgáló tulajdonában lévő AgentSession állapot kérések közötti megőrzéséhez konfigurálja az üzemeltetett munkamenetek megőrzését és elkülönítését, majd képezze le a megnevezett üzemeltetett ügynököt a következővel MapAGUIServer: . Az AG-UI-specifikus bizalmi határral kapcsolatban lásd a Üzemi és biztonsági szempontok című részt.

Következő lépések

Háttéreszközök használata AG-UI használatával

Prerequisites

Mielőtt hozzákezdene, győződjön meg arról, hogy a következők vannak:

Megjegyzés:

Ezek a minták Azure OpenAI-modelleket használnak. További információ: Azure OpenAI-modellek üzembe helyezése a Foundryvel.

Megjegyzés:

Ezek a minták hitelesítéshez használatosak DefaultAzureCredential . Győződjön meg arról, hogy hitelesítve van az Azure-ral (pl. keresztül az login). További információkért tekintse meg az Azure Identity dokumentációját.

Warning

A AG-UI protokoll még fejlesztés alatt áll, és változhat. Ezeket a mintákat a protokoll fejlődésével folyamatosan frissítjük.

1. lépés: AG-UI-kiszolgáló létrehozása

A AG-UI-kiszolgáló üzemelteti az AI-ügynököt, és a FastAPI használatával HTTP-végpontokon keresztül teszi elérhetővé.

A szükséges csomagok telepítése

Telepítse a kiszolgálóhoz szükséges csomagokat:

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

Vagy uv:

uv pip install agent-framework-ag-ui --prerelease=allow

Ez automatikusan telepíti a(z) agent-framework-core-t, fastapi-t, uvicorn-t és sse-starlette-t függőségként.

Kiszolgálókód

Hozzon létre egy fájlt:server.py

"""AG-UI server example."""

import os

from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
from azure.identity import AzureCliCredential
from fastapi import FastAPI

# Read required configuration
endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
deployment_name = os.environ.get("AZURE_OPENAI_CHAT_COMPLETION_MODEL")

if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
if not deployment_name:
    raise ValueError("AZURE_OPENAI_CHAT_COMPLETION_MODEL environment variable is required")

chat_client = OpenAIChatCompletionClient(
    model=deployment_name,
    azure_endpoint=endpoint,
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

# Create the AI agent
agent = Agent(
    name="AGUIAssistant",
    instructions="You are a helpful assistant.",
    client=chat_client,
)

# Create FastAPI app
app = FastAPI(title="AG-UI Server")

# Register the AG-UI endpoint
add_agent_framework_fastapi_endpoint(app, agent, "/")

if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="127.0.0.1", port=8888)

Alapfogalmak

  • add_agent_framework_fastapi_endpoint: A AG-UI végpont regisztrálása automatikus kérés-/válaszkezeléssel és SSE-streameléssel
  • Agent: Az ügynök-keretrendszer, amely a bejövő kéréseket kezeli
  • FastAPI-integráció: A FastAPI natív aszinkron támogatását használja a streamelési válaszokhoz
  • Utasítások: Az ügynök alapértelmezett utasításokat tartalmaz, amelyeket az ügyfélüzenetek felülírhatnak
  • Konfiguráció: OpenAIChatCompletionClient explicit Azure-útválasztási bemeneteket fogad el, például model, azure_endpoint, api_versionés credential, és beolvassa a környezeti változókból is

A kiszolgáló konfigurálása és futtatása

Adja meg a szükséges környezeti változókat:

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_CHAT_COMPLETION_MODEL="gpt-4o-mini"

Futtassa a kiszolgálót:

python server.py

Vagy használja közvetlenül az uvicorn-t:

uvicorn server:app --host 127.0.0.1 --port 8888

A kiszolgáló elkezd figyelni http://127.0.0.1:8888-on.

2. lépés: AG-UI-ügyfél létrehozása

A AG-UI ügyfél csatlakozik a távoli kiszolgálóhoz, és megjeleníti a streamelési válaszokat.

A szükséges csomagok telepítése

A AG-UI csomag már telepítve van, amely tartalmazza a AGUIChatClientkövetkezőket:

# Already installed with agent-framework-ag-ui
pip install agent-framework-ag-ui --pre

Ügyfélkód

Hozzon létre egy fájlt:client.py

"""AG-UI client example."""

import asyncio
import os

from agent_framework import Agent
from agent_framework_ag_ui import AGUIChatClient


async def main():
    """Main client loop."""
    # Get server URL from environment or use default
    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:8888/")
    print(f"Connecting to AG-UI server at: {server_url}\n")

    # Create AG-UI chat client
    chat_client = AGUIChatClient(endpoint=server_url)

    # Create agent with the chat client
    agent = Agent(
        name="ClientAgent",
        client=chat_client,
        instructions="You are a helpful assistant.",
    )

    # Get a thread for conversation continuity
    thread = agent.create_session()

    try:
        while True:
            # Get user input
            message = input("\nUser (:q or quit to exit): ")
            if not message.strip():
                print("Request cannot be empty.")
                continue

            if message.lower() in (":q", "quit"):
                break

            # Stream the agent response
            print("\nAssistant: ", end="", flush=True)
            async for update in agent.run(message, session=thread, stream=True):
                # Print text content as it streams
                if update.text:
                    print(f"\033[96m{update.text}\033[0m", end="", flush=True)

            print("\n")

    except KeyboardInterrupt:
        print("\n\nExiting...")
    except Exception as e:
        print(f"\n\033[91mAn error occurred: {e}\033[0m")


if __name__ == "__main__":
    asyncio.run(main())

Alapfogalmak

  • Server-Sent események (SSE):: A protokoll SSE formátumot használ (data: {json}\n\n)
  • Eseménytípusok: A különböző események metaadatokat és tartalmat biztosítanak (NAGYBETŰ aláhúzással):
    • RUN_STARTED: Az ügynök megkezdte a feldolgozást
    • TEXT_MESSAGE_START: Az ügynöktől érkező szöveges üzenet kezdete
    • TEXT_MESSAGE_CONTENT: Inkrementális szöveg streamelve az ügynöktől (mezővel delta)
    • TEXT_MESSAGE_END: Szöveges üzenet vége
    • RUN_FINISHED: Sikeres befejezés
    • RUN_ERROR: Hibainformációk
  • Mezőelnevezés: Az eseménymezők a camelCaset használják (pl. threadId, , runId) messageId
  • Szálkezelés: A threadId segít fenntartani a beszélgetési környezetet a kérések között
  • Client-Side utasítások: A rendszerüzenetek az ügyféltől érkeznek

Az ügyfél konfigurálása és futtatása

Igény szerint egyéni kiszolgáló URL-címét is beállíthatja:

export AGUI_SERVER_URL="http://127.0.0.1:8888/"

Futtassa a klienst (egy külön terminálban):

python client.py

3. lépés: A teljes rendszer tesztelése

A kiszolgáló és az ügyfél futtatásával most már tesztelheti a teljes rendszert.

Várható kimenet

$ python client.py
Connecting to AG-UI server at: http://127.0.0.1:8888/

User (:q or quit to exit): What is 2 + 2?

[Run Started - Thread: abc123, Run: xyz789]
2 + 2 equals 4.
[Run Finished - Thread: abc123, Run: xyz789]

User (:q or quit to exit): Tell me a fun fact about space

[Run Started - Thread: abc123, Run: def456]
Here's a fun fact: A day on Venus is longer than its year! Venus takes
about 243 Earth days to rotate once on its axis, but only about 225 Earth
days to orbit the Sun.
[Run Finished - Thread: abc123, Run: def456]

User (:q or quit to exit): :q

Színkódolt kimenet

Az ügyfél különböző tartalomtípusokat jelenít meg különböző színekkel:

  • Sárga: Elindított értesítések futtatása
  • Cián: Ügynök szöveges válaszai (valós időben streamelve)
  • Zöld: Befejezési értesítések futtatása
  • Piros: Hibaüzenetek

Tesztelés curl használatával (nem kötelező)

Az ügyfél futtatása előtt manuálisan tesztelheti a kiszolgálót a curl használatával:

curl -N http://127.0.0.1:8888/ \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is 2 + 2?"}
    ]
  }'

Látni kell, hogy a Server-Sent események visszaáramlanak.

data: {"type":"RUN_STARTED","threadId":"...","runId":"..."}

data: {"type":"TEXT_MESSAGE_START","messageId":"...","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"The"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":" answer"}

...

data: {"type":"TEXT_MESSAGE_END","messageId":"..."}

data: {"type":"RUN_FINISHED","threadId":"...","runId":"..."}

Egy tétlen adatfolyam esetén a curl `: keepalive` megjegyzéssorokat is megjeleníthet. Ezek SSE-szállítási megjegyzések, nem AG-UI események.

Hogyan működik?

Server-Side folyamatmenet

  1. Az ügyfél HTTP POST-kérést küld üzenetekkel
  2. A FastAPI-végpont megkapja a kérést
  3. AgentFrameworkAgent wrapper irányítja a végrehajtást
  4. Az Ügynök az Agent Framework használatával dolgozza fel az üzeneteket
  5. AgentFrameworkEventBridge az ügynökfrissítéseket AG-UI eseményekké alakítja
  6. A válaszok Server-Sent eseményekként (SSE) lesznek továbbítva
  7. A kapcsolat bezárul, amikor a futtatás befejeződik

Ügyféloldali műveletfolyam

  1. Az ügyfél HTTP POST-kérést küld a kiszolgálóvégpontnak
  2. A kiszolgáló SSE-adatfolyammal válaszol
  3. Az ügyfél JSON-eseményekként elemzi a bejövő data: sorokat
  4. Minden esemény a típusától függően jelenik meg
  5. threadId a beszélgetés folytonosságának biztosítása érdekében kerül rögzítésre
  6. A stream akkor fejeződik be, amikor RUN_FINISHED az esemény megérkezik

Protokoll részletei

A AG-UI protokoll a következőket használja:

  • HTTP POST kérések küldéséhez
  • A szerver által küldött események (SSE) használata a válaszok streameléséhez.
  • JSON az esemény szerializálásához
  • Témaazonosítók a beszélgetési környezet fenntartásához
  • Azonosítók futtatása az egyes végrehajtások nyomon követéséhez
  • Eseménytípus elnevezése: NAGYBETŰVEL és aláhúzásjelekkel (pl. RUN_STARTED, TEXT_MESSAGE_CONTENT)
  • Mező elnevezése: camelCase (pl. threadId, runId, messageId)
  • SSE életben tartó megjegyzések 15 másodpercenként, miközben az adatfolyam inaktív. A csak data: sorokat feldolgozó ügyfelek automatikusan figyelmen kívül hagyják ezeket a megjegyzéseket.

Gyakori minták

Egyéni kiszolgáló konfigurálása

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Add CORS for web clients
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

add_agent_framework_fastapi_endpoint(
    app,
    agent,
    "/agent",
    keepalive_seconds=30,  # Defaults to 15; set to None to disable
)

keepalive_seconds pozitív szám vagy None kell legyen.

Több ügynök

app = FastAPI()

weather_agent = Agent(name="weather", ...)
finance_agent = Agent(name="finance", ...)

add_agent_framework_fastapi_endpoint(app, weather_agent, "/weather")
add_agent_framework_fastapi_endpoint(app, finance_agent, "/finance")

Hibakezelés

try:
    async for event in client.send_message(message):
        if event.get("type") == "RUN_ERROR":
            error_msg = event.get("message", "Unknown error")
            print(f"Error: {error_msg}")
            # Handle error appropriately
except httpx.HTTPError as e:
    print(f"HTTP error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Troubleshooting

A kapcsolat elutasítva

Győződjön meg arról, hogy a kiszolgáló fut az ügyfél indítása előtt:

# Terminal 1
python server.py

# Terminal 2 (after server starts)
python client.py

Hitelesítési hibák

Győződjön meg arról, hogy hitelesítve van az Azure-ral:

az login

Ellenőrizze, hogy rendelkezik-e a megfelelő szerepkör-hozzárendeléssel az Azure OpenAI-erőforráson.

A streamelés nem működik

Ellenőrizze, hogy az ügyfél időtúllépése elegendő-e:

httpx.AsyncClient(timeout=60.0)  # 60 seconds should be enough

Hosszú ideig futó ügynökök esetén ennek megfelelően növelje az időtúllépést.

Az inaktív adatfolyamok alapértelmezés szerint 15 másodpercenként egy SSE életben tartó kommentet küldenek. Ha egy proxy hamarabb zárja be az inaktív kapcsolatokat, a végpont regisztrálásakor konfiguráljon egy kisebb pozitív keepalive_seconds értéket.

A szál kontextusa veszett el

Az ügyfél automatikusan kezeli a szál folytonosságát. Ha az összefüggés elveszett:

  1. Annak ellenőrzése, hogy threadId az eseményekről RUN_STARTED van-e rögzítve
  2. Győződjön meg arról, hogy ugyanazt az ügyfélpéldányt használja az üzenetek között
  3. Ellenőrizze, hogy a kiszolgáló megkapja-e a thread_id-t a következő kérésekben.

Következő lépések

Most, hogy megismerte az AG-UI alapjait, a következőt teheti:

További források

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

Akkor használható aguiprovider.NewAgent , ha a Go-alkalmazásnak ügynökként kell meghívnia egy AG-UI-kiszolgálót:

import aguiSSEClient "github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/client/sse"

a := aguiprovider.NewAgent(
    aguiSSEClient.NewClient(aguiSSEClient.Config{Endpoint: serverURL}),
    aguiprovider.AgentConfig{},
)

Tip

A teljes, futtatható példákért tekintse meg az AG-UI első lépésekhez készült kiszolgálóval és az ügyféloldali mintákkal kapcsolatos példákat.

  • Last updated on