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

GitBook アシスタントにカスタムツールを使わせると、 [Docs Embed](/docs/documentation/ja-gitbook-documentation/docs-site/embedding.md) 実際の操作を実行できます。

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

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

一般的な例：

* ユーザーに代わってサポートチケットを作成または更新する
* あらかじめ入力したメッセージでサポートチャットを開き、サポートに引き継ぐ

  <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 設定で定義したツールに加えて、アシスタントは [設定した MCP サーバーも使用できます](/docs/documentation/ja-gitbook-documentation/ai-to/mcp-servers-for-published-docs.md) を **設定 → AI & MCP**.
{% endhint %}

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

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

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

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

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

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

### ツールを追加する

ツールを定義する：

* 以下を通じて `window.GitBook("configure", …)` 用の [script タグ](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/implementation/script.md) 実装
* 以下の `tools` プロップを通じて [Node.js/NPM](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/implementation/nodejs.md) package と [React](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/implementation/react.md) コンポーネント

{% hint style="info" %}
ツールは embed ボタンとは異なります **を設定すると**.

* 使うもの **を設定すると** ユーザーがクリックするボタン用です。
* アシスタントにコードを選ばせて実行させたいときは、ツールを使います。
  {% 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: "招待メールを再送しました。",
          },
        };
      },
    },
  ],
});
```

### ツールの使われ方

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

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

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

### ツールのフィールド

* `name`：一意の識別子。
* `説明`：アシスタント向けの「いつ使うか」のヒント。
* `inputSchema`：ツール入力用の JSON Schema。
* `confirmation` （任意）：ツール実行前に表示される確認ボタン。
* `execute(input)`：操作を実行する非同期関数。
  * 返す `{ output, summary }`.
  * `output` はアシスタントに戻されます。
  * `summary` はユーザーに表示されます。

#### 確認

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

`confirmation` 受け取るもの：

* `ラベル` （必須）：ボタンのテキスト。
* `icon` （任意）： [Font Awesome](https://fontawesome.com/search) アイコン名。

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

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

アシスタントに次のことを任せられます：

* 不足している詳細を収集する
* システムにチケットを作成する
* 前後関係をあらかじめ入力した状態で、人間のサポートチャネルを開く

#### テンプレート：あらかじめ入力したメッセージでサポートチャットを開く

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

```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" %}
これを常時表示される **サポートに連絡** アクションと組み合わせて、埋め込みサイドバーに表示してください。アクションは、以下に従って設定できます [埋め込みのカスタマイズ](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/customizing-docs-embed.md).
{% endhint %}

### 次のステップ

* 完全な embed API の全体像が必要ですか？こちらをご覧ください [API リファレンス](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/reference.md).
* もっと UI コントロール（挨拶、提案、アクション）が必要ですか？こちらをご覧ください [埋め込みのカスタマイズ](/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/customizing-docs-embed.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-site/embedding/configuration/creating-custom-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.