创建自定义工具

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

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

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

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

让我们看一个示例：

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: {
            icon: 'check',
            text: `已为 ${ticket_issue} 创建工单 #${ticket.id}`
          },
        };
      },
    },
  ],
});

工作原理

在配置时提供给 GitBook Assistant 的任何工具都将在 AI 中可用——这意味着当情境合适时，Assistant 能够智能地执行您的工具。

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

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