AG-UI Tools

• AG-UI Tool은 Agent가 호출할 수 있고 Frontend가 정의·실행할 수 있는 함수 인터페이스
• LLM 추론 결과를 외부 액션·UI 조작·사용자 확인으로 연결하는 다리
• JSON Schema로 명세되고, 프로토콜 이벤트로 스트리밍되는 표준화된 호출 단위

해당 개념이 필요한 이유

• LLM 추론만으로는 외부 시스템 조작·사용자 입력 수집 불가
• Backend tool 중심 설계는 UI 상태·사용자 권한을 반영하기 어려움
• HITL(Human-in-the-Loop)을 자연스럽게 표현할 일급 메커니즘 필요
• 다양한 백엔드(LangGraph/CrewAI/Mastra…) 간 tool call 포맷 통일 필요

AS-IS

기존 LLM tool calling은 백엔드가 tool을 정의·실행해 UI/사용자 컨텍스트와 분리된다.

sequenceDiagram
    autonumber
    participant FE as Frontend
    participant BE as Backend(Agent)
    participant LLM
    participant Sys as External System
    BE->>LLM: tools 정의 (백엔드 소유)
    LLM->>BE: tool call
    BE->>Sys: tool 실행
    Sys-->>BE: result
    BE-->>FE: 최종 응답만 전달

TO-BE

AG-UI는 frontend tool과 backend tool을 혼재시킬 수 있고, 호출 과정이 표준 이벤트로 스트리밍된다. Frontend tool이 추가된 것이지 기존 backend tool이 사라진 것이 아니다. 프론트엔드는 AbstractAgent의 runAgent({ tools }) 진입점을 통해 매 실행마다 tool 셋을 주입한다.

sequenceDiagram
    autonumber
    participant FE as Frontend
    participant BE as Backend(Agent)
    participant LLM
    participant Sys as External System
    FE->>BE: runAgent({ tools, messages, state })
    Note over BE: tools = frontend tools + backend tools (혼재 가능)
    BE->>LLM: tools 주입
    LLM-->>BE: TOOL_CALL_* 이벤트 발생
    alt Frontend Tool인 경우
        BE-->>FE: TOOL_CALL_START / ARGS(delta) / END 스트리밍
        FE->>FE: tool 실행 (UI 다이얼로그·페이지 이동 등)
        FE->>BE: tool message (role: "tool")
    else Backend Tool인 경우
        BE->>Sys: tool 실행 (DB·외부 API 등)
        Sys-->>BE: result
        BE-->>FE: TOOL_CALL_* 이벤트 + 결과 (가시성 제공)
    end
    BE->>LLM: 결과 포함하여 응답 생성

Tool 구조

name, description, parameters 3필드 구성. parameters는 JSON Schema를 그대로 사용.

interface Tool {
  name: string
  description: string  // LLM이 "언제 쓸지" 판단
  parameters: {
    type: "object",
    properties: { ... },
    required: string[]
  }
}

이 구조는 OpenAI function calling, Anthropic tool use, MCP가 모두 쓰는 공용 형식이다. AG-UI는 이를 그대로 차용해 LLM 호환성과 상호운용성을 확보한다.

업계 표준과 AG-UI 고유 확장의 관계

AG-UI Tool은 새로운 형식을 발명한 것이 아니라, 업계 표준을 차용하면서 그 위에 두 가지 고유 확장을 얹은 구조다. 이 구분을 잡고 가면 이후 내용이 한 줄로 꿰어진다.

차용한 부분 (업계 표준)

• Tool 정의 모양 (name / description / parameters)
• JSON Schema 기반 파라미터 명세
• Tool result 메시지 형식 ([[AG-UI Messages|role: "tool"]])

AG-UI가 더한 부분 (고유 확장)

1. 소유권 모델 확장 — Tool을 정의하고 실행하는 권한이 backend 독점에서 frontend도 가능하도록 이동
2. 호출 과정의 프로토콜화 — Tool call을 표준 이벤트(TOOL_CALL_START → TOOL_CALL_ARGS × N → TOOL_CALL_END)로 정규화

“Frontend tool”이라는 새 종류가 추가된 것이 아니라, Tool을 누가 정의하고 누가 실행하는지의 권한 자체가 유연해진 것으로 이해해야 한다. 그리고 이 두 확장이 결합되어 후술할 HITL의 일급화로 이어진다.

확장 ①: 소유권 모델 — Frontend가 정의·실행할 수 있다

Frontend-defined Tools

Tool 정의 소유권이 frontend에 있다. runAgent({ tools })로 매 실행마다 다른 tool 셋을 주입할 수 있어, 같은 agent라도 화면·사용자 권한·앱 상태에 따라 다른 능력을 갖는다.

Frontend-executed Tools

정의가 frontend로 이동했기 때문에, 실행 위치도 자연스럽게 frontend가 가능해진다. 다이얼로그 표시·페이지 이동·localStorage 접근 같은 UI 액션이 그 자체로 tool이 되며, “사용자에게 묻기”가 별도 메커니즘 없이 일반 tool 호출과 동일하게 처리된다.

Frontend/Backend Tool 혼재

한 agent가 두 종류를 동시에 보유할 수 있다. Agent는 모두 같은 방식으로 호출하지만, 처리 주체는 tool이 정의된 위치가 결정한다. 보안이 필요한 작업은 backend, 사용자 상호작용이 필요한 작업은 frontend로 자연스럽게 갈린다.

확장 ②: Tool Call Lifecycle 표준화

OpenAI·Anthropic도 tool call을 스트리밍하지만 각자 다른 SSE 포맷을 사용한다. AG-UI는 이를 백엔드·프레임워크 무관한 표준 이벤트 3단계로 정규화한다.

sequenceDiagram
    autonumber
    participant Agent
    participant FE as Frontend
    Agent-->>FE: TOOL_CALL_START { toolCallId, toolCallName }
    Agent-->>FE: TOOL_CALL_ARGS { delta: '{"act' }
    Agent-->>FE: TOOL_CALL_ARGS { delta: 'ion":"Depl' }
    Agent-->>FE: TOOL_CALL_ARGS { delta: 'oy"}' }
    Agent-->>FE: TOOL_CALL_END { toolCallId }
    Note over FE: delta 누적 → 완전한 JSON 복원
    FE->>FE: tool 실행
    FE->>Agent: tool message { role: "tool", toolCallId, content }

delta는 인자 JSON의 partial 문자열이며, frontend가 누적해 완전한 인자를 복원한다. toolCallId로 호출과 결과를 매칭하므로, 여러 tool이 병렬로 호출되어도 응답 매핑이 어긋나지 않는다.

Tool Result 메시지

Tool 실행 결과는 대화 히스토리에 role: "tool" 메시지로 추가된다. 이 형식은 OpenAI 컨벤션을 그대로 차용한 표준 부분이다.

{
  id: "result-789",
  role: "tool",
  content: "approved",      // 결과는 항상 string
  toolCallId: "tool-123"    // 원래 호출과 매칭
}

이 메시지가 다음 LLM 호출 시 컨텍스트에 포함되어, agent가 결과를 참조하며 응답을 이어간다.

두 확장의 결과: HITL이 일급 시민이 된다

소유권 모델 확장과 lifecycle 표준화가 결합되면, HITL(Human-in-the-Loop)이 프로토콜의 일급 시민(first-class citizen) 으로 표현된다.

일급 시민이란? 프로그래밍 언어 이론 용어로, 어떤 요소가 다른 요소들과 동등한 권리·취급을 받을 때 “일급(first-class)“이라고 한다. 예를 들어 JavaScript에서 함수는 변수에 담고 인자로 전달하고 반환할 수 있어 일급 시민이다. AG-UI에서 “HITL이 일급 시민”이라는 말은, 사용자에게 묻는 작업이 별도의 우회나 확장 메커니즘 없이 일반 tool 호출과 완전히 동일한 방식으로 작동한다는 뜻이다.

다른 프로토콜에서는 “사용자에게 묻기”를 위해 별도 설계가 필요하지만, AG-UI에서는 frontend tool 하나 정의하면 끝난다. 흐름은 단순하다:

1. Agent: 중요 결정 직면
2. Agent → confirmAction tool 호출 (TOOL_CALL_* 이벤트로 스트리밍)
3. Frontend: 다이얼로그 표시 (tool 실행)
4. User: 승인/거부
5. Frontend → Agent: tool result 전달
6. Agent: 사용자 의사 반영하여 응답 이어감

활용 사례:

• Approval workflows: AI 제안 → 사람 승인
• Data verification: AI 생성 데이터 검증
• Collaborative decision-making: AI·사람 협업 의사결정
• Supervised learning: 피드백 수집

복잡한 구조화 데이터를 사람이 편집하는 시나리오라면, Tool만으로는 부족하고 AG-UI State Management의 양방향 state 채널과 결합해 사용한다. Tool은 “결정 트리거”, State는 “공동 편집 데이터”를 담당하는 보완 관계다.

일반 AI Tool Calling과의 차이 요약

지금까지의 내용을 한 표로 정리하면 다음과 같다.

항목	일반 (OpenAI/Anthropic)	AG-UI
Tool 정의 모양	JSON Schema	JSON Schema (동일)
Tool result 형식	role: "tool" 메시지	role: "tool" 메시지 (동일)
Tool 정의 위치	Backend	Frontend 또는 Backend
Tool 실행 위치	Backend	Frontend 또는 Backend
스트리밍 포맷	벤더별 SSE	표준 TOOL_CALL_ 이벤트*
백엔드 통일성	벤더 종속	프레임워크 무관
HITL 표현	별도 설계 필요	일급 시민

위쪽 두 행이 “차용한 표준”이고, 아래쪽이 “AG-UI 고유 확장”에 해당한다.

자주 헷갈리는 포인트

• JSON Schema는 AG-UI가 만든 게 아니라 차용한 업계 표준이다
• Tool result content는 항상 string — 객체가 아니라 직렬화된 문자열로 전달
• parentMessageId는 optional, tool call이 어떤 assistant 메시지에서 시작됐는지 참조
• “Frontend tool”이라는 별도 종류가 있는 게 아니라, Tool의 정의·실행 권한 자체가 유연해진 것이다
• Frontend·Backend tool 구분은 정의 시점이 아닌 실행 위치 기준이다

관련 개념

• AG-UI Event — TOOL_CALL_* 이벤트의 전체 카탈로그와 lifecycle 패턴
• AG-UI Messages — role: "tool" 메시지의 tagged-union 구조와 누적 방식
• AG-UI State Management — Tool과 함께 HITL 워크플로우를 구성하는 양방향 state 채널
• AbstractAgent — runAgent({ tools, ... }) 진입점과 RunAgentInput 자동 조립
• delta — TOOL_CALL_ARGS.delta 누적 방식의 일반 개념
• CopilotKit — useCopilotAction으로 Frontend tool을 React 컴포넌트와 함께 정의
• MCP Server — 동일한 JSON Schema 기반이지만 Agent ↔ 외부 도구 영역에 집중
• Human-in-the-Loop — Frontend tool이 자연스럽게 표현하는 협업 패턴

참고 문서

• AG-UI Tools Concept
• JSON Schema
• CopilotKit useCopilotAction