Skip to main content

Adding a New Tool

Introduction​

This guide outlines the complete process for integrating a new tool into the chat system. A "tool" is a specialized function that the AI can invoke to perform actions, retrieve data, or present complex information in a structured UI. Following these steps will ensure that your new tool is correctly defined, activated, and rendered within the application.

Step 1. Define the Tool Name and Type​

First, we must register the new tool's name in our TypeScript type system. This provides type safety and enables autocompletion across the codebase.

File: web/src/features/shared/chat/utils/types.ts

Action:

  • Add your new tool's unique identifier to the ToolNames object.

Step 2. Create the Tool Definition File​

This is the core of your tool. Here, you will define its behavior, its input schema, and the React component used to render its output.

File: web/src/features/shared/chat/tools/

Action:

  • Create a new directory for your tool, for example, quote-generator.ts and an index.ts file inside
  • Inside this file, define the tool's definition.
  • Inside the directory, create new file quote-generator-message.ts file. This is the UI for your tool.

Step 3: Register the New Tool​

After defining the tool, you must add it to the central registry. This makes it available to the rest of the application.

File: web/src/features/shared/chat/tools/index.ts

Action:

  • Import your new tool definition and add it to the exported list of all tools

Step 4: Configure Server-Side Tool Activation​

Not all tools should be active for every user or in every situation. This step involves adding logic to conditionally provide your tool to the AI model based on specific criteria (e.g., user permissions, feature flags, or conversation context).

File: web/src/features/shared/chat/utils/server.ts

Action:

  • Add your condition for including the new tool in getActiveTools function

Step 5: Handle Multi-Step​

Some tools are interactive and require user input after the AI has initially called them. For example, a tool might present a form to the user and wait for them to fill it out before its action can be completed. This process involves two stages:

  • Initial Invocation: The AI calls the tool, returns the necessary data to render an interactive UI component (like a form or a confirmation button).
  • Final Execution: The user interacts with the UI, and their input is sent to a dedicated backend handler to complete the tool's action.

This step covers how to implement the final execution logic.

File: web/src/app/api/chat/utils.ts

Action:

  • Add the final execution logic for your interactive tool to the executeTool function. This function acts as a server-side dispatcher that is called when a user submits data from an interactive tool's UI. You will need to add a case for your tool's name within the switch statement.

Step 6: Render the Tool's UI in the Chat​

Once the tool is executed and returns data, we need to render its custom React component in the chat history.

File: src/features/shared/chat/components/messages/bot-message.tsx

Action:

  • In this component, there is a switch statement or a mapping object that determines which component to render based on the message type or tool name. Add a case for your new tool.

Step 7: Final Consideration: Response Persistence​

Finally, determine if the response from your tool should be saved in the conversation history database.

File: web/src/features/shared/chat/utils/server.ts

Action:

  • Add your tool name in TOOLS_TO_EXCLUDE array if you don't want your tool's response to be saved