Начало работы с AG-UI

В этом руководстве показано, как создавать серверные и клиентские приложения с помощью протокола AG-UI с помощью .NET или Python и Agent Framework. Вы узнаете, как создать сервер AG-UI, на котором размещен агент ИИ и клиент, который подключается к нему для интерактивных бесед.

Что вы будете создавать

В конце этого руководства вы получите следующее:

Сервер AG-UI, на котором размещен агент ИИ, доступный через HTTP
Клиентское приложение, которое подключается к серверу и передаёт ответы в потоковом режиме
Общие сведения о том, как работает протокол AG-UI с Agent Framework

Предпосылки

Прежде чем начать, убедитесь, что у вас есть следующее:

.NET 8.0 или более поздней версии
Конечная точка и развертывание службы Azure OpenAI настроены
Установленный и прошедший проверку подлинности Azure CLI
Пользователь обладает Cognitive Services OpenAI Contributor ролью для ресурса Azure OpenAI

Замечание

В этих примерах используются модели Azure OpenAI. Дополнительные сведения см. в статье о развертывании моделей Azure OpenAI с помощью Azure AI Foundry.

Замечание

Эти примеры используют DefaultAzureCredential для проверки подлинности. Убедитесь, что вы прошли проверку подлинности в Azure (например, через az login). Дополнительную информацию см. в документации по идентификации Azure.

Предупреждение

Протокол AG-UI по-прежнему находится в процессе разработки и подлежит изменению. Эти примеры будут обновлены по мере развития протокола.

Шаг 1. Создание сервера AG-UI

Сервер AG-UI размещает вашего агента ИИ и предоставляет его через конечные точки HTTP с помощью ASP.NET Core.

Замечание

Для проекта сервера требуется Microsoft.NET.Sdk.Web пакет SDK. Если вы создаете новый проект с нуля, используйте dotnet new web или убедитесь, что ваш файл .csproj использует <Project Sdk="Microsoft.NET.Sdk.Web"> вместо Microsoft.NET.Sdk.

Установка обязательных пакетов

Установите необходимые пакеты для сервера:

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

Замечание

Пакет Microsoft.Extensions.AI.OpenAI необходим для метода расширения AsIChatClient(), который преобразует компонент ChatClient OpenAI в интерфейс, ожидаемый фреймворком IChatClient Agent Framework.

Код сервера

Создайте файл с именем 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();

Основные понятия

AddAGUI: регистрирует службы AG-UI в контейнере внедрения зависимостей.
MapAGUI: метод расширения, регистрирующий конечную точку AG-UI с автоматической обработкой запросов и ответов и потоковой передачей данных через SSE
ChatClient и AsIChatClient(): AzureOpenAIClient.GetChatClient() возвращает тип OpenAI ChatClient . AsIChatClient() Метод расширения (из Microsoft.Extensions.AI.OpenAI) преобразует его в интерфейс, требуемый для Agent Framework.
AsAIAgent: создает агент Agent Framework из IChatClient
ASP.NET Базовая интеграция: использует встроенную асинхронную поддержку ASP.NET Core для потоковых ответов
Инструкции. Агент создается с инструкциями по умолчанию, которые можно переопределить клиентскими сообщениями.
Конфигурация: AzureOpenAIClient с DefaultAzureCredential обеспечением безопасной проверки подлинности

Настройка и запуск сервера

Задайте необходимые переменные среды:

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

Запустите сервер:

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

Сервер начнет прослушивать http://localhost:8888.

Замечание

Продолжайте работу этого сервера при настройке и запуске клиента на шаге 2. Для работы полной системы необходимо одновременно запустить сервер и клиент.

Шаг 2. Создание клиента AG-UI

Клиент AG-UI подключается к удаленному серверу и отображает потоковые ответы.

Это важно

Перед запуском клиента убедитесь, что сервер AG-UI из шага 1 запущен в http://localhost:8888.

Установка обязательных пакетов

Установите клиентская библиотека AG-UI:

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

Замечание

Пакет Microsoft.Agents.AI предоставляет метод расширения AsAIAgent().

Клиентский код

Создайте файл с именем 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}");
}

Основные понятия

События от сервера (SSE): протокол использует SSE для стриминг ответов.
AGUIChatClient: класс клиента, который подключается к AG-UI серверам и реализует IChatClient
AsAIAgent: метод AGUIChatClient расширения для создания агента из клиента
RunStreamingAsync: потоки ответов в виде AgentResponseUpdate объектов
AsChatResponseUpdate: метод расширения для доступа к свойствам чата, таким как ConversationId и ResponseId
Управление сеансами: AgentSession поддерживает контекст сеанса в запросах
Типы контента: ответы включают сообщения TextContent и ошибки ErrorContent

Настройка и запуск клиента

При необходимости задайте URL-адрес пользовательского сервера:

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

Запустите клиент в отдельном терминале (убедитесь, что сервер из шага 1 запущен):

dotnet run

Шаг 3. Тестирование полной системы

При работе с сервером и клиентом теперь можно протестировать полную систему.

Ожидаемые выходные данные

$ 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

Цветовое кодирование выходных данных

Клиент отображает различные типы контента с различными цветами:

Желтый: уведомления о запуске программы
Cyan: текстовые ответы агента (стриминг в реальном времени)
Зеленый: выполнение уведомлений о завершении
Красный: сообщения об ошибках

Принцип работы

серверный поток

Клиент отправляет HTTP-запрос POST с сообщениями
ASP.NET конечная точка Core получает запрос через MapAGUI
Агент обрабатывает сообщения с помощью Agent Framework
Ответы преобразуются в события AG-UI
События передаются обратно как события, отправляемые сервером (SSE)
Подключение закрывается после завершения выполнения

поток клиентской стороны

AGUIChatClient отправляет HTTP-запрос POST на конечную точку сервера
Сервер отвечает с помощью потока SSE
Клиент анализирует входящие события в AgentResponseUpdate объекты
Каждое обновление отображается на основе типа контента
ConversationId сохраняется для непрерывности беседы
Поток завершается, когда выполнение завершено

Сведения о протоколе

Используется протокол AG-UI:

HTTP POST для отправки запросов
события, передаваемые сервером (SSE) для ответов в режиме потоковой передачи
JSON для сериализации событий
Идентификаторы потоков (как ConversationId) для поддержания контекста беседы
Идентификаторы выполнения (как ResponseId) для отслеживания индивидуальных выполнений

Дальнейшие шаги

Теперь, когда вы понимаете основы ag-UI, вы можете:

Добавление внутренних инструментов: создание пользовательских средств функций для домена

Дополнительные ресурсы

Предпосылки

Прежде чем начать, убедитесь, что у вас есть следующее:

Python 3.10 или более поздней версии
Конечная точка и развертывание службы Azure OpenAI настроены
Установленный и прошедший проверку подлинности Azure CLI
Пользователь обладает Cognitive Services OpenAI Contributor ролью для ресурса Azure OpenAI

Замечание

Предупреждение

Шаг 1. Создание сервера AG-UI

Сервер AG-UI размещает агент ИИ и предоставляет его через конечные точки HTTP с помощью FastAPI.

Установка обязательных пакетов

Установите необходимые пакеты для сервера:

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

Или с помощью ультрафиолета:

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

Это автоматически установит agent-framework-coreи fastapiuvicorn в качестве зависимостей.

Код сервера

Создайте файл с именем 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)

Основные понятия

add_agent_framework_fastapi_endpoint: регистрирует конечную точку AG-UI с автоматической обработкой запросов и ответов и потоковой передачей SSE
Agent: агент Агента Framework, обрабатывающий входящие запросы
Интеграция FastAPI: использует встроенную асинхронную поддержку FastAPI для потоковых ответов.
Инструкции. Агент создается с инструкциями по умолчанию, которые можно переопределить клиентскими сообщениями.
Конфигурация: AzureOpenAIChatClient считывается из переменных среды или принимает параметры напрямую

Настройка и запуск сервера

Задайте необходимые переменные среды:

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

Запустите сервер:

python server.py

Или с помощью uvicorn напрямую:

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

Сервер начнет прослушивать http://127.0.0.1:8888.

Шаг 2. Создание клиента AG-UI

Клиент AG-UI подключается к удаленному серверу и отображает потоковые ответы.

Установка обязательных пакетов

Пакет AG-UI уже установлен, который включает в себя AGUIChatClient:

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

Клиентский код

Создайте файл с именем 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())

Основные понятия

Server-Sent Events (SSE): протокол использует SSE-формат (data: {json}\n\n)
Типы событий: различные события предоставляют метаданные и содержимое (ВЕРХНИЙ РЕГИСТР с подчеркиваниями):
- RUN_STARTED: агент начал обработку
- TEXT_MESSAGE_START: начало текстового сообщения от агента
- TEXT_MESSAGE_CONTENT: добавочный текст, поступающий от агента (с полем delta)
- TEXT_MESSAGE_END: конец текстового сообщения
- RUN_FINISHED: успешное завершение
- RUN_ERROR: сведения об ошибке
Именование полей: поля событий используют CamelCase (например, threadId, runId, messageId)
Управление потоками: threadId поддерживает контекст сессии между запросами
Инструкции на стороне клиента. Сообщения системы отправляются клиентом.

Настройка и запуск клиента

При необходимости задайте URL-адрес пользовательского сервера:

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

Запустите клиент (в отдельном терминале):

python client.py

Шаг 3. Тестирование полной системы

При работе с сервером и клиентом теперь можно протестировать полную систему.

Ожидаемые выходные данные

$ 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

Цветовое кодирование выходных данных

Клиент отображает различные типы контента с различными цветами:

Желтый: уведомления о запуске программы
Cyan: текстовые ответы агента (стриминг в реальном времени)
Зеленый: выполнение уведомлений о завершении
Красный: сообщения об ошибках

Тестирование с помощью curl (необязательно)

Перед запуском клиента можно протестировать сервер вручную с помощью 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?"}
    ]
  }'

Вы должны увидеть поток событий, отправляемых сервером:

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

Принцип работы

серверный поток

Клиент отправляет HTTP-запрос POST с сообщениями
Конечная точка FastAPI получает запрос
AgentFrameworkAgent оболочка оркеструет выполнение
Агент обрабатывает сообщения с помощью Agent Framework
AgentFrameworkEventBridge преобразует обновления агента в события AG-UI
Ответы передаются обратно как события, отправляемые сервером (SSE)
Подключение закрывается после завершения выполнения

поток клиентской стороны

Клиент отправляет HTTP-запрос POST на конечную точку сервера
Сервер отвечает с помощью потока SSE
Клиент анализирует входящие data: строки как события JSON
Каждое событие отображается на основе его типа
threadId сохраняется для непрерывности беседы
Поток завершается при RUN_FINISHED поступлении события

Сведения о протоколе

Используется протокол AG-UI:

HTTP POST для отправки запросов
события, передаваемые сервером (SSE) для ответов в режиме потоковой передачи
JSON для сериализации событий
Идентификаторы потоков для поддержания контекста беседы
Идентификаторы запусков для отслеживания отдельных выполнений
Именование типов событий: ВЕРХНИЙ РЕГИСТР с символами подчеркивания (например, RUN_STARTED, TEXT_MESSAGE_CONTENT)
Именование полей: camelCase (например, threadId, runId, messageId)

Общие шаблоны

Настройка настраиваемого сервера

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

Несколько агентов

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

Обработка ошибок

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

Устранение неполадок

Отклонено подключение

Убедитесь, что сервер запущен перед запуском клиента:

# Terminal 1
python server.py

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

Ошибки проверки подлинности

Убедитесь, что вы прошли проверку подлинности в Azure:

az login

Убедитесь, что у вас есть правильное назначение ролей в ресурсе Azure OpenAI.

Потоковая трансляция не работает

Убедитесь, что тайм-аут клиента достаточно велик.

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

Для длительных агентов увеличьте время ожидания соответствующим образом.

Контекст потока потерян

Клиент автоматически управляет непрерывностью потоков. Если контекст потерян:

Проверка того, что threadId фиксируется из RUN_STARTED событий
Убедитесь, что один и тот же экземпляр клиента используется для всех сообщений
Убедитесь, что сервер получает thread_id в последующих запросах.

Дальнейшие шаги

Теперь, когда вы понимаете основы ag-UI, вы можете:

Добавление внутренних инструментов: создание пользовательских средств функций для домена

Дополнительные ресурсы

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-22

Поделиться через

Начало работы с AG-UI

Что вы будете создавать

Предпосылки

Шаг 1. Создание сервера AG-UI

Установка обязательных пакетов

Код сервера

Основные понятия

Настройка и запуск сервера

Шаг 2. Создание клиента AG-UI

Установка обязательных пакетов

Клиентский код

Основные понятия

Настройка и запуск клиента

Шаг 3. Тестирование полной системы

Ожидаемые выходные данные

Цветовое кодирование выходных данных

Принцип работы

серверный поток

поток клиентской стороны

Сведения о протоколе

Дальнейшие шаги

Дополнительные ресурсы

Предпосылки

Шаг 1. Создание сервера AG-UI

Установка обязательных пакетов

Код сервера

Основные понятия

Настройка и запуск сервера

Шаг 2. Создание клиента AG-UI

Установка обязательных пакетов

Клиентский код

Основные понятия

Настройка и запуск клиента

Шаг 3. Тестирование полной системы

Ожидаемые выходные данные

Цветовое кодирование выходных данных

Тестирование с помощью curl (необязательно)

Принцип работы

серверный поток

поток клиентской стороны

Сведения о протоколе

Общие шаблоны

Настройка настраиваемого сервера

Несколько агентов

Обработка ошибок

Устранение неполадок

Отклонено подключение

Ошибки проверки подлинности

Потоковая трансляция не работает

Контекст потока потерян

Дальнейшие шаги

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы