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

アプリから呼び出せる任意のツール、特にサポート業務のワークフローに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 prop を通じて Node.js/NPM package と React コンポーネント

ツールは embed actions.

• 使用 actions ユーザーがクリックするボタンとは別のものです。

• Assistant にコードを選んで実行させたいときは、ツールを使います。

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

例を見てみましょう:

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: "招待メールを再送しました。",
          },
        };
      },
    },
  ],
});

ツールの使われ方

ツールを登録すると、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 サイドバーで使ってください。アクションは次の手順に従って設定できます Embed のカスタマイズ.

次のステップ

• 完全な embed API の範囲が必要ですか？こちらを参照してください API リファレンス.

• さらに UI コントロール（挨拶、提案、アクション）が欲しいですか？こちらを参照してください Embed のカスタマイズ.