Tool Call Rendering

Render your agent's tool calls with your own React Native components.

What is this?

Tools are how an LLM invokes predefined, typically deterministic functions. Tool rendering lets you decide how each of those tool calls appears in the chat. You register a React Native component that draws a card for the call: its arguments, a live status, and the result once it arrives. This is the generative UI variant CopilotKit calls tool rendering.

When should I use this?

Render tool calls when you want to:

  • Show users which tools the agent is calling, and with what arguments
  • Display live progress while a tool runs
  • Render rich results once a tool completes
  • Give tool-heavy agents a clear, on-brand chat

Default rendering on React Native

The React package has useDefaultRenderTool, which draws a built-in status card for every tool call. Its card uses web elements, so @copilotkit/react-native does not export it.

Without a renderer, the rendered CopilotChat from /components shows a short "Called: tool_name" line for each call. A chat you build yourself shows nothing, unless you render a fallback. To draw every call your way, register a catch-all.

Custom catch-all

useRenderTool with name: "*" registers one renderer for every tool call that has no renderer of its own:

src/ToolCallCard.tsx
import { ActivityIndicator, Text, View } from "react-native";
import { useRenderTool } from "@copilotkit/react-native/headless";

export function useToolCallCards() {
  useRenderTool(
    {
      name: "*",
      render: ({ name, status, result }) => (
        <View style={{ padding: 10, borderRadius: 10, backgroundColor: "#f4f4f8", gap: 4 }}>
          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
            {status === "complete" ? <Text>✓</Text> : <ActivityIndicator size="small" />}
            <Text style={{ fontWeight: "600" }}>{name}</Text>
          </View>
          {status === "complete" ? <Text numberOfLines={3}>{result}</Text> : null}
        </View>
      ),
    },
    [],
  );
}

Call useToolCallCards() once, in a component under CopilotKitProvider. Every tool call without a named renderer now draws this card.

Per-tool renderers

The most expressive path is one renderer per tool name. Each renderer receives the tool's parsed parameters, a live status, and, once the agent returns, the result. The renderer must return a React Native element or null.

src/WeatherCard.tsx
import { Text, View } from "react-native";
import { useRenderTool } from "@copilotkit/react-native/headless";
import { z } from "zod";

export function useWeatherCard() {
  useRenderTool(
    {
      name: "get_weather", // must match the tool name the agent exposes
      parameters: z.object({ location: z.string() }),
      render: ({ parameters, status, result }) => {
        if (status !== "complete") {
          return <Text>Checking the weather in {parameters.location ?? "..."}</Text>;
        }
        const weather = parseWeather(result);
        return (
          <View style={{ padding: 12, borderRadius: 12, backgroundColor: "#eef4ff" }}>
            <Text style={{ fontWeight: "600" }}>{parameters.location}</Text>
            <Text>{weather ? `${weather.temperature}°` : result}</Text>
          </View>
        );
      },
    },
    [],
  );
}

// The result arrives as a string. Parse it when your tool returns JSON.
function parseWeather(result: string): { temperature: number } | null {
  try {
    return JSON.parse(result);
  } catch {
    return null;
  }
}

Named renderers and a catch-all work together: the named one claims its tool, and the "*" renderer handles every other call.

The name you pass to useRenderTool must match the tool name the agent exposes. That is how the chat matches the call to your component.

Tool inputs and results are separate

In useRenderTool, parameters holds the inputs the agent sent to the tool. It does not turn into the tool's return value when status becomes "complete". The output arrives separately as result, a string. For a tool that returns JSON, parse that string before you read its fields.

While the arguments stream, status is "inProgress" and parameters can be partial. Read required fields after the status moves to "executing" or "complete".

Your own tool or someone else's

useRenderTool registers a renderer only. It takes no description and no handler, so the model never sees it as a tool. Use it for a tool that runs on your agent's backend, or as the "*" fallback. For a tool your app owns and runs on the device, pass render to useFrontendTool instead. Both write to the same renderer registry. If your code passes description or handler to useRenderTool, see Migrating from the old React Native useRenderTool.

Where the cards render

The rendered CopilotChat and CopilotModal from /components draw tool calls with your renderers. In your own chat, useRenderToolCall() returns a function that renders one tool call. It returns ReactElement | null, which is what a FlatList renderItem needs. See Headless UI.

The backend tool definition

The frontend renderer only sees what the agent sends. The matching backend must expose a tool named get_weather and return structured data. The renderer with the same name then draws the card. The React Native renderer does not create or run that backend tool.

Register the tool in backend_tools on the router. The router runs backend tools on the server and streams their calls and results to the chat, where your renderer draws them. Tools in frontend_tools are handed to the browser instead.

agent.py
from llama_index.llms.openai import OpenAI
from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router


def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny and 70 degrees."


agentic_chat_router = get_ag_ui_workflow_router(
    llm=OpenAI(model="gpt-6-luna"),
    backend_tools=[get_weather],
    system_prompt="You are a helpful AI assistant with access to various tools and capabilities.",
)
agent.py
import asyncio
import json
import os
from typing import Annotated

from agents._openai_models import OpenAI
from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router

from agents.hitl_in_chat_agent import FixedAGUIChatWorkflow

# Import shared tool implementations
from tools import (
    get_weather_impl,
    query_data_impl,
    manage_sales_todos_impl,
    get_sales_todos_impl,
    schedule_meeting_impl,
    search_flights_impl,
    build_a2ui_operations_from_tool_call,
)


# --- Frontend tools (executed client-side, agent just returns a confirmation) ---


def change_background(
    background: Annotated[str, "CSS background value. Prefer gradients."],
) -> str:
    """Change the background color/gradient of the chat area."""
    return f"Background changed to {background}"


def generate_haiku(
    japanese: Annotated[list[str], "3 lines of haiku in Japanese"],
    english: Annotated[list[str], "3 lines of haiku translated to English"],
    image_name: Annotated[str, "One relevant image name from the valid set"],
    gradient: Annotated[str, "CSS Gradient color for the background"],
) -> str:
    """Generate a haiku with Japanese text, English translation, and a background image."""
    return "Haiku generated!"


def generate_task_steps(
    steps: Annotated[
        list[dict],
        "Array of step objects with 'description' (string) and 'status' ('enabled' or 'disabled')",
    ],
) -> str:
    """Generate a list of task steps for the user to review and approve."""
    return f"Generated {len(steps)} steps for review"


def book_call(
    topic: Annotated[str, "What the call is about (e.g. 'Intro with sales')"],
    attendee: Annotated[str, "Who the call is with (e.g. 'Alice from Sales')"],
) -> str:
    """Ask the user to pick a time slot for a call. The picker UI presents fixed candidate slots; the user's choice is returned to the agent."""
    return f"Booking call about {topic} with {attendee}"


def show_card(
    title: Annotated[str, "Short heading for the card."],
    body: Annotated[str, "Body text for the card."],
) -> str:
    """Display a titled card with a short body of text. Rendered on the frontend via useComponent."""
    return f"Displayed card: {title}"


# --- Backend tools (executed server-side, using shared implementations) ---


async def get_weather(
    location: Annotated[str, "The location to get the weather for."],
) -> str:
    """Get the weather for a given location. Returns temperature, conditions, humidity, wind speed, and feels-like temperature."""
    return json.dumps(get_weather_impl(location))

To check it, ask the agent for the weather in San Francisco. Your card renders with the temperature from result.

For every option, see the useRenderTool reference.

How is this guide?