# Tool Call Rendering

> Render your agent's tool calls with custom UI components.

## What is this? [#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? [#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) [#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.

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

useDefaultRenderTool();
</script>

<template><CopilotChat /></template>
```

## Custom catch-all [#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.

```ts title="src/components/AgentExperience.vue"
useDefaultRenderTool({ render: BrandedToolCard });
```

## Per-tool renderers [#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:

   ```vue title="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:

   ```vue title="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`:

   ```vue title="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.

<Callout type="info">
  The `name` you pass to `useRenderTool` must match the tool name the agent exposes. That is how CopilotKit routes the call to your component.
</Callout>

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:

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

## The backend tool definition [#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.

```python title="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.",
)
```

```python title="src/agents/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))

```

<IntegrationGrid path="generative-ui/tool-rendering" />
