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

カスタムツールを使うと、GitBook Assistant は [Docs Embed](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/ja-gitbook-documentation/publishing-documentation/embedding) の中で実際のアクションを実行できます。

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

アプリから呼び出せるなら、Assistant からも呼び出せます。

一般的な例:

* ユーザーの代わりにサポートチケットを作成または更新する
* 事前入力されたメッセージ付きのサポートチャットを開いてサポートへ引き継ぐ

  <div data-gb-custom-block data-tag="hint" data-style="success" class="hint hint-success"><p><strong>サポート引き継ぎ</strong> は、カスタムツールを使い始めるのに最適な方法です。ユーザーの詰まりを最も早く解消できます。</p></div>
* プロダクト操作をトリガーする（MFA のリセット、招待の再送、機能フラグの有効化）
* バックエンドでアカウントのステータスを確認する
* Jira、Linear、Slack、Zendesk などのツールでワークフローを開始する

{% hint style="info" %}
Embed 設定で定義したツールに加えて、Assistant は次のものも使用できます [設定した MCP サーバー](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/mcp-servers-for-published-docs) の **設定 → AI & MCP**.
{% endhint %}

### ツールが実行される場所

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

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

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

* 独自のバックエンドエンドポイントを呼び出す
* アプリにすでに読み込まれているサードパーティ SDK を呼び出す（たとえば Intercom）
* モーダル、ディープリンク、またはプロダクト内 UI を開く

{% hint style="warning" %}
クライアントサイドのコードに秘密情報を入れないでください。代わりにバックエンドを呼び出しましょう。
{% endhint %}

### ツールを追加する

ツールを定義する:

* 次を通じて `window.GitBook("configure", …)` の [script タグ](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/implementation/script) 実装
* 次の `tools` prop を通じて [Node.js/NPM](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/implementation/nodejs) package と [React](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/implementation/react) コンポーネント

{% hint style="info" %}
ツールは embed **actions**.

* 使用 **actions** ユーザーがクリックするボタンとは別のものです。
* Assistant にコードを選んで実行させたいときは、ツールを使います。
  {% endhint %}

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

例を見てみましょう:

```javascript
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](https://fontawesome.com/search) アイコン名。

### サポートワークフロー

サポートは、ツールの中で最も効果の高いユースケースです。

Assistant に次のことをさせられます:

* 不足している詳細を収集する
* システムにチケットを作成する
* コンテキストを事前入力した人間のサポートチャネルを開く

#### テンプレート: 事前入力メッセージ付きでサポートチャットを開く

人間へのスムーズな引き継ぎを行いたい場合に使います。

```javascript
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: "サポートに転送しました。" },
        };
      },
    },
  ],
});
```

{% hint style="info" %}
これを常に表示される **サポートに連絡** アクションと組み合わせて、embed サイドバーで使ってください。アクションは次の手順に従って設定できます [Embed のカスタマイズ](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/configuration/customizing-docs-embed).
{% endhint %}

### 次のステップ

* 完全な embed API の範囲が必要ですか？こちらを参照してください [API リファレンス](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/configuration/reference).
* さらに UI コントロール（挨拶、提案、アクション）が欲しいですか？こちらを参照してください [Embed のカスタマイズ](https://app.gitbook.com/s/NkEGS7hzeqa35sMXQZ4X/publishing-documentation/embedding/configuration/customizing-docs-embed).