useCapabilities.mdx

title	useCapabilities
description	React hook for reading an agent's declared capabilities

Overview

useCapabilities returns the AG-UI AgentCapabilities declared by an agent. Capabilities describe what an agent supports -- tool calling, streaming, multi-agent coordination, human-in-the-loop, and more.

Capabilities are populated from the runtime /info response at connection time. The value is undefined until the runtime handshake completes or if the agent doesn't declare capabilities.

Signature

import { useCapabilities } from "@copilotkit/react-core/v2";

function useCapabilities(agentId?: string): AgentCapabilities | undefined

Parameters

ID of the agent whose capabilities to read. If omitted, uses the default agent.

Return Value

The agent's capability declaration, or `undefined` if the agent hasn't reported capabilities yet (e.g., the runtime handshake is still in progress) or doesn't implement `getCapabilities()`.

When defined, the object contains these optional categories:

Agent metadata: `name`, `type` (framework), `description`, `version`, `provider`, `documentationUrl`, `metadata`. Supported transports: `streaming`, `websocket`, `httpBinary`, `pushNotifications`, `resumable`. Tool support: `supported`, `items`, `parallelCalls`, `clientProvided`. Output formats: `structuredOutput`, `supportedMimeTypes`. State management: `snapshots`, `deltas`, `memory`, `persistentState`. Multi-agent coordination: `supported`, `delegation`, `handoffs`, `subAgents`. Reasoning/thinking visibility: `supported`, `streaming`, `encrypted`. Multimodal input/output: `input` and `output` sub-objects for images, audio, video, PDF, and file support. Code execution: `codeExecution`, `sandboxed`, `maxIterations`, `maxExecutionTime`. Human-in-the-loop: `supported`, `approvals`, `interventions`, `feedback`. Arbitrary key-value pairs for integration-specific capabilities.

Usage

Conditionally render UI based on capabilities

import { useCapabilities } from "@copilotkit/react-core/v2";

function ToolPanel() {
  const capabilities = useCapabilities();

  if (!capabilities?.tools?.supported) {
    return null; // Agent doesn't support tools — hide the panel
  }

  return (
    <div>
      <h3>Tools</h3>
      {capabilities.tools.clientProvided && (
        <p>This agent accepts client-provided tools.</p>
      )}
    </div>
  );
}

Read capabilities for a specific agent

import { useCapabilities } from "@copilotkit/react-core/v2";

function AgentInfo({ agentId }: { agentId: string }) {
  const capabilities = useCapabilities(agentId);

  if (!capabilities) {
    return <p>Loading capabilities…</p>;
  }

  return (
    <ul>
      <li>Streaming: {capabilities.transport?.streaming ? "Yes" : "No"}</li>
      <li>Tools: {capabilities.tools?.supported ? "Yes" : "No"}</li>
      <li>Human-in-the-loop: {capabilities.humanInTheLoop?.supported ? "Yes" : "No"}</li>
    </ul>
  );
}

Behavior

• Synchronous read -- The hook reads capabilities directly from the agent instance. There is no separate loading state or async fetch -- the value is undefined until the runtime /info handshake populates it, then becomes defined.
• Re-renders -- The hook calls useAgent() internally, so the component re-renders on agent state, message, and run-status changes (the default updates set). If you only need capabilities and want fewer re-renders, read agent.capabilities directly via useAgent({ updates: [] }).
• Stable reference -- The capabilities object reference only changes when the agent reconnects or the runtime response changes. It does not change on every render.

Related

• useAgent -- access the full agent instance (capabilities are a property of the agent)
• AG-UI Protocol -- the protocol that defines the capabilities schema