--- meta: title: "Tools" parentTitle: "AI Copilots" description: "Allow AI to interact with your application" --- Tools allow AI to make actions, modify your application state, interact with your front-end, and render custom components within your AI chat. Use tools to extend the capabilities of AI Copilots beyond simple text, allowing autonomous and human-in-the-loop interactions. ## Tool use cases Tools can be used to create various different interactions inside of your AI chat, such as: - **Actions**: Autonomously perform actions like editing documents, redirecting users, sending emails. - **Custom components**: Render custom React components like forms, graphs, videos, callouts. - **Query actions**: AI can query your app, search documents, find pages, check invoices. - **Human-in-the-loop actions**: Show confirm/deny buttons before taking destructive actions. - **AI presence**: Tool results can be streamed in, allowing AI to show live updates in your app. ### How tools work You can define a list of tools in your application, and your AI can choose to use them whenever it decides they’re needed. Within each tool you can set certain parameters which AI will fill in for you. For example, a weather tool may have a `location` parameter, and AI may enter `"Paris"` as the value. Here’s an example of a tool call interaction: In your weather tool, `location` is defined as a `string` ```json { "location": { type: "string" } } ``` {" "} User asks about the weather in Paris ```js User: "What's the weather in Paris?" ``` AI calls the weather tool with `Paris` as the `location` ```js { "location": "Paris" } ``` {" "} You write code to fetch the weather for the `location` ```js execute: async ({ location }) => { // { "temperature": 20, "condition": "sunny" }; const weather = await __fetchWeather__(location); return { data: { weather }}; } ``` AI answers the user ```js AI: "It's sunny in Paris, with a temperature of 20°C." ``` When writing your [system prompt](/docs/ready-made-features/ai-copilots/copilots#System-prompt) you can suggest when certain tools should be used, helping AI respond as you like. This is just an example of a simple tool, but below we’ll detail how to create more complex tools that have confirm/deny dialogs, render custom components, query data, and more. ## Defining tools You can define a tool with [`defineAiTool`](/docs/api-reference/liveblocks-client#defineAiTool) and [`RegisterAiTool`](/docs/api-reference/liveblocks-react#RegisterAiTool). First, you first need to give your tool a unique name, and a description, which helps AI understand when to call it. You can place the component anywhere in your app. ```tsx import { RegisterAiTool } from "@liveblocks/react"; import { defineAiTool } from "@liveblocks/client"; import { AiChat } from "@liveblocks/react-ui"; function Chat() { return ( <> // +++ // +++ ); } ``` For AI to use your tools intelligently, parameters must be defined, which AI will fill in for you. Tools use [JSON schema](/docs/ready-made-features/ai-copilots/tools#Advanced-JSON-schema) to define these. For example, you can define `location` parameter as a `string`. ```tsx ``` To add functionality to your tool, a combination of `execute` and `render` functions are used. ```tsx { // ... }, render: ({ stage, partialArgs, args, result, respond }) => { // ... }, // +++ })} /> ``` In each of the following sections, different ways to implement `execute` and `render` are detailed. ## Actions If you’d like your AI to perform an action when the tool is called, you can use `execute` to define what should happen. The arguments passed to `execute` are the parameters defined in your tool, filled in by AI. After the tool has run, return any `data` you’d like to pass back to AI. ```tsx { const weather = await __fetchWeather__(location); return { data: { weather } }; }, // +++ })} /> ``` After running `execute`, AI will read the `data` object, and choose how to respond. Additionally, you can define a `description` to pass back to AI. This is a way to inform AI what has just taken place, so it can understand the context of the result, and what it should do next. This text will never be shown to the user. ```ts execute: async ({ location }) => { const weather = await __fetchWeather__(location); return { data: { weather }, // +++ description: "You've just fetched the weather, share the temperature in °C." // +++ }; }, ``` The [AI Calendar](/examples/ai-calendar/nextjs-ai-calendar) example contains an action that allows AI to create new calendar events. ### Display a loading message You can easily display a loading message while an action takes place using `render` and [`AiTool`](/docs/api-reference/liveblocks-react-ui#AiTool). You can also choose to display a message after the action has finished, as in the example below. ```tsx import { AiChat, AiTool } from "@liveblocks/react-ui"; import { RegisterAiTool } from "@liveblocks/react"; function Chat() { <> { const weather = await __fetchWeather__(location); return { data: { weather }, description: "You've just fetched the weather.", }; }, // +++ render: ({ stage }) => { // `execute` is still running if (stage !== "executed") { return ; } // `execute` has finished return ; }, // +++ })} /> ; } ``` [`AiTool`](/docs/api-reference/liveblocks-react-ui#AiTool) isn’t required here, as you can return any JSX, but it’s an easy way to match the styling of the default chat. Returning `null` will display nothing. ### Combine actions with front-end knowledge You can combine actions with [front-end knowledge](/docs/ready-made-features/ai-copilots/knowledge) to create an AI assistant that can take actions. For example, say you have a document on the current page. You can use knowledge to pass the document’s text to the AI, then create a tool that allows AI to edit the document. ```tsx import { RegisterAiKnowledge } from "@liveblocks/react"; import { AiChat } from "@liveblocks/react-ui"; import { RegisterAiTool } from "@liveblocks/react"; import { defineAiTool } from "@liveblocks/client"; import { useState } from "react"; function Document() { // +++ const [document, setDocument] = useState("Hello world"); // +++ return ( <> { // +++ setDocument(args.text); // +++ return { data: {}, description: "Document updated" }; }, render: ({ stage }) => { if (stage !== "executed") { return ; } return ; }, })} /> ); } ``` ## Custom components You can use tools to display custom components inside the chat with the `render` function. These don’t have to be simple components, but can be complex, like forms, graphs, videos, callouts. When displaying a simple component, include an `execute` function, even if it’s empty, otherwise the chat will assume it’s a [human-in-the-loop action](#Human-in-the-loop-actions). ```tsx {}, // +++ render: () => { return ; }, // +++ })} /> ``` You can go further than this, and allow AI to [create parameters](#Advanced-JSON-schema) which you can use in your custom component, for example `x` and `y` values on a graph. ```tsx {}, render: ({ args, stage }) => { if (stage !== "executed") { return
Loading...
; } // +++ return ; // +++ }, })} /> ``` AI will most likely write a response after using your tool, but you can prompt the AI to not respond by adding a `description` to `execute`. ```tsx { return { data: {}, // +++ description: "You’re displaying a graph. Do not respond further.", // +++ }; }, render: ({ args, stage }) => { if (stage !== "executed") { return
Loading...
; } // +++ return ; // +++ }, })} /> ``` The [AI Support Chat](/examples/ai-support/nextjs-ai-support) example uses custom components in its support ticket tool to display a contact form. ### Fetching data for custom components You can take custom components a step further by combining them with [actions](#Actions), and then showing the results inside the custom component. The `result` property contains the data returned from the action. ```tsx { // { "temperature": 20, "condition": "sunny" }; const weather = await __fetchWeather__(location); return { data: { weather } }; }, // +++ render: ({ stage, args, result }) => { if (stage !== "executed") { return
Fetching weather…
; } return ( ); }, // +++ })} /> ``` `args` contains the arguments passed to the tool from AI, and `result` contains the data returned from the tool. ## Query actions A helpful way to use tools is to allow AI to query data from your application, such as documents, pages, or other data sources. If your application already contains a search function, you can easily plug it into your tool to create a powerful AI assistant. For example, this tool can search through documents by title, folder, and category. ```tsx { const documents = await __queryDocuments__({ title, folder, category }); return { data: { documents }, description: documents.length > 0 ? `${documents.length} results` : "No results" }; }, // +++ render: ({ stage, args, result }) => { if (stage !== "executed") { return ; } return null; }, })} /> ``` Since the query is happening on the front-end, you don’t need to implement separate authentication for your AI tool—it can leverage the same APIs that your users are already authorized to access. The [AI Reports Dashboard](/examples/ai-dashboard-reports/nextjs-ai-dashboard-reports) example has a query transactions tool allowing for complex searching. ## Human-in-the-loop actions Human-in-the-loop actions allow the user to confirm or deny an action before it’s executed. This is particularly useful when it comes to destructive and stateful actions, such as deleting a document, or sending an email. Confirmable actions like these will freeze the chat until the user responds, either by confirming or cancelling the action. User asks to delete a document ```js User: "Can you delete my-document.txt?" ``` AI calls the delete document tool, “Confirm” and “deny” buttons are displayed _The chat waits for the user to respond._ The user clicks “Confirm” _The document is deleted._ The chat unfreezes and is ready to continue ```js AI: "I've deleted it! How else can I help you?" ``` To create confirmable actions, you must skip using the `execute` function, and instead move your logic to `render`, as we detail below. This will always freeze the chat until the user responds. The [AI Reports Dashboard](/examples/ai-dashboard-reports/nextjs-ai-dashboard-reports) example demonstrates human-in-the-loop actions with its invite member tool. ### Default confirmation component The easiest way to create confirmable actions, is to return the ready-made [`AiTool.Confirmation`](/docs/api-reference/liveblocks-react-ui#AiTool.Confirmation) component in `render`. The `confirm` and `cancel` callbacks work very similarly to `execute`, and are triggered when the user clicks “Confirm” or “Cancel”. ```tsx { return ( // +++ { await __deleteDocument__(documentId); return { data: { documentId }, description: "The user chose to delete the document", }; }} cancel={() => { return { data: { documentId }, description: "The user cancelled deleting the document", }; }} /> // +++ ); }, })} /> ``` In the `cancel` callback it’s important to let the AI know that the user cancelled the action, otherwise it may assume the action failed and try to run it again. ```js description: "The user cancelled deleting the document", ``` ### Building a custom confirmation component By utilizing the `respond` argument in `render`, and the different stages of a tool’s lifecycle, you can build a fully custom confirmation component. These are the different stages: 1. `receiving` - Displayed when AI is streaming in the parameters. 2. `executing` - Displayed when the chat is frozen, and is waiting for a response. 3. `executed` - Displayed after a response has been recorded. Here’s how to leverage the different stages to create a custom “send email” tool—note how `respond` is used similarly to `execute`. ```tsx { // `emailAddress` param is still streaming in, wait // +++ if (stage === "receiving") { return
Loading...
; } // +++ // The tool is waiting for `respond` to be called // +++ if (stage === "executing") { return (
{ e.preventDefault(); const message = e.target.message.value; await __sendEmail__(args.emailAddress, message); // Similar to `execute`/`confirm`, let AI know it succeeded respond({ data: { emailAddress: args.emailAddress, message }, description: "You sent an email for the user", }); }} >