カスタムツールに接続する

GitBook Assistant を、アプリから呼び出せるあらゆるツール、特にサポートワークフローに接続する

GitBook アシスタントにカスタムツールを使わせると、 Docs Embed 実際の操作を実行できます。

これを 任意の アプリからアクセスできるツールに接続できます。これには、バックエンド API、サードパーティ SDK、社内システムが含まれます。

アプリから呼び出せるものなら、アシスタントも呼び出せます。

一般的な例：

• ユーザーに代わってサポートチケットを作成または更新する

• あらかじめ入力したメッセージでサポートチャットを開き、サポートに引き継ぐ

  サポートへの引き継ぎ は、カスタムツールを始めるのに最適な方法です。ユーザーの課題を最も早く解消できます。

• 製品の操作をトリガーする（MFA のリセット、招待の再送、機能フラグの有効化）

• バックエンドでアカウントの状態を確認する

• Jira、Linear、Slack、Zendesk などのツールでワークフローを開始する

Embed 設定で定義したツールに加えて、アシスタントは 設定した MCP サーバーも使用できます を 設定 → AI & MCP.

ツールが実行される場所

ツールの execute 関数は、埋め込み統合と同じ環境で実行されます。

通常は、ユーザーのブラウザ内、つまりアプリの中で実行されることを意味します。

そのため、次のことができます：

• 自分のバックエンドエンドポイントを呼び出す

• アプリにすでに読み込まれているサードパーティ SDK を呼び出す（たとえば Intercom）

• モーダル、ディープリンク、製品内 UI を開く

クライアントサイドのコードに秘密情報を入れないようにしてください。代わりにバックエンドを呼び出しましょう。

ツールを追加する

ツールを定義する：

• 以下を通じて window.GitBook("configure", …) 用の script タグ 実装

• 以下の tools プロップを通じて Node.js/NPM package と React コンポーネント

ツールは embed ボタンとは異なります を設定すると.

• 使うもの を設定すると ユーザーがクリックするボタン用です。

• アシスタントにコードを選ばせて実行させたいときは、ツールを使います。

ツールテンプレート（招待メールの再送）

例を見てみましょう：

window.GitBook("configure", {
  tools: [
    {
      // ツールを名前と説明付きで登録します。
      name: "resend_invite",
      description:
        "ユーザーが招待メールを見つけられない、または期限切れだと言ったときに、招待メールを再送します。",

      // 入力スキーマは、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: "招待メールを再送しました。",
          },
        };
      },
    },
  ],
});

ツールの使われ方

ツールを登録すると、アシスタントはユーザーの質問とツールに基づいて、自動的にそれらを選択できます 説明.

必須フィールドが不足している場合、アシスタントは追加の質問を行うべきです。

追加すると confirmation、ツールが実行される前にユーザーの承認が必要です。

ツールのフィールド

• name：一意の識別子。

• 説明：アシスタント向けの「いつ使うか」のヒント。

• inputSchema：ツール入力用の JSON Schema。

• confirmation （任意）：ツール実行前に表示される確認ボタン。

• execute(input)：操作を実行する非同期関数。

  • 返す { output, summary }.

  • output はアシスタントに戻されます。

  • summary はユーザーに表示されます。

確認

使うもの confirmation は、ユーザーに操作の承認を求めたいときに使います。予期しない副作用を防ぐのに役立ちます。

confirmation 受け取るもの：

• ラベル （必須）：ボタンのテキスト。

• 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 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 コントロール（挨拶、提案、アクション）が必要ですか？こちらをご覧ください 埋め込みのカスタマイズ.