连接到自定义工具

将 GitBook Assistant 连接到任何你可以从应用中调用的工具——尤其是支持类工作流

自定义工具可让 GitBook Assistant 在 Docs Embed 中执行真实操作。

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

如果你的应用能调用它，Assistant 也能调用它。

常见示例：

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

• 通过打开带有预填消息的支持聊天，将用户转交给支持团队

  支持转接 是开始使用自定义工具的绝佳方式。它是快速帮助用户解决阻塞的最快途径。

• 触发产品操作（重置 MFA、重新发送邀请、启用功能标志）

• 在你的后端查询账户状态

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

除了你在 Embed 配置中定义的工具之外，Assistant 还可以使用任何 你设置的 MCP 服务器 在 设置 → AI 与 MCP.

工具运行的位置

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

这通常意味着它运行在用户的浏览器中，位于你的应用内。

因此你可以：

• 调用你自己的后端端点

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

• 打开模态窗口、深层链接或产品内 UI

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

添加工具

定义工具：

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

• 通过 tools 用于 Node.js/NPM package 和 React 组件的

工具与嵌入 actions.

• 使用 actions 中用户点击的按钮并不相同。

• 当你希望 Assistant 选择并运行代码时，请使用工具。

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

让我们看一个例子：

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: "已重新发送邀请邮件。",
          },
        };
      },
    },
  ],
});

工具如何被使用

一旦你注册了工具，Assistant 就可以自动选择它们——基于用户的问题和你的工具 描述.

如果缺少必需字段，Assistant 应该提出后续问题。

如果你添加 confirmation，则工具运行前用户必须批准。

工具字段

• name：唯一标识符。

• 描述：给 Assistant 的“何时使用此工具”提示。

• inputSchema：工具输入的 JSON Schema。

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

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

  • 返回 { output, summary }.

  • output 会返回给 Assistant。

  • summary 会显示给用户。

确认

使用 confirmation 用于你希望用户批准某个操作时。它有助于防止意外的副作用。

confirmation 接受：

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

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

支持工作流

支持是工具最具价值的使用场景。

你可以让 Assistant：

• 收集缺失的详细信息

• 在你的系统中创建工单

• 打开一个带有预填上下文的人工支持渠道

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

当你想要顺畅地转接给人工时，请使用此模板。

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 Assistant
        window.GitBook('close');
     
        // 示例：
        // - Intercom: Intercom('showNewMessage', input.message);
        // - Zendesk: zE('messenger', 'open');
        
        return {
          output: {
            status: "success",
          },
          summary: { icon: 'check', text: "已转交给支持团队。" },
        };
      },
    },
  ],
});

将其与始终可见的 联系支持 操作一起放在嵌入侧边栏中。你可以按照以下方式配置操作 自定义嵌入.

后续步骤

• 需要完整的 embed API 能力面？请参阅 API 参考.

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