Tools

Tools configuration allows you to define custom functions that can be called by the AI assistant during chat interactions. These tools enable the AI to trigger actions in your application based on its responses, such as opening forms, links, or performing callbacks.

Tools do not modify or generate the AI's response content. They are specifically designed to perform actions (like opening links or forms) in response to the AI's analysis of the conversation.

Basic Usage

Here's a simple example of configuring a tool that checks service status:

const aiChatSettings = {
  getTools: () => [
    {
      type: "function",
      function: {
        name: "checkStatus",
        description: "Check the status of a service",
        parameters: {
          type: "object",
          properties: {
            service: {
              type: "object",
              properties: {
                name: {
                  anyOf: [
                    {
                      type: "string",
                      const: "api",
                      description: "API service",
                    },
                    {
                      type: "string",
                      const: "database",
                      description: "Database service",
                    },
                  ],
                },
              },
              required: ["name"],
            },
          },
          required: ["service"],
        },
      },
      renderMessageButtons: ({ args }) => {
        return [
          {
            label: `Check ${args.service.name} Status`,
            icon: { builtIn: "FaServer" },
            action: {
              type: "open_link",
              url: `https://status.example.com/${args.service.name}`,
            },
          },
        ];
      },
    },
  ],
};

Available Actions

Tools can trigger three types of actions:

Open Link (open_link)
action: { type: 'open_link', url: 'https://example.com' }

Open Form (open_form)

action: {
  type: 'open_form',
  formSettings: {
    heading: 'Contact Support',
    fields: [
      {
        label: 'Email',
        name: 'email',
        inputType: 'email',
        isRequired: true,
      }
    ]
  }
}

Invoke Callback (invoke_callback)
action: { type: 'invoke_callback', callback: ({ conversation }) => { console.log('Custom action triggered', conversation) } }

For more details about actions and their configurations, see the Actions Guide.

Common Use Cases

1. Confidence-Based Support Escalation

This example shows how to create a tool that suggests contacting support when the AI's confidence is low:

const aiChatSettings = {
  getTools: () => [
    {
      type: "function",
      function: {
        name: "escalateToHuman",
        description: "Escalates the conversation to a human",
        parameters: {
          type: "object",
          properties: {
            aiAnnotations: {
              type: "object",
              properties: {
                answerConfidence: {
                  anyOf: [
                    { type: "string", const: "very_confident" },
                    { type: "string", const: "somewhat_confident" },
                    { type: "string", const: "not_confident" },
                    { type: "string", const: "no_sources" },
                  ],
                },
              },
              required: ["answerConfidence"],
            },
          },
          required: ["aiAnnotations"],
        },
      },
      renderMessageButtons: ({ args }) => {
        const confidence = args.aiAnnotations.answerConfidence;
        if (confidence !== "very_confident") {
          return [
            {
              label: "Contact Support",
              icon: { builtIn: "LuUsers" },
              action: {
                type: "open_link",
                url: "https://support.example.com",
              },
            },
          ];
        }
        return [];
      },
    },
  ],
};

2. Contact Form Integration

Example of a tool that opens a contact form based on the query category:

const aiChatSettings = {
  getTools: () => [
    {
      type: "function",
      function: {
        name: "contactSupport",
        description: "Open contact form for support",
        parameters: {
          type: "object",
          properties: {
            category: {
              type: "object",
              properties: {
                type: {
                  anyOf: [
                    {
                      type: "string",
                      const: "technical",
                      description: "Technical support",
                    },
                    {
                      type: "string",
                      const: "billing",
                      description: "Billing support",
                    },
                  ],
                },
              },
              required: ["type"],
            },
          },
          required: ["category"],
        },
      },
      renderMessageButtons: ({ args }) => {
        return [
          {
            label: "Contact Support",
            icon: { builtIn: "FaEnvelope" },
            action: {
              type: "open_form",
              formSettings: {
                heading: `${args.category.type} Support`,
                fields: [
                  {
                    label: "Email",
                    name: "email",
                    inputType: "email",
                    isRequired: true,
                  },
                  {
                    label: "Message",
                    name: "message",
                    inputType: "textarea",
                    isRequired: true,
                  },
                ],
              },
            },
          },
        ];
      },
    },
  ],
};

Context-Based Tool Generation

Tools can be dynamically generated based on the conversation context. The getTools function receives a context object containing the current conversation state

This example shows a tool that schedules a call when the AI has had multiple low confidence responses:

const aiChatSettings = {
  getTools: (context: ToolContext) => {
    // Count how many low confidence responses we've had in this conversation
    const lowConfidenceCount = context.conversation.messages.reduce(
      (count, msg) => {
        const toolCalls = msg.toolCalls || [];
        const hasLowConfidence = toolCalls.some((call) => {
          try {
            const args = JSON.parse(call.arguments);
            return (
              call.name === "provideAIAnnotations" &&
              args.aiAnnotations?.answerConfidence !== "very_confident"
            );
          } catch {
            return false;
          }
        });
        return count + (hasLowConfidence ? 1 : 0);
      },
      0
    );
 
    const tools = [
      // Base tools always available
      {
        type: "function",
        function: {
          name: "provideAIAnnotations",
          description: "Provides AI annotations about response confidence",
          parameters: {
            type: "object",
            properties: {
              aiAnnotations: {
                type: "object",
                properties: {
                  answerConfidence: {
                    anyOf: [
                      { type: "string", const: "very_confident" },
                      { type: "string", const: "somewhat_confident" },
                      { type: "string", const: "not_confident" },
                      { type: "string", const: "no_sources" },
                    ],
                  },
                },
                required: ["answerConfidence"],
              },
            },
            required: ["aiAnnotations"],
          },
        },
      },
    ];
 
    // If we've had multiple low confidence responses, add a tool to schedule a call
    if (lowConfidenceCount >= 2) {
      tools.push({
        type: "function",
        function: {
          name: "scheduleCall",
          description: "Schedule a call with support team",
          parameters: {
            type: "object",
            properties: {
              reason: {
                type: "string",
                enum: ["technical_help", "product_demo", "general_inquiry"],
              },
            },
          },
        },
        renderMessageButtons: ({ args }) => [
          {
            label: "Schedule Support Call",
            icon: { builtIn: "FaPhone" },
            action: {
              type: "open_form",
              formSettings: {
                heading: "Schedule a Call",
                description: "Let's set up a call to better assist you",
                fields: [
                  {
                    label: "Email",
                    name: "email",
                    inputType: "email",
                    isRequired: true,
                  },
                  {
                    label: "Preferred Time",
                    name: "preferredTime",
                    inputType: "datetime-local",
                    isRequired: true,
                  },
                ],
              },
            },
          },
        ],
      });
    }
 
    return tools;
  },
};

Using Zod Schemas

You can use Zod to define your parameter schemas in a more type-safe way. The schema can be converted to JSON Schema format using zod-to-json-schema:

import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";
 
const answerConfidence = z
  .enum(["very_confident", "somewhat_confident", "not_confident", "no_sources"])
  .describe("AI confidence level in the response");
 
const confidenceSchema = z.object({
  aiAnnotations: z.object({
    answerConfidence,
  }),
});
 
const aiChatSettings = {
  getTools: () => [
    {
      type: "function",
      function: {
        name: "provideAIAnnotations",
        description: "Provides AI annotations about response confidence",
        parameters: zodToJsonSchema(confidenceSchema),
      },
      renderMessageButtons: ({ args }) => {
        const confidence = args.aiAnnotations.answerConfidence;
        if (confidence !== "very_confident") {
          return [
            {
              label: "Contact Support",
              icon: { builtIn: "LuUsers" },
              action: {
                type: "open_link",
                url: "https://support.example.com",
              },
            },
          ];
        }
        return [];
      },
    },
  ],
};