Komma igång med AG-UI

Den här självstudien visar hur du skapar både server- och klientprogram med hjälp av AG-UI-protokollet med .NET eller Python och Agent Framework. Du får lära dig hur du skapar en AG-UI server som är värd för en AI-agent och en klient som ansluter till den för interaktiva konversationer.

Vad du kommer att bygga

I slutet av den här självstudien har du:

En AG-UI server som är värd för en AI-agent som är tillgänglig via HTTP
Ett klientprogram som ansluter till servern och strömmar svar
Förstå hur AG-UI-protokollet fungerar med Agent Framework

Förutsättningar

Kontrollera att du har följande innan du börjar:

.NET 8.0 eller senare
Azure OpenAI-tjänstslutpunkt och distribution konfigurerad
Azure CLI installerat och autentiserat
Användaren har Cognitive Services OpenAI Contributor rollen för Azure OpenAI-resursen

Anmärkning

De här exemplen använder Azure OpenAI-modeller. Mer information finns i distribuera Azure OpenAI-modeller med Microsoft Foundry.

Anmärkning

Dessa exempel använder DefaultAzureCredential för autentisering. Kontrollera att du är autentiserad med Azure (t.ex. via az login). Mer information finns i dokumentationen om Azure Identity.

Varning

Protokollet AG-UI är fortfarande under utveckling och kan komma att ändras. Vi kommer att hålla dessa exempel uppdaterade när protokollet utvecklas.

Steg 1: Skapa en AG-UI Server

AG-UI-servern är värd för din AI-agent och exponerar den via HTTP-slutpunkter med hjälp av ASP.NET Core.

Anmärkning

Serverprojektet kräver Microsoft.NET.Sdk.Web SDK. Om du skapar ett nytt projekt från grunden kan du använda dotnet new web eller se till att .csproj filen används <Project Sdk="Microsoft.NET.Sdk.Web"> i stället för Microsoft.NET.Sdk.

Installera nödvändiga paket

Installera nödvändiga paket för servern:

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease
dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease

Anmärkning

Paketet Microsoft.Extensions.AI.OpenAI krävs för tilläggsmetoden AsIChatClient() som konverterar OpenAI:er ChatClient till det IChatClient gränssnitt som förväntas av Agent Framework.

Serverkod

Skapa en fil med namnet Program.cs:

// Copyright (c) Microsoft. All rights reserved.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.Extensions.AI;
using OpenAI.Chat;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();
builder.Services.AddAGUI();

WebApplication app = builder.Build();

string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");

// Create the AI agent
ChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName);

AIAgent agent = chatClient.AsIChatClient().AsAIAgent(
    name: "AGUIAssistant",
    instructions: "You are a helpful assistant.");

// Map the AG-UI agent endpoint
app.MapAGUI("/", agent);

await app.RunAsync();

Viktiga begrepp

AddAGUI: Registrerar AG-UI tjänster med containern för beroendeinmatning
MapAGUI: Tilläggsmetod som registrerar AG-UI slutpunkt med automatisk hantering av begäran/svar och SSE-strömning
ChatClient och AsIChatClient(): AzureOpenAIClient.GetChatClient() returnerar OpenAI:s ChatClient typ. Tilläggsmetoden AsIChatClient() (från Microsoft.Extensions.AI.OpenAI) konverterar den till IChatClient det gränssnitt som krävs av Agent Framework
AsAIAgent: Skapar en Agent Framework-agent från en IChatClient
ASP.NET Core-integrering: Använder ASP.NET Cores interna asynkrona stöd för strömningssvar
Instruktioner: Agenten skapas med standardinstruktioner som kan åsidosättas av klientmeddelanden
Konfiguration: AzureOpenAIClient med DefaultAzureCredential ger säker autentisering

Konfigurera och köra servern

Ange nödvändiga miljövariabler:

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

Kör servern:

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

Servern börjar lyssna på http://localhost:8888.

Anmärkning

Håll den här servern igång medan du konfigurerar och kör klienten i steg 2. Både servern och klienten måste köras samtidigt för att hela systemet ska fungera.

Steg 2: Skapa en AG-UI-klient

Den AG-UI klienten ansluter till fjärrservern och visar strömmande svar.

Viktigt!

Innan du kör klienten kontrollerar du att AG-UI-servern från steg 1 körs på http://localhost:8888.

Installera nödvändiga paket

Installera AG-UI-klientbiblioteket:

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

Anmärkning

Paketet Microsoft.Agents.AI innehåller tilläggsmetoden AsAIAgent() .

Klientkod

Skapa en fil med namnet Program.cs:

// Copyright (c) Microsoft. All rights reserved.

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

string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";

Console.WriteLine($"Connecting to AG-UI server at: {serverUrl}\n");

// Create the AG-UI client agent
using HttpClient httpClient = new()
{
    Timeout = TimeSpan.FromSeconds(60)
};

AGUIChatClient chatClient = new(httpClient, serverUrl);

AIAgent agent = chatClient.AsAIAgent(
    name: "agui-client",
    description: "AG-UI Client Agent");

AgentSession session = await agent.CreateSessionAsync();
List<ChatMessage> messages =
[
    new(ChatRole.System, "You are a helpful assistant.")
];

try
{
    while (true)
    {
        // Get user input
        Console.Write("\nUser (:q or quit to exit): ");
        string? message = Console.ReadLine();

        if (string.IsNullOrWhiteSpace(message))
        {
            Console.WriteLine("Request cannot be empty.");
            continue;
        }

        if (message is ":q" or "quit")
        {
            break;
        }

        messages.Add(new ChatMessage(ChatRole.User, message));

        // Stream the response
        bool isFirstUpdate = true;
        string? threadId = null;

        await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
        {
            ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();

            // First update indicates run started
            if (isFirstUpdate)
            {
                threadId = chatUpdate.ConversationId;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"\n[Run Started - Thread: {chatUpdate.ConversationId}, Run: {chatUpdate.ResponseId}]");
                Console.ResetColor();
                isFirstUpdate = false;
            }

            // Display streaming text content
            foreach (AIContent content in update.Contents)
            {
                if (content is TextContent textContent)
                {
                    Console.ForegroundColor = ConsoleColor.Cyan;
                    Console.Write(textContent.Text);
                    Console.ResetColor();
                }
                else if (content is ErrorContent errorContent)
                {
                    Console.ForegroundColor = ConsoleColor.Red;
                    Console.WriteLine($"\n[Error: {errorContent.Message}]");
                    Console.ResetColor();
                }
            }
        }

        Console.ForegroundColor = ConsoleColor.Green;
        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
        Console.ResetColor();
    }
}
catch (Exception ex)
{
    Console.WriteLine($"\nAn error occurred: {ex.Message}");
}

Viktiga begrepp

Server-Sent Events (SSE): Protokollet använder SSE för strömningssvar
AGUIChatClient: Klientklass som ansluter till AG-UI servrar och implementerar IChatClient
AsAIAgent: Tilläggsmetod på AGUIChatClient för att skapa en agent från klienten
RunStreamingAsync: Strömmar svar som AgentResponseUpdate objekt
AsChatResponseUpdate: Tilläggsmetod för åtkomst till chattspecifika egenskaper som ConversationId och ResponseId
Sessionshantering: Upprätthåller AgentSession konversationskontexten mellan begäranden
Innehållstyper: Svar inkluderar TextContent för meddelanden och ErrorContent för fel

Konfigurera och köra klienten

Du kan också ange en anpassad server-URL:

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

Kör klienten i en separat terminal (se till att servern från steg 1 körs):

dotnet run

Steg 3: Testa det fullständiga systemet

När både servern och klienten körs kan du nu testa hela systemet.

Förväntade utdata

$ dotnet run
Connecting to AG-UI server at: http://localhost:8888

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

[Run Started - Thread: thread_abc123, Run: run_xyz789]
2 + 2 equals 4.
[Run Finished - Thread: thread_abc123]

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

[Run Started - Thread: thread_abc123, Run: 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: thread_abc123]

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

Färgkodad utdata

Klienten visar olika innehållstyper med distinkta färger:

Gul: Meddelanden om start av körning
Cyan: Agenttextsvar (strömmas i realtid)
Grön: Kör aviseringar om slutförande
Röd: Felmeddelanden

Så här fungerar det

Flöde på Serversidan

Klienten skickar HTTP POST-begäran med meddelanden
ASP.NET Core-slutpunkten tar emot begäran via MapAGUI
Agenten bearbetar meddelandena med Agent Framework
Svar konverteras till AG-UI händelser
Händelser strömmas tillbaka som Server-Sent Events (SSE)
Anslutningen stängs när processen är klar

Klientsideflöde

AGUIChatClient skickar HTTP POST-begäran till serverslutpunkten
Servern svarar med SSE-ström
Klienten parsar inkommande händelser i AgentResponseUpdate objekt
Varje uppdatering visas baserat på dess innehållstyp
ConversationId samlas in för konversationskontinuitet
Dataströmmen slutförs när körningen avslutas

Protokollinformation

Protokollet AG-UI använder:

HTTP POST för att skicka begäranden
Server-Sent Events (SSE) för strömningssvar
JSON för händelse serialisering
Tråd-ID :er (som ConversationId) för att upprätthålla konversationskontext
Kör ID:er (som ResponseId) för att spåra enskilda körningar

Nästa steg

Nu när du förstår grunderna i AG-UI kan du:

Lägg till serverdelsverktyg: Skapa anpassade funktionsverktyg för din domän

Ytterligare resurser

Förutsättningar

Kontrollera att du har följande innan du börjar:

Python 3.10 eller senare
Azure OpenAI-tjänstslutpunkt och distribution konfigurerad
Azure CLI installerat och autentiserat
Användaren har Cognitive Services OpenAI Contributor rollen för Azure OpenAI-resursen

Anmärkning

De här exemplen använder Azure OpenAI-modeller. Mer information finns i distribuera Azure OpenAI-modeller med Foundry.

Anmärkning

Dessa exempel använder DefaultAzureCredential för autentisering. Kontrollera att du är autentiserad med Azure (t.ex. via az login). Mer information finns i dokumentationen om Azure Identity.

Varning

Protokollet AG-UI är fortfarande under utveckling och kan komma att ändras. Vi kommer att hålla dessa exempel uppdaterade när protokollet utvecklas.

Steg 1: Skapa en AG-UI Server

AG-UI-servern är värd för din AI-agent och exponerar den via HTTP-slutpunkter med FastAPI.

Installera nödvändiga paket

Installera nödvändiga paket för servern:

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

Eller med uv:

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

Detta installerar automatiskt agent-framework-core, fastapi och uvicorn som beroenden.

Serverkod

Skapa en fil med namnet server.py:

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

import os

from agent_framework import Agent
from agent_framework.azure import AzureOpenAIChatClient
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_DEPLOYMENT_NAME")

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

chat_client = AzureOpenAIChatClient(
    credential=AzureCliCredential(),
    endpoint=endpoint,
    deployment_name=deployment_name,
)

# Create the AI agent
agent = Agent(
    name="AGUIAssistant",
    instructions="You are a helpful assistant.",
    chat_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)

Viktiga begrepp

add_agent_framework_fastapi_endpoint: Registrerar AG-UI slutpunkten med automatisk hantering av begäran/svar och SSE-strömning
Agent: Agent Framework-agenten som hanterar inkommande begäranden
FastAPI-integrering: Använder FastAPI:s interna asynkrona stöd för strömningssvar
Instruktioner: Agenten skapas med standardinstruktioner som kan åsidosättas av klientmeddelanden
Konfiguration: AzureOpenAIChatClient läser från miljövariabler eller accepterar parametrar direkt

Konfigurera och köra servern

Ange nödvändiga miljövariabler:

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

Kör servern:

python server.py

Eller använda uvicorn direkt:

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

Servern börjar lyssna på http://127.0.0.1:8888.

Steg 2: Skapa en AG-UI-klient

Den AG-UI klienten ansluter till fjärrservern och visar strömmande svar.

Installera nödvändiga paket

Det AG-UI paketet är redan installerat, som innehåller AGUIChatClient:

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

Klientkod

Skapa en fil med namnet 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(server_url=server_url)

    # Create agent with the chat client
    agent = Agent(
        name="ClientAgent",
        chat_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())

Viktiga begrepp

Server-Sent Events (SSE): Protokollet använder SSE-format (data: {json}\n\n)
Händelsetyper: Olika händelser tillhandahåller metadata och innehåll (VERSALER med understreck):
- RUN_STARTED: Agenten har börjat bearbeta
- TEXT_MESSAGE_START: Start av ett textmeddelande från agenten
- TEXT_MESSAGE_CONTENT: Inkrementell text som strömmas från agenten, med fältet delta
- TEXT_MESSAGE_END: Slutet på ett textmeddelande
- RUN_FINISHED: Slutfört
- RUN_ERROR: Felinformation
Fältnamngivning: Händelsefält använder camelCase (t.ex. threadId, runId, messageId)
Trådhantering: Upprätthåller threadId konversationskontexten mellan begäranden
Client-Side instruktioner: Systemmeddelanden skickas från klienten

Konfigurera och köra klienten

Du kan också ange en anpassad server-URL:

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

Kör klienten (i en separat terminal):

python client.py

Steg 3: Testa det fullständiga systemet

När både servern och klienten körs kan du nu testa hela systemet.

Förväntade utdata

$ 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

Färgkodad utdata

Klienten visar olika innehållstyper med distinkta färger:

Gul: Meddelanden om start av körning
Cyan: Agenttextsvar (strömmas i realtid)
Grön: Kör aviseringar om slutförande
Röd: Felmeddelanden

Testa med curl (valfritt)

Innan du kör klienten kan du testa servern manuellt med curl:

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?"}
    ]
  }'

Du bör se Server-Sent Events som strömmas tillbaka:

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":"..."}

Så här fungerar det

Flöde på Serversidan

Klienten skickar HTTP POST-begäran med meddelanden
FastAPI-slutpunkten tar emot begäran
AgentFrameworkAgent wrapper orkestrerar körningen
Agenten bearbetar meddelandena med Agent Framework
AgentFrameworkEventBridge konverterar agentuppdateringar till AG-UI händelser
Svar strömmas tillbaka som Server-Sent Events (SSE)
Anslutningen stängs när processen är klar

Klientsideflöde

Klienten skickar HTTP POST-begäran till serverslutpunkten
Servern svarar med SSE-ström
Klienten parsar inkommande data: rader som JSON-händelser
Varje händelse visas baserat på dess typ
threadId samlas in för konversationskontinuitet
Flödet kompletteras när RUN_FINISHED händelsen anländer

Protokollinformation

Protokollet AG-UI använder:

HTTP POST för att skicka begäranden
Server-Sent Events (SSE) för strömningssvar
JSON för händelse serialisering
Tråd-ID:t för att upprätthålla konversationskontext
Kör ID:t för att spåra enskilda körningar
Namngivning av händelsetyp: VERSALER med understreck (t.ex. RUN_STARTED, TEXT_MESSAGE_CONTENT)
Namn på fält: camelCase (t.ex. threadId, runId, messageId)

Vanliga mönster

Anpassad serverkonfiguration

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

Flera agenter

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

Felhantering

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

Felsökning

Anslutningen nekades

Kontrollera att servern körs innan du startar klienten:

# Terminal 1
python server.py

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

Autentiseringsfel

Kontrollera att du är autentiserad med Azure:

az login

Kontrollera att du har rätt rolltilldelning för Azure OpenAI-resursen.

Strömning fungerar inte

Kontrollera att klientens timeout är tillräcklig:

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

För långkörande agenter ökar du tidsgränsen därefter.

Trådkontext förlorad

Klienten hanterar automatiskt trådkontinuitet. Om kontexten går förlorad:

Kontrollera att threadId samlas in från RUN_STARTED händelser
Kontrollera att samma klientinstans används mellan meddelanden
Kontrollera att servern tar emot thread_id i efterföljande begäranden

Nästa steg

Nu när du förstår grunderna i AG-UI kan du:

Lägg till serverdelsverktyg: Skapa anpassade funktionsverktyg för din domän

Ytterligare resurser

Feedback

Var den här sidan hjälpsam?

Last updated on 2026-01-22

Dela via

Komma igång med AG-UI

Vad du kommer att bygga

Förutsättningar

Steg 1: Skapa en AG-UI Server

Installera nödvändiga paket

Serverkod

Viktiga begrepp

Konfigurera och köra servern

Steg 2: Skapa en AG-UI-klient

Installera nödvändiga paket

Klientkod

Viktiga begrepp

Konfigurera och köra klienten

Steg 3: Testa det fullständiga systemet

Förväntade utdata

Färgkodad utdata

Så här fungerar det

Flöde på Serversidan

Klientsideflöde

Protokollinformation

Nästa steg

Ytterligare resurser

Förutsättningar

Steg 1: Skapa en AG-UI Server

Installera nödvändiga paket

Serverkod

Viktiga begrepp

Konfigurera och köra servern

Steg 2: Skapa en AG-UI-klient

Installera nödvändiga paket

Klientkod

Viktiga begrepp

Konfigurera och köra klienten

Steg 3: Testa det fullständiga systemet

Förväntade utdata

Färgkodad utdata

Testa med curl (valfritt)

Så här fungerar det

Flöde på Serversidan

Klientsideflöde

Protokollinformation

Vanliga mönster

Anpassad serverkonfiguration

Flera agenter

Felhantering

Felsökning

Anslutningen nekades

Autentiseringsfel

Strömning fungerar inte

Trådkontext förlorad

Nästa steg

Ytterligare resurser

Feedback

Ytterligare resurser