Udostępnij przez

Wprowadzenie do AG-UI

W tym samouczku przedstawiono sposób kompilowania aplikacji serwerowych i klienckich przy użyciu protokołu AG-UI przy użyciu platformy .NET lub Python i programu Agent Framework. Dowiesz się, jak utworzyć serwer AG-UI hostujący agenta sztucznej inteligencji i klienta łączącego się z nim na potrzeby konwersacji interakcyjnych.

Co będziesz budować

Po ukończeniu tego samouczka będziesz mieć następujące elementy:

  • Serwer AG-UI hostuje agenta sztucznej inteligencji dostępnego za pośrednictwem protokołu HTTP
  • Aplikacja kliencka, która łączy się z serwerem i przesyła strumieniowo odpowiedzi
  • Informacje o sposobie działania protokołu AG-UI z platformą Agent Framework

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

Uwaga / Notatka

Te przykłady korzystają z modeli usługi Azure OpenAI. Aby uzyskać więcej informacji, zobacz jak wdrażać modele usługi Azure OpenAI za pomocą rozwiązania Azure AI Foundry.

Uwaga / Notatka

Przykłady te używają DefaultAzureCredential do uwierzytelniania. Upewnij się, że uwierzytelniasz się przy użyciu platformy Azure (np. za pośrednictwem polecenia az login). Aby uzyskać więcej informacji, zobacz dokumentację usługi Azure Identity.

Ostrzeżenie

Protokół AG-UI jest nadal opracowywany i podlega zmianie. Te przykłady będą aktualizowane w miarę rozwoju protokołu.

Krok 1. Tworzenie serwera AG-UI

Serwer AG-UI hostuje agenta sztucznej inteligencji i uwidacznia go za pośrednictwem punktów końcowych HTTP przy użyciu ASP.NET Core.

Uwaga / Notatka

Projekt serwera wymaga zestawu Microsoft.NET.Sdk.Web SDK. Jeśli tworzysz nowy projekt od podstaw, użyj dotnet new web lub upewnij się, że twój plik .csproj używa <Project Sdk="Microsoft.NET.Sdk.Web"> zamiast Microsoft.NET.Sdk.

Instalowanie wymaganych pakietów

Zainstaluj niezbędne pakiety dla serwera:

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

Uwaga / Notatka

Pakiet Microsoft.Extensions.AI.OpenAI jest wymagany dla AsIChatClient() metody rozszerzenia, która konwertuje interfejs OpenAI ChatClient na IChatClient interfejs oczekiwany przez program Agent Framework.

Kod serwera

Utwórz plik o nazwie 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();

Kluczowe pojęcia

  • AddAGUI: rejestruje usługi AG-UI za pomocą kontenera wstrzykiwania zależności
  • MapAGUI: metoda rozszerzenia, która rejestruje punkt końcowy AG-UI z automatyczną obsługą żądań/odpowiedzi i przesyłaniem strumieniowym SSE
  • ChatClient i AsIChatClient(): AzureOpenAIClient.GetChatClient() zwraca typ interfejsu ChatClient OpenAI. Metoda rozszerzenia AsIChatClient() (pochodząca z Microsoft.Extensions.AI.OpenAI) konwertuje na wymagany przez Agent Framework interfejs IChatClient.
  • AsAIAgent: Tworzy agenta programu Agent Framework na podstawie elementu IChatClient
  • integracja ASP.NET Core: korzysta z natywnej obsługi asynchronicznego środowiska ASP.NET Core na potrzeby odpowiedzi przesyłanych strumieniowo
  • Instrukcje: agent jest tworzony za pomocą domyślnych instrukcji, które mogą być zastępowane przez komunikaty klienta
  • Konfiguracja: AzureOpenAIClient z DefaultAzureCredential zapewnieniem bezpiecznego uwierzytelniania

Konfigurowanie i uruchamianie serwera

Ustaw wymagane zmienne środowiskowe:

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

Uruchom serwer:

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

Serwer rozpocznie nasłuchiwanie na http://localhost:8888.

Uwaga / Notatka

Zachowaj działanie tego serwera podczas konfigurowania i uruchamiania klienta w kroku 2. Zarówno serwer, jak i klient muszą działać jednocześnie, aby pełny system działał.

Krok 2. Tworzenie klienta AG-UI

Klient AG-UI łączy się z serwerem zdalnym i wyświetla strumieniowe odpowiedzi.

Ważne

Przed uruchomieniem klienta upewnij się, że serwer AG-UI z kroku 1 jest uruchomiony pod adresem http://localhost:8888.

Instalowanie wymaganych pakietów

Zainstaluj bibliotekę klienta AG-UI:

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

Uwaga / Notatka

Pakiet Microsoft.Agents.AI udostępnia metodę AsAIAgent() rozszerzenia.

Kod klienta

Utwórz plik o nazwie 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}");
}

Kluczowe pojęcia

  • Server-Sent Events (SSE): Protokół używa protokołu SSE na potrzeby odpowiedzi przesyłanych strumieniowo
  • AGUIChatClient: klasa klienta, która łączy się z serwerami AG-UI i implementuje IChatClient
  • AsAIAgent: metoda rozszerzenia na AGUIChatClient do tworzenia agenta z klienta
  • RunStreamingAsync: przesyła strumieniowo odpowiedzi jako AgentResponseUpdate obiekty
  • AsChatResponseUpdate: metoda rozszerzenia w celu uzyskania dostępu do właściwości specyficznych dla czatu, takich jak ConversationId i ResponseId
  • Zarządzanie sesjami: AgentSession utrzymuje kontekst konwersacji między żądaniami
  • Typy zawartości: odpowiedzi obejmują TextContent komunikaty i ErrorContent błędy

Konfigurowanie i uruchamianie klienta

Opcjonalnie ustaw niestandardowy adres URL serwera:

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

Uruchom klienta w osobnym terminalu (upewnij się, że serwer z kroku 1 jest uruchomiony):

dotnet run

Krok 3. Testowanie kompletnego systemu

Po uruchomieniu serwera i klienta można teraz przetestować kompletny system.

Oczekiwane dane wyjściowe

$ 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

Kodowane kolorem dane wyjściowe

Klient wyświetla różne typy zawartości z różnymi kolorami:

  • Żółty: uruchamianie powiadomień
  • Cyan: Odpowiedzi tekstowe agenta (przesyłane strumieniowo w czasie rzeczywistym)
  • Zielony: uruchamianie powiadomień o zakończeniu
  • Czerwony: Komunikaty o błędach

Jak to działa

przepływ po stronie serwera

  1. Klient wysyła żądanie HTTP POST z komunikatami
  2. Punk końcowy ASP.NET Core odbiera żądanie za pomocą MapAGUI
  3. Agent przetwarza komunikaty przy użyciu struktury agenta
  4. Odpowiedzi są konwertowane na zdarzenia AG-UI
  5. Zdarzenia są przesyłane strumieniowo jako zdarzenia wysyłane przez serwer (SSE)
  6. Połączenie zostanie zamknięte po zakończeniu przebiegu

Przepływ po stronie klienta

  1. AGUIChatClient wysyła żądanie HTTP POST do punktu końcowego serwera
  2. Serwer odpowiada strumieniem SSE
  3. Klient analizuje zdarzenia przychodzące do AgentResponseUpdate obiektów
  4. Każda aktualizacja jest wyświetlana na podstawie typu zawartości
  5. ConversationId jest przechwytywany w celu zapewnienia ciągłości konwersacji
  6. Strumień kończy się po zakończeniu przebiegu

Szczegóły protokołu

Protokół AG-UI używa:

  • HTTP POST na potrzeby wysyłania żądań
  • Server-Sent Events (SSE) do strumieniowego przesyłania odpowiedzi
  • Kod JSON na potrzeby serializacji zdarzeń
  • Identyfikatory wątków (jako ConversationId) do obsługi kontekstu konwersacji
  • Uruchamianie identyfikatorów (jako ResponseId) na potrzeby śledzenia poszczególnych wykonań

Dalsze kroki

Skoro już znasz podstawy AG-UI, możesz:

Dodatkowe zasoby

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

Uwaga / Notatka

Te przykłady korzystają z modeli usługi Azure OpenAI. Aby uzyskać więcej informacji, zobacz jak wdrażać modele usługi Azure OpenAI za pomocą rozwiązania Azure AI Foundry.

Uwaga / Notatka

Przykłady te używają DefaultAzureCredential do uwierzytelniania. Upewnij się, że uwierzytelniasz się przy użyciu platformy Azure (np. za pośrednictwem polecenia az login). Aby uzyskać więcej informacji, zobacz dokumentację usługi Azure Identity.

Ostrzeżenie

Protokół AG-UI jest nadal opracowywany i podlega zmianie. Te przykłady będą aktualizowane w miarę rozwoju protokołu.

Krok 1. Tworzenie serwera AG-UI

Serwer AG-UI hostuje agenta sztucznej inteligencji i uwidacznia go za pośrednictwem punktów końcowych HTTP przy użyciu interfejsu FastAPI.

Instalowanie wymaganych pakietów

Zainstaluj niezbędne pakiety dla serwera:

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

Lub przy użyciu uv:

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

Spowoduje to automatyczne zainstalowanie agent-framework-core, fastapi i uvicorn jako zależności.

Kod serwera

Utwórz plik o nazwie 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)

Kluczowe pojęcia

  • add_agent_framework_fastapi_endpoint: rejestruje punkt końcowy AG-UI z automatyczną obsługą żądań/odpowiedzi i przesyłaniem strumieniowym SSE
  • Agent: Agent frameworku, który będzie obsługiwać przychodzące żądania
  • Integracja FastAPI: używa natywnego wsparcia dla asynchronicznych operacji FastAPI w odpowiedziach strumieniowych
  • Instrukcje: agent jest tworzony za pomocą domyślnych instrukcji, które mogą być zastępowane przez komunikaty klienta
  • Konfiguracja: AzureOpenAIChatClient odczytuje ze zmiennych środowiskowych lub akceptuje parametry bezpośrednio

Konfigurowanie i uruchamianie serwera

Ustaw wymagane zmienne środowiskowe:

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

Uruchom serwer:

python server.py

Lub bezpośrednio przy użyciu uvicorn:

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

Serwer rozpocznie nasłuchiwanie na http://127.0.0.1:8888.

Krok 2. Tworzenie klienta AG-UI

Klient AG-UI łączy się z serwerem zdalnym i wyświetla strumieniowe odpowiedzi.

Instalowanie wymaganych pakietów

Pakiet AG-UI jest już zainstalowany, który zawiera element AGUIChatClient:

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

Kod klienta

Utwórz plik o nazwie 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())

Kluczowe pojęcia

  • Server-Sent Events (SSE): Protokół używa formatu SSE (data: {json}\n\n)
  • Typy zdarzeń: Różne zdarzenia zapewniają metadane i zawartość (WIELKIMI LITERAMI z podkreśleniami):
    • RUN_STARTED: Agent rozpoczął przetwarzanie
    • TEXT_MESSAGE_START: Początek wiadomości SMS od agenta
    • TEXT_MESSAGE_CONTENT: tekst przyrostowy przesyłany strumieniowo z agenta (z polem delta)
    • TEXT_MESSAGE_END: Koniec wiadomości SMS
    • RUN_FINISHED: Pomyślne ukończenie
    • RUN_ERROR: Informacje o błędzie
  • Nazewnictwo pól: Pola zdarzeń używają camelCase (np. threadId, runId, messageId)
  • Zarządzanie wątkami: threadId utrzymuje kontekst konwersacji między żądaniami
  • Instrukcje po stronie klienta: komunikaty systemowe są wysyłane po stronie klienta

Konfigurowanie i uruchamianie klienta

Opcjonalnie ustaw niestandardowy adres URL serwera:

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

Uruchom klienta (w osobnym terminalu):

python client.py

Krok 3. Testowanie kompletnego systemu

Po uruchomieniu serwera i klienta można teraz przetestować kompletny system.

Oczekiwane dane wyjściowe

$ 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

Kodowane kolorem dane wyjściowe

Klient wyświetla różne typy zawartości z różnymi kolorami:

  • Żółty: uruchamianie powiadomień
  • Cyan: Odpowiedzi tekstowe agenta (przesyłane strumieniowo w czasie rzeczywistym)
  • Zielony: uruchamianie powiadomień o zakończeniu
  • Czerwony: Komunikaty o błędach

Testowanie przy użyciu narzędzia curl (opcjonalnie)

Przed uruchomieniem klienta można przetestować serwer ręcznie przy użyciu narzędzia 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?"}
    ]
  }'

Powinny być widoczne zdarzenia typu Server-Sent przesyłane strumieniowo z powrotem:

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

Jak to działa

przepływ po stronie serwera

  1. Klient wysyła żądanie HTTP POST z komunikatami
  2. Punkt końcowy fastAPI odbiera żądanie
  3. AgentFrameworkAgent opakowanie orkiestruje wykonywanie
  4. Agent przetwarza komunikaty przy użyciu struktury agenta
  5. AgentFrameworkEventBridge konwertuje aktualizacje agenta na zdarzenia AG-UI
  6. Odpowiedzi są przesyłane strumieniowo jako zdarzenia Server-Sent (SSE)
  7. Połączenie zostanie zamknięte po zakończeniu przebiegu

Przepływ po stronie klienta

  1. Klient wysyła żądanie HTTP POST do punktu końcowego serwera
  2. Serwer odpowiada strumieniem SSE
  3. Klient analizuje wiersze przychodzące data: jako zdarzenia JSON
  4. Każde zdarzenie jest wyświetlane na podstawie jego typu
  5. threadId jest przechwytywany w celu zapewnienia ciągłości konwersacji
  6. Strumień kończy się, gdy nadejdzie zdarzenie RUN_FINISHED

Szczegóły protokołu

Protokół AG-UI używa:

  • HTTP POST na potrzeby wysyłania żądań
  • Server-Sent Events (SSE) do strumieniowego przesyłania odpowiedzi
  • Kod JSON na potrzeby serializacji zdarzeń
  • Identyfikatory wątków do utrzymania kontekstu konwersacji
  • Identyfikatory uruchomień do śledzenia poszczególnych wykonów
  • Nazewnictwo typów zdarzeń: WIELKIE LITERY z podkreśleniami (np. RUN_STARTED, TEXT_MESSAGE_CONTENT)
  • Nazewnictwo pól: camelCase (np. threadId, runId, messageId)

Typowe wzorce

Konfiguracja niestandardowego serwera

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

Wielu agentów

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

Obsługa błędów

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

Rozwiązywanie problemów

Odmowa połączenia

Przed uruchomieniem klienta upewnij się, że serwer jest uruchomiony:

# Terminal 1
python server.py

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

Błędy uwierzytelniania

Upewnij się, że uwierzytelniasz się na platformie Azure:

az login

Sprawdź, czy masz poprawne przypisanie roli w zasobie Azure OpenAI.

Przesyłanie strumieniowe nie działa

Sprawdź, czy czas oczekiwania klienta jest wystarczający.

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

W przypadku długotrwałych agentów należy odpowiednio zwiększyć limit czasu.

Utracono kontekst wątku

Klient automatycznie zarządza ciągłością wątków. Jeśli kontekst zostanie utracony:

  1. Sprawdź, czy threadId jest przechwytywane z RUN_STARTED zdarzeń
  2. Upewnij się, że to samo wystąpienie klienta jest używane we wszystkich wiadomościach
  3. Sprawdź, czy serwer odbiera thread_id w kolejnych żądaniach

Dalsze kroki

Skoro już znasz podstawy AG-UI, możesz:

Dodatkowe zasoby

  • Last updated on