AG-UI Agents

• AG-UI Agent는 요청을 처리하고 이벤트 스트림으로 응답을 생성하는 AG-UI 프로토콜의 실행 단위
• LLM/RAG/멀티 에이전트 등 어떤 AI 시스템도 동일 인터페이스로 추상화하는 벤더 중립 컴포넌트
• AbstractAgent 계약을 따르는 표준화된 구체 구현체
• 메시지·상태·도구·기억·메타데이터를 한 단위로 묶은 합성 추상화 (compound abstraction)

해당 개념이 필요한 이유

• 다양한 AI 백엔드(LangGraph, CrewAI, Mastra…)를 동일한 UI에서 연결할 표준 단위 부재 해결
• LLM 호출은 stateless이지만 실제 사용자 경험은 대화·상태·도구·기억의 누적을 요구
• Multi-Agent, HITL, Reasoning 표시 등 고차 워크플로우를 단일 표준 모델로 표현 필요

AS-IS — 특정 AI 서비스에 직접 묶인 코드

sequenceDiagram
    autonumber
    participant UI as Frontend
    participant SVC as Specific AI Service

    UI->>SVC: 벤더 전용 요청
    SVC-->>UI: 벤더 전용 응답
    Note over UI,SVC: 백엔드 교체 시<br/>UI 전체 수정 필요<br/>도구·상태·기억 별도 구현

TO-BE — Agent 추상화로 캡슐화

sequenceDiagram
    autonumber
    participant UI as Frontend
    participant Agent as "AG-UI Agent (AbstractAgent)"
    participant Any as Any AI System

    UI->>Agent: runAgent(input)
    Agent->>Any: 내부 위임 (LLM/RAG/Multi-Agent...)
    Any-->>Agent: 결과
    Agent-->>UI: BaseEvent 스트림
    Note over Agent: 메시지·상태·도구·기억<br/>표준 인터페이스로 노출

Agent의 정체성 — 단순 LLM 호출이 아닌 이유

Agent는 LLM 호출 함수가 아니라 여러 능력을 묶은 합성 추상화다.

차원	LLM 호출	AG-UI Agent
입출력	prompt → completion	AG-UI Event 스트림 ↔ 양방향
상태	stateless	AG-UI State Management 보유
기억	매번 재구성	AG-UI Messages 자동 누적
도구	호출자가 매번 결합	AG-UI Tools 표준 채널
식별	없음	agentId, threadId, runId

Agent Type 3가지

1. AbstractAgent — 추상 베이스

AbstractAgent는 모든 에이전트가 구현해야 하는 추상 클래스로, run(input) → Observable<BaseEvent> 단 하나의 계약만 강제한다. 상태·메시지·이벤트 검증·미들웨어·구독자 알림은 베이스 클래스가 자동 처리한다.

2. HttpAgent — 표준 HTTP 구현체

AbstractAgent를 상속하는 클라이언트 측 구체 구현으로, 원격 AG-UI 호환 엔드포인트와 SSE/Binary 프로토콜로 통신한다. Frontend에서 가장 흔히 사용된다.

const agent = new HttpAgent({
  url: "https://your-agent-endpoint.com/agent",
  headers: { Authorization: "Bearer your-api-key" },
})

3. Custom Agent — 직접 구현

AbstractAgent를 상속해 임의의 AI 시스템(자체 LLM, RAG 파이프라인, 멀티 에이전트 컨트롤러)과 결합 가능하다.

Agent Capabilities 7가지

공식 문서가 정의하는 Agent의 7가지 능력 카탈로그. 각 능력은 별도 컴포넌트로 분해된다.

1. Interactive Communication

실시간 양방향 스트림. 상세는 AG-UI Event 참조.

2. Tool Usage

Frontend가 정의하고 Agent가 호출하는 표준 함수 인터페이스. 상세는 AG-UI Tools 참조. CopilotKit의 useCopilotAction 훅이 React에서 이 패턴을 단순화한 대표 사례.

3. State Management

구조화된 공유 상태를 STATE_SNAPSHOT / STATE_DELTA로 동기화. 상세는 AG-UI State Management 참조.

4. Multi-Agent Collaboration

Agent 간 작업 위임(handoff)·협업이 프로토콜 차원에서 가능하다. 단, 누가 라우팅을 결정하는가(=orchestration 주체)는 AG-UI가 강제하지 않는다. 프로토콜은 결과 이벤트 스트림 포맷만 표준화하고, orchestration은 사용 시나리오에 따라 4가지 패턴 중 하나가 담당한다.

Orchestration 패턴	주체	대표 사례
Supervisor Agent	감독 역할의 에이전트가 하위 에이전트를 라우팅	LangGraph supervisor, CrewAI manager
Workflow Engine	프레임워크가 정의한 그래프/DAG가 자동 전이	LangGraph state graph
Frontend Router	UI가 의도·도메인을 분석해 적절한 에이전트 선택	CopilotKit selfManagedAgents 분기
Peer-to-peer Handoff	에이전트가 직접 다른 에이전트로 위임	OpenAI Swarm 스타일 직접 handoff

3개 에이전트가 협업하는 Supervisor 패턴 예시:

sequenceDiagram
    autonumber
    participant UI as Frontend
    participant SUP as Supervisor Agent<br/>(orchestrator)
    participant CA as Coding Agent
    participant RA as Research Agent
    participant DOC as Doc Writer Agent

    UI->>SUP: "이 라이브러리 조사 후<br/>샘플 코드 짜고 문서화해줘"
    Note over SUP: 의도 분석 → 작업 분해<br/>실행 계획 수립
    SUP->>RA: 라이브러리 조사 위임 (state + messages)
    RA-->>SUP: 조사 결과 (state 갱신)
    SUP->>CA: 샘플 코드 작성 위임 (조사 결과 컨텍스트 포함)
    CA-->>SUP: 코드 + tool call 결과
    SUP->>DOC: 문서화 위임 (코드 + 조사 결과)
    DOC-->>UI: TEXT_MESSAGE 스트림
    Note over UI: 에이전트 전환은 투명<br/>대화·상태 연속성 유지

핵심 속성:

• 작업을 전문 에이전트로 위임 가능 (역할 분리)
• 상태와 컨텍스트가 에이전트 간 이전됨 (handoff)
• Orchestration 주체는 프로토콜 외부에서 결정 (AG-UI는 결과 스트림만 규정)
• Frontend는 에이전트 전환 중에도 일관된 경험 제공

5. Human-in-the-Loop

실행 중 사용자 개입(승인·수정·거절). 상세는 Human-in-the-Loop 참조.

6. Conversational Memory

대화 이력의 자동 누적·동기화. 상세는 AG-UI Messages 참조.

7. Metadata & Instrumentation

Agent가 자신의 내부 처리 과정에 대한 메타데이터를 emit해 Frontend가 투명성을 제공할 수 있게 한다.

종류	용도	표시 예시
Reasoning steps	사고 흐름 노출	”Thinking…” 패널
Performance metrics	실행 시간/토큰 사용량	디버그 오버레이
Source citations	참조 문헌·출처	인라인 각주
Confidence scores	응답별 확신도	색상 강도

sequenceDiagram
    autonumber
    participant Agent
    participant UI

    Agent-->>UI: REASONING_START
    Agent-->>UI: REASONING_CONTENT (사고 과정 텍스트)
    Agent-->>UI: REASONING_END
    Agent-->>UI: TEXT_MESSAGE_START
    Agent-->>UI: TEXT_MESSAGE_CONTENT (citation 메타 포함)
    Agent-->>UI: TEXT_MESSAGE_END
    Note over UI: 사고 과정과 최종 답변을<br/>분리해 렌더

Agent Configuration

Agent 인스턴스는 AgentConfig를 통해 정체성·초기 상태를 주입받는다.

interface AgentConfig {
  agentId?: string             // 에이전트 식별자
  description?: string         // 사람이 읽는 설명 (multi-agent 라우팅에 활용)
  threadId?: string            // 대화 세션 식별자
  initialMessages?: Message[]  // 초기 메시지 (system prompt 등)
  initialState?: State         // 초기 공유 상태
}
 
const agent = new HttpAgent({
  agentId: "my-agent-123",
  description: "A helpful assistant",
  threadId: "thread-456",
  initialMessages: [
    { id: "1", role: "system", content: "You are a helpful assistant." },
  ],
  initialState: { preferredLanguage: "English" },
})

설정 필드의 역할 분담:

필드	역할	비고
agentId	에이전트 식별	Multi-agent 라우팅 키
description	능력·역할 메타정보	Handoff 결정에 활용
threadId	대화 세션 식별	AbstractAgent에서 자동 생성도 가능
initialMessages	system prompt·few-shot	AG-UI Messages 누적의 시드
initialState	공유 상태 시드	AG-UI State Management 초기값

agent.clone()으로 상태를 복제한 분기 인스턴스를 만들 수 있어, 시뮬레이션·what-if 분석에도 활용 가능하다.

참고 문서

• AG-UI Agents
• AG-UI Architecture
• AbstractAgent
• AG-UI Event
• AG-UI Tools
• AG-UI State Management
• AG-UI Messages
• Human-in-the-Loop