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.

index.ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "get_weather",
  description: "Get current weather for a location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
    temperature: z
      .number()
      .optional()
      .describe(
        "Optional scripted temperature (°F); echoed back when provided",
      ),
    conditions: z
      .string()
      .optional()
      .describe("Optional scripted conditions; echoed back when provided"),
    humidity: z
      .number()
      .optional()
      .describe("Optional scripted humidity; echoed back when provided"),
    wind_speed: z
      .number()
      .optional()
      .describe("Optional scripted wind speed; echoed back when provided"),
  }),
  // Optional temperature/conditions/humidity/wind_speed let an aimock fixture
  // script a deterministic snapshot (mirrors get_stock_price's scripted
  // price_usd — e.g. headless-complete pins Tokyo to a fixed "Sunny / 68°F"
  // card matching gold langgraph-python). When omitted, the seeded
  // getWeatherImpl(location) values are used (e.g. tool-rendering's SF pill).
  //
  // Return the OBJECT, not JSON.stringify: the @ag-ui/mastra bridge encodes the
  // tool result exactly once on the way to the frontend, so stringifying here
  // double-encodes it and the typed cards' single-parse (parseJsonResult) reads
  // back a string with undefined fields ("--%"). Single-encode by returning the
  // object (same rule as browse_web / the Mastra capability-map memory).
  execute: async ({
    location,
    temperature,
    conditions,
    humidity,
    wind_speed,
  }) => ({
    ...getWeatherImpl(location),
    ...(typeof temperature === "number" ? { temperature } : {}),
    ...(conditions ? { conditions } : {}),
    ...(typeof humidity === "number" ? { humidity } : {}),
    ...(typeof wind_speed === "number" ? { wind_speed } : {}),
  }),
});

How is this guide?