Skip to content

useCapabilities.mdx

Latest commit

 

History

History
140 lines (103 loc) · 5.56 KB

useCapabilities.mdx

File metadata and controls

140 lines (103 loc) · 5.56 KB
Raw
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.

Re-exported from `@copilotkit/react-core/v2`. It is identical to the [React (V2) `useCapabilities`](/reference/v2/hooks/useCapabilities); only the import path differs.

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-native";

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-native";
import { Text, View } from "react-native";

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

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

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

Read capabilities for a specific agent

import { useCapabilities } from "@copilotkit/react-native";
import { Text, View } from "react-native";

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

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

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

Behavior

  • Synchronous read: The hook reads capabilities directly from the agent instance. There is no separate loading state or async fetch. The value stays 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
  • React (V2) reference: the web useCapabilities this hook mirrors