도구
도구 (Tools)
도구가 무엇이고, 어떻게 인간이 개입하는(human-in-the-loop) AI 워크플로를 가능하게 하는지 다루는 페이지예요. AG-UI에서는 백엔드 에이전트가 정의한 도구와 클라이언트가 런타임에 제공하는 도구를 구분합니다.
출처: 문서
본문
도구는 AG-UI 프로토콜의 근본적인 개념으로, AI 에이전트가 외부 시스템과 상호작용하고 인간의 판단을 자신의 워크플로에 통합할 수 있게 해 줍니다.
AG-UI는 에이전트 백엔드가 정의하는 도구와 클라이언트가 런타임에 제공하는 도구를 구분해요. 백엔드 정의 도구는 백엔드 에이전트나 프레임워크 구성에 남아 있습니다. 클라이언트 정의 도구는 RunAgentInput.tools로 전달되어, 에이전트가 UI 액션이나 승인, 사용자 매개 워크플로 같은 애플리케이션 특화 프런트엔드 동작을 다시 호출(call back)할 수 있게 합니다.
도구란 무엇인가 (What Are Tools?)
AG-UI에서 도구는 에이전트가 다음을 위해 호출할 수 있는 함수입니다:
- 특정 정보 요청
- 외부 시스템에서 액션 수행
- 인간 입력이나 확인 요청
- 특화된 능력에 접근
도구는 AI 추론과 실세계 액션 사이의 간극을 메워, 에이전트가 대화만으로는 불가능한 작업을 완수할 수 있게 해 줍니다.
도구 구조 (Tool Structure)
도구는 이름, 목적, 기대 파라미터를 정의하는 일관된 구조를 따릅니다:
interface Tool {
name: string // Unique identifier for the tool
description: string // Human-readable explanation of what the tool does
parameters: {
// JSON Schema defining the tool's parameters
type: "object"
properties: {
// Tool-specific parameters
}
required: string[] // Array of required parameter names
}
}
parameters 필드는 JSON Schema를 사용해 도구가 받는 인수의 구조를 정의합니다. 이 스키마는 에이전트(유효한 도구 호출을 생성하기 위해)와 프런트엔드(도구 인수를 검증·분석하기 위해) 양쪽이 사용해요.
프런트엔드 정의 도구 (Frontend-Defined Tools)
AG-UI 도구 시스템의 핵심 측면은 도구가 프런트엔드에서 정의되고 실행 중에 에이전트에게 전달된다는 점입니다:
// Define tools in the frontend
const userConfirmationTool = {
name: "confirmAction",
description: "Ask the user to confirm a specific action before proceeding",
parameters: {
type: "object",
properties: {
action: {
type: "string",
description: "The action that needs user confirmation",
},
importance: {
type: "string",
enum: ["low", "medium", "high", "critical"],
description: "The importance level of the action",
},
},
required: ["action"],
},
}
// Pass tools to the agent during execution
agent.runAgent({
tools: [userConfirmationTool],
// Other parameters...
})
이 접근 방식에는 여러 장점이 있습니다:
- 프런트엔드 통제: 프런트엔드가 에이전트에게 어떤 능력을 제공할지 결정합니다
- 동적 능력: 사용자 권한, 컨텍스트, 애플리케이션 상태에 따라 도구를 추가·제거할 수 있어요
- 관심사 분리: 프런트엔드가 도구 구현을 담당하는 동안 에이전트는 추론에 집중합니다
- 보안: 민감한 작업은 에이전트가 아니라 애플리케이션이 통제해요
RunAgentInput.tools는 이러한 클라이언트 제공 도구 전용입니다. 백엔드 에이전트가 사용할 수 있는 모든 도구를 담기 위한 것이 아니에요. 통합에 백엔드 도구가 있다면, 클라이언트에서 그 스키마를 보내는 대신 백엔드 프레임워크에 정의하거나 에이전트 능력으로 광고하세요.
도구 호출 수명주기 (Tool Call Lifecycle)
에이전트가 도구를 사용해야 할 때 표준화된 이벤트 시퀀스를 따릅니다:
-
ToolCallStart: 고유 ID와 도구 이름으로 도구 호출의 시작을 나타냅니다
{ type: EventType.TOOL_CALL_START, toolCallId: "tool-123", toolCallName: "confirmAction", parentMessageId: "msg-456" // Optional reference to a message } -
ToolCallArgs: 생성되면서 도구 인수를 스트리밍합니다
{ type: EventType.TOOL_CALL_ARGS, toolCallId: "tool-123", delta: '{"act' // Partial JSON being streamed }{ type: EventType.TOOL_CALL_ARGS, toolCallId: "tool-123", delta: 'ion":"Depl' // More JSON being streamed }{ type: EventType.TOOL_CALL_ARGS, toolCallId: "tool-123", delta: 'oy the application to production"}' // Final JSON fragment } -
ToolCallEnd: 도구 호출의 완료를 표시합니다
{ type: EventType.TOOL_CALL_END, toolCallId: "tool-123" }
프런트엔드는 이 delta를 누적해 완전한 도구 호출 인수를 구성합니다. 도구 호출이 완료되면 프런트엔드는 도구를 실행하고 결과를 에이전트에 다시 제공할 수 있어요.
도구 호출 메타데이터 (Tool call metadata)
이 세 이벤트 모두 metadata 객체를 담을 수 있고, 그것은 이를 소유한 어시스턴트 메시지가 아니라 도구 호출 자체에 누적됩니다:
assistantMessage.toolCalls[0].metadata
// { provider: "anthropic", latencyMs: 84 }
이는 의도적인 설계예요. 하나의 어시스턴트 메시지가 여러 도구 호출을 소유할 수 있으므로, 그 메타데이터를 부모에 접으면 결과가 호출들이 섞인 순서에 따라 달라지게 됩니다. 각 도구 호출이 자신만의 것을 갖게 해서 모호함을 없앱니다.
ToolCallResult는 다릅니다 — 그것은 도구 메시지를 만들기 때문에, 그 메타데이터는 다른 메시지 생성 이벤트처럼 그 메시지에 병합됩니다. 메타데이터 (Metadata)를 참고하세요.
도구 결과 (Tool Results)
도구가 실행된 후, 그 결과는 "도구 메시지"로 에이전트에게 다시 보내집니다:
{
id: "result-789",
role: "tool",
content: "true", // Tool result as a string
toolCallId: "tool-123" // References the original tool call
}
이 메시지는 대화 내역의 일부가 되어, 에이전트가 이후 응답에서 도구의 결과를 참조하고 통합할 수 있게 합니다.
도구가 성공하지 못했다면 error에 실패 메시지를 설정하세요:
{
id: "result-789",
role: "tool",
content: "Deployment blocked: the production environment is locked",
toolCallId: "tool-123",
error: "the production environment is locked" // Marks this result as a failure
}
error는 프로토콜이 클라이언트 측 도구 실패를 표현하는 방법이에요. 그것이 없으면, 실패한 도구는 성공한 것과 구별할 수 없습니다 — 프런트엔드가 content에 넣은 것이 에이전트가 의존할 수 있는 전부니까요. 전체 ToolMessage 형태는 메시지 (Messages)를 참고하세요.
인간이 개입하는 워크플로 (Human-in-the-Loop Workflows)
AG-UI 도구 시스템은 인간이 개입하는 워크플로를 구현하는 데 특히 강력해요. 인간 입력이나 확인을 요청하는 도구를 정의함으로써, 개발자는 자율 작동과 인간 판단을 매끄럽게 혼합한 AI 경험을 만들 수 있습니다.
예를 들면:
- 에이전트가 중요한 결정을 내려야 합니다
- 에이전트가 결정에 대한 세부 정보와 함께
confirmAction도구를 호출합니다 - 프런트엔드가 사용자에게 확인 다이얼로그를 표시합니다
- 사용자가 입력을 제공합니다
- 프런트엔드가 사용자의 결정을 에이전트에게 다시 보냅니다
- 에이전트는 사용자의 선택을 인지하고 계속 처리합니다
이 패턴은 다음과 같은 사용 사례를 가능하게 합니다:
- 승인 워크플로: AI가 인간 승인이 필요한 액션을 제안합니다
- 데이터 검증: 인간이 AI 생성 데이터를 검증하거나 수정합니다
- 협력적 의사결정: AI와 인간이 복잡한 문제를 함께 해결합니다
- 감독 학습: 인간 피드백이 미래 AI 결정을 개선합니다
CopilotKit 통합 (CopilotKit Integration)
CopilotKit은 React 애플리케이션에서 AG-UI 도구를 간단하게 다룰 수 있는 useCopilotAction 훅을 제공합니다:
import { useCopilotAction } from "@copilotkit/react-core"
// Define a tool for user confirmation
useCopilotAction({
name: "confirmAction",
description: "Ask the user to confirm an action",
parameters: {
type: "object",
properties: {
action: {
type: "string",
description: "The action to confirm",
},
},
required: ["action"],
},
handler: async ({ action }) => {
// Show a confirmation dialog
const confirmed = await showConfirmDialog(action)
return confirmed ? "approved" : "rejected"
},
})
이 접근 방식 덕분에 React 컴포넌트와 통합되는 도구를 정의하고, 도구 실행 로직을 깔끔하고 선언적인 방식으로 처리하기 쉽습니다.
도구 예시 (Tool Examples)
여기 AG-UI 애플리케이션에서 쓰이는 흔한 도구 유형 몇 가지를 소개할게요.
사용자 확인 (User Confirmation)
{
name: "confirmAction",
description: "Ask the user to confirm an action",
parameters: {
type: "object",
properties: {
action: {
type: "string",
description: "The action to confirm"
},
importance: {
type: "string",
enum: ["low", "medium", "high", "critical"],
description: "The importance level"
}
},
required: ["action"]
}
}
데이터 검색 (Data Retrieval)
{
name: "fetchUserData",
description: "Retrieve data about a specific user",
parameters: {
type: "object",
properties: {
userId: {
type: "string",
description: "ID of the user"
},
fields: {
type: "array",
items: {
type: "string"
},
description: "Fields to retrieve"
}
},
required: ["userId"]
}
}
사용자 인터페이스 제어 (User Interface Control)
{
name: "navigateTo",
description: "Navigate to a different page or view",
parameters: {
type: "object",
properties: {
destination: {
type: "string",
description: "Destination page or view"
},
params: {
type: "object",
description: "Optional parameters for the navigation"
}
},
required: ["destination"]
}
}
콘텐츠 생성 (Content Generation)
{
name: "generateImage",
description: "Generate an image based on a description",
parameters: {
type: "object",
properties: {
prompt: {
type: "string",
description: "Description of the image to generate"
},
style: {
type: "string",
description: "Visual style for the image"
},
dimensions: {
type: "object",
properties: {
width: { type: "number" },
height: { type: "number" }
},
description: "Dimensions of the image"
}
},
required: ["prompt"]
}
}
모범 사례 (Best Practices)
AG-UI용 도구를 설계할 때:
- 명확한 명명: 설명적이고 액션 지향적인 이름을 사용하세요
- 상세한 설명: 에이전트가 언제·어떻게 도구를 쓸지 이해하도록 철저한 설명을 포함하세요
- 구조화된 파라미터: 설명적인 필드 이름과 제약을 가진 정밀한 파라미터 스키마를 정의하세요
- 필수 필드: 정말 필요한 파라미터만 required로 표시하세요
- 오류 처리: 도구 실행 코드에 견고한 오류 처리를 구현하세요
- 사용자 경험: 인간 의사결정을 위한 적절한 맥락을 제공하는 도구 UI를 설계하세요
결론 (Conclusion)
AG-UI의 도구는 AI 추론과 실세계 액션 사이의 간극을 메워, AI와 인간 지능의 강점을 결합한 정교한 워크플로를 가능하게 해요. 프런트엔드에서 도구를 정의하고 에이전트에게 전달함으로써, 개발자는 AI와 인간이 효율적으로 협력하는 대화형 경험을 만들 수 있습니다.
도구 시스템은 AI가 액션을 제안하되 중요한 결정은 인간에게 맡기는 인간-개입 워크플로를 구현하는 데 특히 강력합니다. 이는 자동화와 인간 판단 사이의 균형을 맞춰, 강력하면서도 신뢰할 수 있는 AI 경험을 만들어 줍니다.
더 알아보기 (Learn more)
- 도구 호출 (1.0 스펙) — 도구 호출 이벤트의 스펙 정의
- 메타데이터 (Metadata) — 도구 호출에 붙는 메타데이터
- 핵심 아키텍처 — AG-UI의 이벤트 주도 구조