Tool Call Rendering

Render your agent's tool calls with custom UI 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. Instead of showing raw JSON, you register a Vue component that draws a branded card for the call (arguments, live status, and the eventual result). This is the Generative UI variant CopilotKit calls tool rendering.

When should I use this?

Render tool calls when you want to:

  • Show users exactly what tools the agent is invoking and with what arguments
  • Display live progress indicators while a tool executes
  • Render rich, polished results once a tool completes
  • Give tool-heavy agents a transparent, on-brand chat experience

Default tool rendering (zero-config)

The simplest entry point is useDefaultRenderTool() with no arguments. CopilotKit registers its built-in default renderer as the * wildcard: every tool call renders as a status card (tool name, live Running → Done state, collapsible arguments/result) without you writing any UI.

Without this composable, CopilotKit has no * renderer and tool calls are not shown. The user only sees the assistant's final text summary.

src/components/AgentExperience.vue
<script setup lang="ts">
import { CopilotChat, useDefaultRenderTool } from "@copilotkit/vue/v2";

useDefaultRenderTool();
</script>

<template><CopilotChat /></template>

Custom catch-all

Once you want on-brand chrome, pass a render component or function to useDefaultRenderTool. It's a convenience wrapper around useRenderTool({ name: "*", ... }): one wildcard renderer handles every tool call, named or not.

src/components/AgentExperience.vue
useDefaultRenderTool({ render: BrandedToolCard });

Per-tool renderers

The most expressive path is one renderer per tool name. Each renderer receives the tool's parsed arguments, a live status, and, once the agent returns, the result.

  1. Write the card component:

    src/components/WeatherToolCard.vue
    <script setup lang="ts">
    defineProps<{
      parameters: { city?: string };
      status: "inProgress" | "executing" | "complete";
      result?: string;
    }>();
    </script>
    
    <template>
      <p v-if="status !== 'complete'">Checking {{ parameters.city ?? "…" }}</p>
      <article v-else>
        <strong>{{ parameters.city }}</strong>
        <pre>{{ result }}</pre>
      </article>
    </template>
  2. Register it with useRenderTool in a component:

    src/components/AgentExperience.vue
    <script setup lang="ts">
    import { z } from "zod";
    import { CopilotChat, useDefaultRenderTool, useRenderTool } from "@copilotkit/vue/v2";
    import WeatherToolCard from "./WeatherToolCard.vue";
    
    useRenderTool({
      name: "get_weather",
      parameters: z.object({ city: z.string() }),
      render: WeatherToolCard,
    });
    
    useDefaultRenderTool(); // wildcard fallback for every other tool
    </script>
    
    <template><CopilotChat /></template>
  3. Mount that component under CopilotKitProvider:

    src/App.vue
    <script setup lang="ts">
    import { CopilotKitProvider } from "@copilotkit/vue/v2";
    import AgentExperience from "./components/AgentExperience.vue";
    </script>
    
    <template>
      <CopilotKitProvider runtime-url="/api/copilotkit"><AgentExperience /></CopilotKitProvider>
    </template>

parameters is partial while arguments stream. Read required fields only after the status advances from inProgress. The result is a string when status is complete; parse it only if your backend deliberately returns a documented serialized shape.

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

Per-tool renderers compose with a catch-all: named renderers claim the "interesting" tools and a wildcard handles everything else. The example registers the built-in wildcard after the named get_weather renderer.

If the renderer closes over reactive values, pass Vue watch sources as the second argument:

useRenderTool({ name: "get_weather", parameters, render: WeatherToolCard }, [locale]);

The backend tool definition

The frontend renderer only sees what the agent sends down. The matching backend must expose a tool named get_weather, return structured data, and let the frontend renderer with the same name paint the card. The Vue renderer does not create or execute 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))

How is this guide?