시작하기

시작하기 (Introduction)

AG-UI 통합(integration)을 처음부터 만들어 보는 방법을 안내해 드릴게요. AG-UI 프로토콜로 소통하는 에이전트를 만들려면 어떤 흐름을 거쳐야 하는지, 서버 구현과 미들웨어 구현 중 어느 쪽을 골라야 할지 하나씩 짚어 드릴게요.

출처: 문서

본문

통합(Integration)이란 무엇인가요?

AG-UI 통합은 에이전트가 AG-UI 프로토콜로 말하게 만들어 줘요. 즉 에이전트가 AG-UI와 호환되는 어떤 클라이언트 애플리케이션이든 함께 동작할 수 있게 되는 거죠 — 채팅 인터페이스, 코파일럿(copilot), 커스텀 AI 도구 같은 것들이요.

마치 에이전트에 "만국 공통어 번역기"를 달아 주는 것과 같아요. 클라이언트마다 별도의 커스텀 API를 만들 필요 없이, AG-UI를 한 번만 구현해 두면 어떤 호환 애플리케이션이든 바로 동작하게 됩니다.

AG-UI와 통합하는 에이전트는 다음을 할 수 있어요.

  • 응답 스트리밍 - 생성되는 대로 실시간으로 나타나는 텍스트
  • 클라이언트 측 도구 호출 - 클라이언트가 정의한 함수와 서비스 활용
  • 상태 공유 - 에이전트의 상태를 양방향으로 공유
  • 범용 실행 - AG-UI와 호환되는 어떤 클라이언트 애플리케이션과도 통합
  • 그 외에도 많아요! - 전체 스펙은 여기에서 확인해 보세요.

언제 통합을 만들어야 하나요?

찾고 있는 통합이 integrations 페이지에 없다면 직접 통합을 만들어야 해요. 이 아래에 몇 가지 가이드가 준비되어 있으니 참고해 주세요!

반대로 이미 존재하는 통합(예: LangGraph, CrewAI, Mastra 등)을 활용하려 한다면 이 단계는 건너뛰고 바로 애플리케이션 만들기로 넘어가면 됩니다.

통합의 유형

통합이 필요하다고 결정하셨군요! 좋아요, AG-UI 통합을 구현하는 방법에는 크게 두 가지가 있어요.

  • 서버 구현 (Server Implementation) - 에이전트나 서버에서 직접 AG-UI 이벤트를 내보냅니다.
  • 미들웨어 구현 (Middleware Implementation) - 기존 프로토콜과 애플리케이션을 AG-UI 이벤트로 번역해 줍니다.

서버 구현을 쓸 때

서버 구현은 에이전트나 서버에서 AG-UI 이벤트를 직접 내보낼 수 있게 해 줘요. 에이전트 프레임워크를 쓰고 있지 않거나, 에이전트 프레임워크를 위한 프로토콜을 아직 만들지 않았다면 시작하기에 가장 좋은 방법이에요.

서버 구현은 이런 경우에도 좋아요.

  • 새 에이전트 프레임워크를 처음부터 만들 때
  • 어떤 이벤트를 어떻게 내보낼지 최대한 제어하고 싶을 때
  • 에이전트를 독립 API로 노출하고 싶을 때

미들웨어 구현을 쓸 때

미들웨어는 유연한 선택지예요. 기존 프로토콜과 애플리케이션을 AG-UI 이벤트로 번역해서, 기존 시스템과 AG-UI 사이의 다리를 만들어 줍니다.

미들웨어는 이런 경우에 좋아요.

  • 기존 프로토콜이나 API를 범용적으로 번역하고 싶을 때
  • 기존 시스템이나 프레임워크 안에서 작업해야 할 때
  • 에이전트 프레임워크나 시스템을 직접 제어할 수 없을 때

더 알아보기 (Learn more)