다음을 통해 공유

에이전트 프레임워크와 AG-UI 통합

AG-UI 는 실시간 스트리밍, 상태 관리 및 대화형 UI 구성 요소와 같은 고급 기능을 사용하여 웹 기반 AI 에이전트 애플리케이션을 빌드할 수 있는 프로토콜입니다. 에이전트 프레임워크 AG-UI 통합은 에이전트와 웹 클라이언트 간에 원활한 연결을 제공합니다.

AG-UI란?

AG-UI 다음을 제공하는 AI 에이전트 인터페이스를 빌드하기 위한 표준화된 프로토콜입니다.

  • 원격 에이전트 호스팅: 여러 클라이언트에서 액세스할 수 있는 웹 서비스로 AI 에이전트 배포
  • 실시간 스트리밍: 즉각적인 피드백을 위해 Server-Sent 이벤트(SSE)를 사용하여 에이전트 응답 스트리밍
  • 표준화된 통신: 신뢰할 수 있는 에이전트 상호 작용을 위한 일관된 메시지 형식
  • 세션 관리: 여러 요청에서 대화 컨텍스트 유지 관리
  • 고급 기능: 휴먼 인더 루프 승인, 상태 동기화 및 사용자 지정 UI 렌더링

AG-UI 사용해야 하는 경우

필요한 경우 AG-UI 사용하는 것이 좋습니다.

  • AI 에이전트와 상호 작용하는 웹 또는 모바일 애플리케이션 빌드
  • 여러 동시 사용자가 액세스할 수 있는 서비스로 에이전트 배포
  • 즉각적인 사용자 피드백을 제공하기 위해 실시간으로 에이전트 응답 스트리밍
  • 사용자가 실행 전에 작업을 확인하는 승인 워크플로 구현
  • 대화형 환경을 위해 클라이언트와 서버 간의 상태 동기화
  • 에이전트 도구 호출을 기반으로 사용자 지정 UI 구성 요소 렌더링

지원되는 기능

에이전트 프레임워크 AG-UI 통합은 7개의 AG-UI 프로토콜 기능을 모두 지원합니다.

  1. 에이전트 채팅: 자동 도구 호출을 사용하는 기본 스트리밍 채팅
  2. 백 엔드 도구 렌더링: 클라이언트로 스트리밍된 결과와 함께 백 엔드에서 실행되는 도구
  3. 휴먼 인 더 루프: 사용자 확인을 위한 함수 승인 요청
  4. 에이전트 생성 UI: 진행률 업데이트가 있는 장기 실행 작업을 위한 비동기 도구
  5. 도구 기반 생성 UI: 도구 호출을 기반으로 렌더링되는 사용자 지정 UI 구성 요소
  6. 공유 상태: 클라이언트와 서버 간의 양방향 상태 동기화
  7. 예측 상태 업데이트: 낙관적 상태 업데이트로 도구 인수 스트리밍

CopilotKit를 사용하여 에이전트 UI 빌드

CopilotKit 는 표준 AG-UI 프로토콜을 기반으로 에이전트 사용자 인터페이스를 빌드하기 위한 풍부한 UI 구성 요소를 제공합니다. CopilotKit는 스트리밍 채팅 인터페이스, 프런트 엔드 및 백 엔드 도구 호출, 휴먼 인더 루프 상호 작용, 생성 UI, 공유 상태 등을 지원합니다. CopilotKit가 AG-UI Dojo 샘플 애플리케이션에서 지원하는 다양한 에이전트 UI 시나리오의 예를 볼 수 있습니다.

CopilotKit는 휠을 재창조할 필요 없이 세련된 사용자 경험을 제공하면서 에이전트의 기능에 집중할 수 있도록 도와줍니다. Microsoft Agent Framework 및 CopilotKit 시작에 대한 자세한 내용은 CopilotKit용 Microsoft Agent Framework 통합 설명서를 참조하세요.

AG-UI 및 직접 에이전트 사용

에이전트 프레임워크 Run 및 RunStreamingAsync 메서드를 사용하여 애플리케이션에서 직접 에이전트를 실행할 수 있지만 AG-UI 추가 기능을 제공합니다.

특징 직접 에이전트 사용 AG-UI 통합
배치 애플리케이션에 포함 HTTP를 통한 원격 서비스
클라이언트 액세스 단일 애플리케이션 여러 클라이언트(웹, 모바일)
스트리밍 프로세스 내의 비동기 순환 Server-Sent 이벤트(SSE)
상태 관리 애플리케이션에서 관리되는 프로토콜 수준 상태 스냅샷
세션 컨텍스트 애플리케이션에서 관리되는 프로토콜로 관리되는 세션 ID
승인 워크플로 사용자 지정 구현 기본 제공 미들웨어 패턴

아키텍처 개요

AG-UI 통합은 ASP.NET Core를 사용하고 깨끗한 미들웨어 기반 아키텍처를 따릅니다.

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  ASP.NET Core           │
│  MapAGUI("/", agent)    │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AIAgent                │
│  (with Middleware)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  IChatClient            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

주요 구성 요소

  • ASP.NET 핵심 엔드포인트: MapAGUI 확장 메서드는 HTTP 요청 및 SSE 스트리밍을 처리합니다.
  • AIAgent: 에이전트 프레임워크 에이전트 생성 IChatClient 또는 사용자 지정 구현
  • 미들웨어 파이프라인: 승인, 상태 관리 및 사용자 지정 논리를 위한 선택적 미들웨어
  • 프로토콜 어댑터: 에이전트 프레임워크 형식과 AG-UI 프로토콜 이벤트 간 변환
  • 채팅 클라이언트: Microsoft.Extensions.AI 채팅 클라이언트(Azure OpenAI, OpenAI, Ollama 등)

에이전트 프레임워크가 AG-UI 변환하는 방법

에이전트 프레임워크 개념이 AG-UI 매핑되는 방식을 이해하면 효과적인 통합을 구축하는 데 도움이 됩니다.

에이전트 프레임워크 개념 AG-UI에 해당하는 Description
AIAgent 에이전트 엔드포인트 각 에이전트는 HTTP 엔드포인트가 됩니다.
agent.Run() HTTP POST 요청 클라이언트가 HTTP를 통해 메시지를 보냅니다.
agent.RunStreamingAsync() 서버에서 보낸 이벤트 SSE를 통한 스트리밍 응답
AgentResponseUpdate AG-UI 이벤트 자동으로 프로토콜 이벤트로 변환
AIFunctionFactory.Create() 백 엔드 도구 서버에서 실행되고 결과가 스트리밍됨
ApprovalRequiredAIFunction 휴먼 인 더 루프 미들웨어가 승인 프로토콜로 변환
AgentSession 세션 관리 ConversationId 는 컨텍스트를 유지 관리합니다.
ChatResponseFormat.ForJsonSchema<T>() 상태 스냅샷 구조적 출력이 상태 이벤트가 됩니다.

설치

AG-UI 통합은 ASP.NET Core 호스팅 패키지에 포함됩니다.

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore

이 패키지에는 을 포함하여 Microsoft.Extensions.AIAG-UI 통합에 필요한 모든 종속성이 포함됩니다.

다음 단계

AG-UI 통합을 시작하려면 다음을 수행합니다.

  1. 시작: 첫 번째 AG-UI 서버 및 클라이언트 빌드
  2. 백 엔드 도구 렌더링: 에이전트에 함수 도구 추가

추가 리소스

AG-UI 및 직접 에이전트 사용

에이전트 프레임워크 run 및 run(..., stream=True) 메서드를 사용하여 애플리케이션에서 직접 에이전트를 실행할 수 있지만 AG-UI 추가 기능을 제공합니다.

특징 직접 에이전트 사용 AG-UI 통합
배치 애플리케이션에 포함 HTTP를 통한 원격 서비스
클라이언트 액세스 단일 애플리케이션 여러 클라이언트(웹, 모바일)
스트리밍 프로세스 내의 비동기 순환 Server-Sent 이벤트(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에 해당하는 Description
Agent 에이전트 엔드포인트 각 에이전트는 HTTP 엔드포인트가 됩니다.
agent.run() HTTP POST 요청 클라이언트가 HTTP를 통해 메시지를 보냅니다.
agent.run(..., stream=True) 서버에서 보낸 이벤트 SSE를 통한 스트리밍 응답
에이전트 응답 업데이트 AG-UI 이벤트 TEXT_MESSAGE_CONTENT, TOOL_CALL_START 등
함수 도구(@tool) 백 엔드 도구 서버에서 실행되고 결과가 클라이언트로 스트리밍됨
도구 승인 모드 휴먼 인 더 루프 프로토콜을 통한 승인 요청/응답
대화 내용 스레드 관리 threadId 는 요청 간에 컨텍스트를 유지 관리합니다.

설치

AG-UI 통합 패키지를 설치합니다.

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

이렇게 하면 핵심 에이전트 프레임워크와 AG-UI 통합 구성 요소가 모두 설치됩니다.

다음 단계

AG-UI 통합을 시작하려면 다음을 수행합니다.

  1. 시작: 첫 번째 AG-UI 서버 및 클라이언트 빌드
  2. 백 엔드 도구 렌더링: 에이전트에 함수 도구 추가

추가 리소스

  • Last updated on