useCapabilities

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#

agentIdstring

Default: ""default""

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

Return Value#

capabilitiesAgentCapabilities | undefined

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:

identityIdentityCapabilities

Agent metadata: name, type (framework), description, version, provider, documentationUrl, metadata.

transportTransportCapabilities

Supported transports: streaming, websocket, httpBinary, pushNotifications, resumable.

toolsToolsCapabilities

Tool support: supported, items, parallelCalls, clientProvided.

outputOutputCapabilities

Output formats: structuredOutput, supportedMimeTypes.

stateStateCapabilities

State management: snapshots, deltas, memory, persistentState.

multiAgentMultiAgentCapabilities

Multi-agent coordination: supported, delegation, handoffs, subAgents.

reasoningReasoningCapabilities

Reasoning/thinking visibility: supported, streaming, encrypted.

multimodalMultimodalCapabilities

Multimodal input/output: input and output sub-objects for images, audio, video, PDF, and file support.

executionExecutionCapabilities

Code execution: codeExecution, sandboxed, maxIterations, maxExecutionTime.

humanInTheLoopHumanInTheLoopCapabilities

Human-in-the-loop: supported, approvals, interventions, feedback.

customRecord<string, unknown>

Arbitrary key-value pairs for integration-specific capabilities.

Usage#

Conditionally render UI based on capabilities#

ToolPanel.tsx

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#

AgentInfo.tsx

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.

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