创建自定义工具

向 GitBook 助手添加自定义工具，以允许其与您的产品、网站等交互

Docs 嵌入中的自定义工具允许您让助理在您的产品或网络上智能地调度操作。例如，您可以构建一个自定义工具，指示 GitBook 助手调用 API、执行产品操作、打开其他工具等。

除了在 Docs 嵌入配置中定义的自定义工具外，助理还始终可以访问任何 您定义的 MCP 服务器 在您站点的 AI 设置中。

工具可以通过 configure 方法在使用脚本实现时定义，或在使用 NPM 包/React 组件时作为属性传入。

让我们看一个示例：

window.GitBook("configure", {
  tools: [
    {
      // 使用名称和描述注册该工具。
      name: "create_ticket",
      description:
        "为用户创建工单。您必须填写 ticket_issue 字段。",

      // input schema 是可以在 execute 函数中访问的数据。
      inputSchema: {
        type: "object",
        properties: {
          ticket_issue: {
            type: "string",
            description:
              "用于创建工单的问题。如果未知，请先询问用户。",
          },
        },
        required: ["ticket_issue"],
      },

      // 一个可选的确认按钮，会在执行 execute 函数之前显示。
      confirmation: { icon: "circle-question", label: "创建支持工单？" },

      // execute 函数是在工具被使用时调用的函数。
      execute: async (input) => {
        const { ticket_issue } = input;

        // 使用用户的问题创建工单
        const ticket = await fetch("/api/tickets", {
          method: "POST",
          body: JSON.stringify({ issue: ticket_issue }),
        }).then((r) => r.json());

        return {
          // 输出会传回给 AI。
          output: {
            ticketId: ticket.id,
            status: "success",
          },
          // 摘要显示给用户。
          summary: `Created ticket #${ticket.id} for ${ticket_issue}`,
        };
      },
    },
  ],
});

工作原理

在配置时提供给 GitBook 助手的任何工具都将在 AI 中可用——这意味着助理能够在合适的上下文中智能地执行您的工具。

在上面的示例中，当助理识别出用户需要创建支持工单时，会询问用户问题是什么，然后执行记录工单的函数。

键	描述
name	唯一的工具标识符。
description	让 GitBook 助手了解何时使用所定义的工具的上下文。
inputSchema	定义该工具输入参数的 JSON 模式。可在 input 参数的 execute 调用中访问。
confirmation	一个可选的确认按钮，允许您在触发 execute 函数之前指定用户交互。格式： { icon?: string, label: string }.
execute	在调用工具时运行的异步函数。必须返回 { output: any, summary: string }. 输出 output 会提供给 AI 以便继续处理（不向用户显示）。 summary 是在用户聊天窗口中显示的可视摘要。