连接自定义工具

将 GitBook 助手连接到您应用中可以调用的任何工具 — 尤其是支持工作流

自定义工具允许 GitBook 助手在 文档嵌入 执行真实操作。

您可以将其连接到 任何 您的应用可以访问的工具。这包括您的后端 API、第三方 SDK 和内部系统。

如果您的应用可以调用它，助手也可以调用它。

常见示例：

• 代表用户创建或更新支持工单

• 通过打开带有预填消息的支持聊天将用户交接给人工支持

  支持交接 是开始使用自定义工具的好方法。这是最快的方式来帮助用户解困。

• 触发产品操作（重置多因素认证、重新发送邀请、启用功能开关）

• 在后端查找账户状态

• 在 Jira、Linear、Slack 或 Zendesk 等工具中启动工作流

除了在嵌入配置中定义的工具外，助手还可以使用任何 您设置的 MCP 服务器 位于 设置 → AI 与 MCP.

工具运行位置

该工具的 execute 函数在与您的嵌入集成相同的环境中运行。

这通常意味着它在用户的浏览器中、在您的应用内运行。

因此您可以：

• 调用您自己的后端端点

• 调用您应用中已加载的任何第三方 SDK（例如 Intercom）

• 打开模态、深度链接或产品内 UI

避免在客户端代码中放置密钥——改为调用您的后端。

添加工具

定义工具：

• 通过 window.GitBook("configure", …) 用于 脚本标签 实现

• 通过 tools 属性用于 Node.js/NPM 包和 React 组件

工具不同于嵌入 操作.

• 对于用户点击的按钮使用 操作 。

• 当您希望助手选择并运行代码时使用工具。

工具模板（重新发送邀请邮件）

让我们看一个示例：

window.GitBook("configure", {
  tools: [
    {
      // 使用名称和描述注册该工具。
      name: "resend_invite",
      description:
        "当用户找不到邀请或说邀请已过期时，重新发送邀请邮件。",

      // 输入 schema 是可以在 execute 函数中访问的数据。
      inputSchema: {
        type: "object",
        properties: {
          email: {
            type: "string",
            description:
              "要重新发送邀请的电子邮件地址。如果未知，请先询问用户。",
          },
        },
        required: ["email"],
      },

      // 可选的确认按钮，会在执行 execute 函数之前显示。
      confirmation: { icon: "paper-plane", label: "重新发送邀请？" },

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

        const result = await fetch("/api/invites/resend", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ email }),
        }).then((r) => r.json());

        return {
          // 输出会被传回给 AI。
          output: {
            recipient: email,
            status: result.status ?? "success",
          },
          // 摘要会显示给用户。
          summary: {
            icon: "check",
            text: "已重新发送邀请邮件。",
          },
        };
      },
    },
  ],
});

工具如何被使用

注册工具后，助手可以基于用户的问题和您对工具的 描述.

如果必填字段缺失，助手应提出后续问题。

如果您添加了 确认，在工具运行前用户必须批准。

工具字段

• name：唯一标识符。

• 描述：助手的“何时使用此项”提示。

• inputSchema：工具输入的 JSON Schema。

• 确认 （可选）：在工具运行前显示的确认按钮。

• execute(input)：运行操作的异步函数。

  • 返回 { output, summary }.

  • output 会返回给助手。

  • summary 会显示给用户。

确认

对于用户点击的按钮使用 确认 当您希望用户批准某个操作时使用。它有助于防止意外的副作用。

确认 接受：

• label （必填）：按钮文本。

• icon （可选）：一个 Font Awesome 图标名称。

支持工作流

支持是工具的最高效用场景。

您可以让助手：

• 收集缺失的细节

• 在您的系统中创建工单

• 打开带有预填上下文的人类支持通道

模板：使用预填消息打开支持聊天

当您希望将问题干净地交接给人工时使用此项。

window.GitBook("configure", {
  tools: [
    {
      name: "open_support_chat",
      description:
        "使用预填消息打开支持聊天，以便用户可以快速联系支持。",
      inputSchema: {
        type: "object",
        properties: {
          message: {
            type: "string",
            description:
              "发送给支持的消息。如果缺失，请先询问用户。",
          },
        },
      },
      confirmation: { icon: "circle-question", label: "打开支持聊天" },
      execute: (input) => {
        // 关闭 GitBook 助手
        window.GitBook('close');
     
        // 示例：
        // - Intercom: Intercom('showNewMessage', input.message);
        // - Zendesk: zE('messenger', 'open');
        
        return {
          output: {
            status: "success",
          },
          summary: { icon: 'check', text: "已转发给支持。" },
        };
      },
    },
  ],
});

将此与始终可见的 联系支持 操作配对放在嵌入侧边栏中。您可以按照 自定义嵌入.

下一步

• 需要完整的嵌入 API 表面？请参见 API 参考.

• 想要更多 UI 控件（问候语、建议、操作）？请参见 自定义嵌入.