AG-UI 는 실시간 스트리밍, 상태 관리 및 대화형 UI 구성 요소와 같은 고급 기능을 사용하여 웹 기반 AI 에이전트 애플리케이션을 빌드할 수 있는 프로토콜입니다. 에이전트 프레임워크 AG-UI 통합은 에이전트와 웹 클라이언트 간에 원활한 연결을 제공합니다.
AG-UI란?
AG-UI 다음을 제공하는 AI 에이전트 인터페이스를 빌드하기 위한 표준화된 프로토콜입니다.
- 원격 에이전트 호스팅: 여러 클라이언트에서 액세스할 수 있는 웹 서비스로 AI 에이전트 배포
- 실시간 스트리밍: 즉각적인 피드백을 위해 Server-Sent 이벤트(SSE)를 사용하여 에이전트 응답 스트리밍
- 표준화된 통신: 신뢰할 수 있는 에이전트 상호 작용을 위한 일관된 메시지 형식
- 세션 관리: 여러 요청에서 대화 컨텍스트 유지 관리
- 고급 기능: 휴먼 인더 루프 승인, 상태 동기화 및 사용자 지정 UI 렌더링
AG-UI 사용해야 하는 경우
필요한 경우 AG-UI 사용하는 것이 좋습니다.
- AI 에이전트와 상호 작용하는 웹 또는 모바일 애플리케이션 빌드
- 여러 동시 사용자가 액세스할 수 있는 서비스로 에이전트 배포
- 즉각적인 사용자 피드백을 제공하기 위해 실시간으로 에이전트 응답 스트리밍
- 사용자가 실행 전에 작업을 확인하는 승인 워크플로 구현
- 대화형 환경을 위해 클라이언트와 서버 간의 상태 동기화
- 에이전트 도구 호출을 기반으로 사용자 지정 UI 구성 요소 렌더링
AG-UI 시나리오
AG-UI 7가지 쇼케이스 시나리오를 정의합니다. MAF 지원은 SDK에 따라 다릅니다. 현재 지원 수준 및 구현 지침에 대해서는 이 페이지의 언어별 섹션을 사용합니다.
- 에이전트 채팅: 자동 도구 호출을 사용하는 기본 스트리밍 채팅
- 백 엔드 도구 렌더링: 클라이언트로 스트리밍된 결과와 함께 백 엔드에서 실행되는 도구
- 휴먼 인 더 루프: 사용자 확인을 위한 함수 승인 요청
- 에이전트 기반 생성형 UI: 진행 상황 업데이트가 포함된 장기 실행 작업을 위한 비동기 도구
- 도구 기반 생성 UI: 도구 호출을 기반으로 렌더링되는 사용자 지정 UI 구성 요소
- 공유 상태: 클라이언트와 서버 간의 양방향 상태 동기화
- 예측 상태 업데이트: 낙관적 상태 업데이트로 도구 인수 스트리밍
CopilotKit를 사용하여 에이전트 UI 빌드
CopilotKit 는 표준 AG-UI 프로토콜을 기반으로 에이전트 사용자 인터페이스를 빌드하기 위한 풍부한 UI 구성 요소를 제공합니다. CopilotKit는 스트리밍 채팅 인터페이스, 프런트 엔드 및 백 엔드 도구 호출, 휴먼 인더 루프 상호 작용, 생성 UI, 공유 상태 등을 지원합니다. CopilotKit가 AG-UI Dojo 샘플 애플리케이션에서 지원하는 다양한 에이전트 UI 시나리오의 예를 볼 수 있습니다.
CopilotKit React 프런트 엔드를 Agent Framework AG-UI 백 엔드에 연결하려면 엔드포인트를 HttpAgent CopilotKit 런타임에 등록합니다. 이렇게 하면 CopilotKit의 프런트 엔드 도구가 AG-UI 클라이언트 도구로 전달되고 모든 AG-UI 기능(스트리밍, 승인, 상태 동기화)이 자동으로 작동합니다.
CopilotKit는 처음부터 개발할 필요 없이, 세련된 사용자 경험을 제공하면서 에이전트의 역량에 집중할 수 있도록 도와줍니다. Microsoft Agent Framework 및 CopilotKit를 시작하는 방법에 대한 자세한 내용은 Microsoft Agent Framework integration for CopilotKit 설명서를 참조하세요.
.NET 통합
.NET 통합은 MAF AIAgent 를 AG-UI HTTP 엔드포인트로 노출합니다. 호스팅 어댑터는 에이전트의 응답 스트림을 AG-UI 이벤트로 변환합니다. 도구 실행 및 승인과 같은 핵심 에이전트 동작은 MAF의 일부로 유지됩니다.
.NET 통합을 사용하여 다음을 수행합니다.
- Server-Sent 이벤트(SSE)를 통해 에이전트 텍스트를 스트리밍합니다.
- Surface 백 엔드 및 프런트 엔드 도구는 AG-UI 이벤트로 호출됩니다.
- 클라이언트에 MAF 도구 승인 요청을 보내고 결정을 반환합니다.
- 클라이언트 상태, 상태 스냅샷과 델타, 그리고 전달된 속성을 교환합니다.
- AG-UI
threadId사용하여 지속형 호스팅 세션을 다시 시작합니다. - 동일한 엔드포인트 를 통해 에이전트로 변환된 워크플로 를 노출합니다.
AG-UI 클라이언트는 텍스트, 도구, 승인 및 상태 이벤트를 렌더링하는 방법을 결정합니다.
Architecture
C# 호스팅 패키지는 일반 MAF 에이전트를 중심으로 ASP.NET Core 엔드포인트를 추가합니다.
AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent
MapAGUIServer 는 AG-UI 요청을 MAF 메시지에 맞게 조정하고 옵션을 실행합니다. 그런 다음 AG-UI .NET SDK를 사용하여 에이전트의 스트리밍 응답을 AG-UI 이벤트로 변환합니다.
Installation
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease
다음 단계
관련 리소스
AG-UI 및 직접 에이전트 사용
에이전트 프레임워크 run 및 run(..., stream=True) 메서드를 사용하여 애플리케이션에서 직접 에이전트를 실행할 수 있지만 AG-UI 추가 기능을 제공합니다.
| 특징 | 직접 에이전트 사용 | AG-UI 통합 |
|---|---|---|
| Deployment | 애플리케이션에 포함 | HTTP를 통한 원격 서비스 |
| 클라이언트 액세스 | 단일 애플리케이션 | 여러 클라이언트(웹, 모바일) |
| Streaming | 프로세스 내의 비동기 순환 | 서버 전송 이벤트(SSE) |
| 상태 관리 | 애플리케이션에서 관리되는 | 양방향 프로토콜 수준 동기화 |
| 스레드 컨텍스트 | 애플리케이션에서 관리되는 | 프로토콜 관리 스레드 ID |
| 승인 워크플로 | 사용자 지정 구현 | 기본 제공 프로토콜 지원 |
아키텍처 개요
AG-UI 통합은 깨끗한 모듈식 아키텍처를 사용합니다.
┌─────────────────┐
│ Web Client │
│ (Browser/App) │
└────────┬────────┘
│ HTTP POST + SSE
▼
┌─────────────────────────┐
│ FastAPI Endpoint │
│ (add_agent_framework_ │
│ fastapi_endpoint) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ AgentFrameworkAgent │
│ (Protocol Wrapper) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Orchestrators │
│ (Execution Flow Logic) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Agent │
│ (Agent Framework) │
└────────┬────────────────┘
│
▼
┌─────────────────────────┐
│ Chat Client │
│ (Azure OpenAI, etc.) │
└─────────────────────────┘
주요 구성 요소
- FastAPI 엔드포인트: SSE 스트리밍, 구성 가능한 유지 주석 및 요청 라우팅을 처리하는 HTTP 엔드포인트
- AgentFrameworkAgent: 에이전트 프레임워크 에이전트를 AG-UI 프로토콜에 맞게 조정하는 경량 래퍼
- 오케스트레이터: 다양한 실행 흐름 처리(기본값, 휴먼 인 더 루프, 상태 관리)
- 이벤트 브리지: 에이전트 프레임워크 이벤트를 AG-UI 프로토콜 이벤트로 변환
- 메시지 어댑터: AG-UI 및 에이전트 프레임워크 메시지 형식 간의 양방향 변환
- 확인 전략: 도메인별 확인 메시지에 대한 확장 가능한 전략
에이전트 프레임워크가 AG-UI 변환하는 방법
에이전트 프레임워크 개념이 AG-UI 매핑되는 방식을 이해하면 효과적인 통합을 구축하는 데 도움이 됩니다.
| 에이전트 프레임워크 개념 | AG-UI에 해당하는 | 설명 |
|---|---|---|
Agent |
에이전트 엔드포인트 | 각 에이전트는 HTTP 엔드포인트가 됩니다. |
agent.run() |
HTTP POST 요청 | 클라이언트가 HTTP를 통해 메시지를 보냅니다. |
agent.run(..., stream=True) |
서버에서 보낸 이벤트 | SSE를 통한 스트리밍 응답 |
| 에이전트 응답 업데이트 | AG-UI 이벤트 |
TEXT_MESSAGE_CONTENT, TOOL_CALL_START 등 |
함수 도구(@tool) |
백 엔드 도구 | 서버에서 실행되고 결과가 클라이언트로 스트리밍됨 |
| 도구 승인 모드 | 휴먼 인 더 루프 | 프로토콜을 통한 승인 요청/응답 |
| 대화 기록 | 스레드 관리 |
threadId 는 요청 간에 컨텍스트를 유지 관리합니다. |
Installation
AG-UI 통합 패키지를 설치합니다.
pip install agent-framework-ag-ui --pre
이렇게 하면 핵심 에이전트 프레임워크와 AG-UI 통합 구성 요소가 모두 설치됩니다.
터미널 메시지 스냅샷 제어
기본적으로 AgentFrameworkAgent 전체 대본이 포함된 터미널 MESSAGES_SNAPSHOT 이벤트를 내보낸다.
HistoryProvider 또는 애플리케이션이 이미 대화 상태를 관리하는 경우, 각 실행이 끝날 때마다 클라이언트 대화 기록을 다시 작성하지 않도록 emit_messages_snapshot=False을 설정하세요:
from agent_framework_ag_ui import AgentFrameworkAgent
wrapped_agent = AgentFrameworkAgent(
agent=agent,
emit_messages_snapshot=False,
)
이 설정은 터미널 메시지 스냅샷만 숨깁니다. 다른 스트리밍 이벤트(예 RUN_FINISHED: )는 변경되지 않습니다.
다음 단계
AG-UI 통합을 시작하려면 다음을 수행합니다.
- 시작: 첫 번째 AG-UI 서버 및 클라이언트 빌드
- 백 엔드 도구 렌더링: 에이전트에 함수 도구 추가
- 워크플로: AG-UI 통해 다중 에이전트 워크플로 노출
- 휴먼 인 더 루프: 승인 워크플로 구현
- MCP 앱 호환성: AG-UI 엔드포인트에서 MCP 앱 사용
- 상태 관리: 클라이언트와 서버 간의 상태 동기화
추가 리소스
- 에이전트 프레임워크 설명서
- AG-UI 프로토콜 설명서
- AG-UI Dojo 앱 - 에이전트 프레임워크 통합을 보여주는 예제 애플리케이션
- CopilotKit MAF 통합 - AG-UI 백 엔드에 CopilotKit React 프런트 엔드 연결
- 에이전트 프레임워크 GitHub 리포지토리
Go는 서버와 클라이언트 모두에 대해 AG-UI provider/aguiprovider 지원합니다.
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)
}
Tip
전체 서버 및 클라이언트 샘플은 AG-UI Go 예제 를 참조하세요.