AG-UI 시작하기 안내

이 자습서에서는 .NET 또는 Python 및 에이전트 프레임워크에서 AG-UI 프로토콜을 사용하여 서버 및 클라이언트 애플리케이션을 빌드하는 방법을 보여 줍니다. 대화형 대화를 위해 AI 에이전트 및 해당 에이전트에 연결하는 클라이언트를 호스트하는 AG-UI 서버를 만드는 방법을 알아봅니다.

만들게 될 것들

이 자습서를 마치면 다음을 수행할 수 있습니다.

HTTP를 통해 액세스할 수 있는 AI 에이전트를 호스팅하는 AG-UI 서버
서버에 연결하고 응답을 스트리밍하는 클라이언트 애플리케이션
AG-UI 프로토콜이 Agent Framework에서 작동하는 방식 이해

필수 조건

시작하기 전에 다음이 있는지 확인합니다.

.NET 8.0 이상
구성된 Azure OpenAI 서비스 엔드포인트 및 배포
Azure CLI 설치 및 인증
Cognitive Services OpenAI Contributor 사용자에게 Azure OpenAI 리소스에 대한 역할이 있습니다.

비고

이러한 샘플은 Azure OpenAI 모델을 사용합니다. 자세한 내용은 Azure AI Foundry를 사용하여 Azure OpenAI 모델을 배포하는 방법을 참조하세요.

비고

이러한 샘플은 인증에 사용합니다 DefaultAzureCredential . Azure(예: 통해 az login)로 인증되었는지 확인합니다. 자세한 내용은 Azure ID 설명서를 참조하세요.

경고

AG-UI 프로토콜은 아직 개발 중이며 변경될 수 있습니다. 프로토콜이 발전함에 따라 이러한 샘플을 계속 업데이트합니다.

1단계: AG-UI 서버 만들기

AG-UI 서버는 AI 에이전트를 호스트하고 ASP.NET Core를 사용하여 HTTP 엔드포인트를 통해 노출합니다.

비고

서버 프로젝트에는 SDK가 Microsoft.NET.Sdk.Web 필요합니다. 새 프로젝트를 처음부터 만드는 경우 dotnet new web을(를) 사용하거나, .csproj 파일이 <Project Sdk="Microsoft.NET.Sdk.Web">을(를) 사용하고 있는지 확인하세요.

필수 패키지 설치

서버에 필요한 패키지를 설치합니다.

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 패키지는 OpenAI의 AsIChatClient()를 ChatClient에서 Agent Framework에서 기대하는 인터페이스인 IChatClient로 변환하는 확장 메서드에 필요합니다.

서버 코드

다음과 같은 파일을 만듭니다 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: 자동 요청/응답 처리 및 SSE 스트리밍을 사용하여 AG-UI 엔드포인트를 등록하는 확장 메서드
ChatClient and AsIChatClient(): AzureOpenAIClient.GetChatClient() OpenAI의 ChatClient 타입을 반환합니다. AsIChatClient() 확장 메서드(Microsoft.Extensions.AI.OpenAI에서) 는 에이전트 프레임워크에 필요한 IChatClient 인터페이스로 변환합니다.
AsAIAgent: IChatClient에서 에이전트 프레임워크 에이전트를 생성합니다.
ASP.NET Core 통합: 스트리밍 응답에 ASP.NET Core의 기본 비동기 지원을 사용합니다.
지침: 에이전트는 클라이언트 메시지에 의해 재정의될 수 있는 기본 지침으로 만들어집니다.
구성: AzureOpenAIClientDefaultAzureCredential과 함께 보안 인증을 제공합니다.

서버 구성 및 실행

필요한 환경 변수를 설정합니다.

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 클라이언트는 원격 서버에 연결하고 스트리밍 응답을 표시합니다.

중요합니다

클라이언트를 실행하기 전에 1단계의 AG-UI 서버가 실행 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}");
}

주요 개념

Server-Sent 이벤트(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
에이전트가 에이전트 프레임워크를 사용하여 메시지를 처리합니다.
응답이 AG-UI 이벤트로 변환됩니다.
이벤트는 SSE(Server-Sent 이벤트)로 다시 스트리밍됩니다.
실행이 완료되면 연결이 닫힙니다.

클라이언트 측 프로세스

AGUIChatClient HTTP POST 요청을 서버 엔드포인트로 보냅니다.
서버가 SSE 스트림으로 응답
클라이언트는 들어오는 이벤트를 구문 분석하여 AgentResponseUpdate 개체로 변환합니다.
각 업데이트는 콘텐츠 형식에 따라 표시됩니다.
ConversationId 는 대화 연속성을 위해 캡처됩니다.
실행이 완료되면 스트림이 완료됩니다.

프로토콜 세부 정보

AG-UI 프로토콜은 다음을 사용합니다.

요청을 보내기 위한 HTTP POST
스트리밍 응답에 대한 Server-Sent 이벤트(SSE)
이벤트 직렬화를 위한 JSON
대화 컨텍스트를 유지 관리하기 위한 스레드 ID(예: ConversationId)
개별 실행을 추적하기 위한 ID 실행(예: ResponseId)

다음 단계

이제 AG-UI의 기본 사항을 이해했으므로 다음을 수행할 수 있습니다.

백 엔드 도구 추가: 도메인에 대한 사용자 지정 함수 도구 만들기

추가 리소스

필수 조건

시작하기 전에 다음이 있는지 확인합니다.

Python 3.10 이상
구성된 Azure OpenAI 서비스 엔드포인트 및 배포
Azure CLI 설치 및 인증
Cognitive Services OpenAI Contributor 사용자에게 Azure OpenAI 리소스에 대한 역할이 있습니다.

비고

이러한 샘플은 Azure OpenAI 모델을 사용합니다. 자세한 내용은 Azure AI Foundry를 사용하여 Azure OpenAI 모델을 배포하는 방법을 참조하세요.

비고

이러한 샘플은 인증에 사용합니다 DefaultAzureCredential . Azure(예: 통해 az login)로 인증되었는지 확인합니다. 자세한 내용은 Azure ID 설명서를 참조하세요.

경고

AG-UI 프로토콜은 아직 개발 중이며 변경될 수 있습니다. 프로토콜이 발전함에 따라 이러한 샘플을 계속 업데이트합니다.

1단계: AG-UI 서버 만들기

AG-UI 서버는 AI 에이전트를 호스트하고 FastAPI를 사용하여 HTTP 엔드포인트를 통해 노출합니다.

필수 패키지 설치

서버에 필요한 패키지를 설치합니다.

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

또는 uv 사용:

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

이러한 agent-framework-core, fastapi, 및 uvicorn가 종속성으로 자동으로 설치됩니다.

서버 코드

다음과 같은 파일을 만듭니다 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: 자동 요청/응답 처리 및 SSE 스트리밍을 사용하여 AG-UI 엔드포인트를 등록합니다.
Agent: 들어오는 요청을 처리할 에이전트 프레임워크 에이전트
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 이벤트(SSE): 프로토콜은 SSE 형식(data: {json}\n\n)을 사용합니다.
이벤트 유형: 다양한 이벤트가 메타데이터 및 콘텐츠를 제공합니다(밑줄이 있는 대문자):
- RUN_STARTED: 에이전트가 처리를 시작했습니다.
- TEXT_MESSAGE_START: 에이전트의 문자 메시지 시작
- TEXT_MESSAGE_CONTENT: 에이전트에서 스트리밍된 증분 텍스트(delta 필드와 함께)
- TEXT_MESSAGE_END: 문자 메시지의 끝
- RUN_FINISHED: 성공적인 완료
- RUN_ERROR: 오류 정보
필드 명명: 이벤트 필드는 camelCase를 사용합니다(예: threadId, , runIdmessageId)
스레드 관리: threadId 요청 간에 대화 컨텍스트를 유지 관리합니다.
Client-Side 지침: 시스템 메시지가 클라이언트에서 전송됩니다.

클라이언트 구성 및 실행

필요에 따라 사용자 지정 서버 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?"}
    ]
  }'

Server-Sent 이벤트가 다시 스트리밍됩니다.

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 래퍼가 실행을 조정합니다.
에이전트가 에이전트 프레임워크를 사용하여 메시지를 처리합니다.
AgentFrameworkEventBridge 에이전트 업데이트를 AG-UI 이벤트로 변환
응답은 SSE(Server-Sent 이벤트)로 다시 스트리밍됩니다.
실행이 완료되면 연결이 닫힙니다.

클라이언트 측 프로세스

클라이언트가 서버 엔드포인트에 HTTP POST 요청을 보냅니다.
서버가 SSE 스트림으로 응답
클라이언트는 들어오는 data: 줄을 JSON 이벤트로 구문 분석합니다.
각 이벤트는 형식에 따라 표시됩니다.
threadId 는 대화 연속성을 위해 캡처됩니다.
이벤트가 도착하면 스트림이 완료 RUN_FINISHED 됩니다.

프로토콜 세부 정보

AG-UI 프로토콜은 다음을 사용합니다.

요청을 보내기 위한 HTTP POST
스트리밍 응답에 대한 Server-Sent 이벤트(SSE)
이벤트 직렬화를 위한 JSON
대화 컨텍스트를 유지 관리하기 위한 스레드 ID
개별 실행을 추적하기 위한 ID 실행
이벤트 유형 이름 지정: 밑줄이 있는 대문자(예: RUN_STARTED, TEXT_MESSAGE_CONTENT)
필드 이름 지정: camelCase(예: , threadId, runIdmessageId)

일반적인 패턴

사용자 지정 서버 구성

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

Troubleshooting

연결이 거부됨

클라이언트를 시작하기 전에 서버가 실행 중인지 확인합니다.

# 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

장기 실행 에이전트의 경우 시간 제한(timeout)을 알맞게 늘립니다.

스레드 컨텍스트 손실

클라이언트는 스레드 연속성을 자동으로 관리합니다. 컨텍스트가 손실된 경우:

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을 사용하여 테스트(선택 사항)

작동 방식

서버 측 처리 흐름

클라이언트 측 프로세스

프로토콜 세부 정보

일반적인 패턴

사용자 지정 서버 구성

여러 에이전트

오류 처리

Troubleshooting

연결이 거부됨

인증 오류

스트리밍이 작동하지 않음

스레드 컨텍스트 손실

다음 단계

추가 리소스

피드백

추가 리소스