AG-UI Capabilities

• **Capabilities(역량 선언)**는 AG-UI 프로토콜에서 에이전트가 런타임에 자신이 지원하는 기능을 클라이언트에 노출하는 발견(discovery) 메커니즘
• AbstractAgent의 getCapabilities()가 반환하는 타입화된 능력 스냅샷
• 협상(negotiation)이 아닌 단방향 선언 방식의 인터페이스
• 명시되지 않은 필드는 “미선언(unknown)“으로 해석되는 부분 선언 가능한 옵셔널 구조
• 도구 등록·해제처럼 상태가 변하면 다음 호출에 즉시 반영되는 라이브 스냅샷

해당 개념이 필요한 이유

• 클라이언트가 에이전트 기능을 추측하거나 하드코딩하지 않고도 UI/플로우를 적응적으로 구성할 수 있어야 함
• 도구·추론·멀티모달·HITL 등 이질적인 기능군을 단일 표준 스키마로 노출할 통일된 창구가 필요
• 런타임에 도구가 추가/제거되거나 모드가 바뀔 때 동적으로 반영될 수 있어야 함
• 에이전트 마켓플레이스·라우팅 로직에서 에이전트 비교·선택의 객관적 근거가 필요

AS-IS

sequenceDiagram
    autonumber
    participant Client
    participant Agent
    Client->>Client: "이 에이전트가 tools 지원하나?" 추측
    Client->>Agent: run() with tool calls
    Agent-->>Client: 런타임 오류 또는 무시됨
    Note over Client: 하드코딩된 가정에 의존<br/>실패 후에야 미지원 발견

TO-BE

sequenceDiagram
    autonumber
    participant Client
    participant Agent
    Client->>Agent: getCapabilities()
    Agent-->>Client: AgentCapabilities snapshot
    Client->>Client: tools.supported, reasoning.supported 등 검사
    Client->>Client: 지원 기능만 UI에 노출 (Adaptive UI)
    Client->>Agent: run() — 검증된 기능만 사용
    Agent-->>Client: 정상 응답

핵심 원칙 4가지

원칙 1. Discovery only — 발견이지 협상이 아니다

에이전트가 자신이 할 수 있는 것을 선언할 뿐이고, 클라이언트가 능력을 요청·교섭하지 않는다. 단방향이다.

원칙 2. Dynamic — 호출 시점의 라이브 상태

getCapabilities()는 캐시된 정적 메타데이터가 아니라 호출 시점의 현재 상태다. 도구를 등록하면 다음 호출의 tools.items에 곧바로 반영된다.

let caps = await agent.getCapabilities()
console.log(caps.tools?.items?.length) // 5
 
agent.registerTool(newTool)
 
caps = await agent.getCapabilities()
console.log(caps.tools?.items?.length) // 6

원칙 3. Optional — 구현 자체가 옵션

구현하지 않은 에이전트는 undefined를 반환한다. 따라서 클라이언트는 항상 await agent.getCapabilities?.() 형태의 옵셔널 체이닝으로 호출해야 한다.

원칙 4. Absent = unknown — 부재는 미지원이 아니라 미선언

tools 필드를 생략한 것이 “도구 미지원”을 뜻하지는 않는다. 선언하지 않았음을 의미할 뿐이다. 명시적으로 차단하려면 supported: false를 써야 한다.

AgentCapabilities 인터페이스 — 11개 카테고리

카테고리	역할	대표 필드
identity	에이전트 메타데이터	name, type, version, provider, documentationUrl
transport	전송 방식 (AG-UI Serialization)	streaming(SSE), websocket, httpBinary(protobuf), pushNotifications, resumable
tools	도구 호출	supported, items[], parallelCalls, clientProvided
output	출력 포맷	structuredOutput, supportedMimeTypes
state	상태/메모리	snapshots, deltas, memory, persistentState
multiAgent	다중 에이전트 협력	supported, delegation, handoffs, subAgents
reasoning	추론/사고 노출	supported, streaming, encrypted
multimodal	입출력 모달리티	input.{image,audio,video,pdf,file}, output.{image,audio}
execution	실행 제어	codeExecution, sandboxed, maxIterations, maxExecutionTime
humanInTheLoop	인간 개입	supported, approvals, interventions, feedback
custom	표준 외 확장	Record<string, unknown> (escape hatch)

interface AgentCapabilities {
  identity?: IdentityCapabilities
  transport?: TransportCapabilities
  tools?: ToolsCapabilities
  output?: OutputCapabilities
  state?: StateCapabilities
  multiAgent?: MultiAgentCapabilities
  reasoning?: ReasoningCapabilities
  multimodal?: MultimodalCapabilities
  execution?: ExecutionCapabilities
  humanInTheLoop?: HumanInTheLoopCapabilities
  custom?: Record<string, unknown>
}

tools.items vs RunAgentInput.tools

tools.items는 에이전트가 내장한 도구, RunAgentInput.tools는 클라이언트가 런타임에 주입하는 도구다. 둘은 서로 다른 출처의 도구 목록이며, tools.clientProvided: true는 후자를 받아들일 수 있다는 신호다.

state — 스냅샷과 델타의 구분

AG-UI State Management에서 다루는 STATE_SNAPSHOT(전체 교체)과 STATE_DELTA(JSON Patch 기반 부분 갱신, delta) 중 어떤 것을 이벤트로 발행하는지를 각각 snapshots/deltas 플래그로 선언한다. persistentState는 같은 thread 내에서 run 간 상태가 유지되는지 여부다.

reasoning.encrypted — 무엇을 의미하나

encrypted: true는 zero-data-retention 모드로, 클라이언트는 읽을 수 있는 추론 텍스트 대신 불투명한 encryptedValue 필드를 받는다. UI에 추론 패널을 그대로 노출하면 안 된다는 신호다.

구현 예시

커스텀 에이전트에서 선언

import { AbstractAgent, AgentCapabilities } from "@ag-ui/client"
 
class MyAgent extends AbstractAgent {
  async getCapabilities(): Promise<AgentCapabilities> {
    return {
      identity: {
        name: "my-agent",
        description: "A custom agent with tool support",
        version: "1.0.0",
      },
      transport: {
        streaming: true,
      },
      tools: {
        supported: true,
        items: this.getRegisteredTools(),
        clientProvided: true,
      },
      state: {
        snapshots: true,
        deltas: true,
      },
    }
  }
}

선언하지 않은 카테고리(reasoning, multimodal, execution 등)는 자동으로 “미선언” 상태가 된다.

클라이언트 활용 패턴 3가지

패턴 1. Adaptive UI — UI 컴포넌트 가시성 제어

const caps = await agent.getCapabilities?.()
 
if (caps?.reasoning?.supported) showReasoningPanel()
if (caps?.multiAgent?.subAgents?.length) showSubAgentSelector(caps.multiAgent.subAgents)
if (caps?.humanInTheLoop?.approvals) enableApprovalWorkflow()

패턴 2. Feature Gating — 미지원 기능 사전 차단

const canUseStructuredOutput = caps?.output?.structuredOutput ?? false
const canStream = caps?.transport?.streaming ?? false

런타임 실패 대신 사전에 비활성화하여 사용자 경험을 일관되게 유지한다. ?? false로 미선언 케이스를 안전한 쪽(미지원)으로 좁히는 것이 관용 패턴이다.

패턴 3. Custom Capabilities — 통합별 확장

const rateLimit = caps?.custom?.rateLimit as
  | { maxRequestsPerMinute: number }
  | undefined
 
if (rateLimit) configureThrottling(rateLimit.maxRequestsPerMinute)

표준 카테고리에 없는 정보(레이트 리밋, 비용 단가, 벤더 식별자 등)는 custom으로 노출한다. 타입은 통합별 합의에 의존하므로 클라이언트 측에서 단언(assert)이 필요하다.

참고 문서

• AG-UI Capabilities
• AG-UI
• AbstractAgent
• AG-UI Agents
• AG-UI Event
• AG-UI State Management
• AG-UI Tools
• AG-UI Serialization
• SSE (Server-Sent Events)
• Protocol Buffers
• delta