> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/embedding/configuration/creating-custom-tools.md).

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

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

カスタムツールを使うと、GitBook アシスタントはその中で [Docs Embed](/docs/documentation/ja-gitbook-documentation/publish/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-for-your-readers/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/publish/embedding/implementation/script.md) 実装
* 〜を通じて `tools` 〜の prop を通じて [Node.js/NPM](/docs/documentation/ja-gitbook-documentation/publish/embedding/implementation/nodejs.md) パッケージおよび [React](/docs/documentation/ja-gitbook-documentation/publish/embedding/implementation/react.md) コンポーネント

{% hint style="info" %}
ツールは埋め込みと同じものではありません **actions**.

* 使用 **actions** ユーザーがクリックするボタン用です。
* アシスタントにコードを選ばせて実行させたいときにツールを使います。
  {% 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` 受け取るもの：

* `label` （必須）：ボタンのテキスト。
* `アイコン` （任意）： [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 アシスタントを閉じる
        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/publish/embedding/configuration/customizing-docs-embed.md).
{% endhint %}

### 次のステップ

* 埋め込み API の全体像が必要ですか？次を参照してください。 [API リファレンス](/docs/documentation/ja-gitbook-documentation/publish/embedding/configuration/reference.md).
* さらに UI コントロール（挨拶、候補、アクション）が必要ですか？次を参照してください。 [埋め込みのカスタマイズ](/docs/documentation/ja-gitbook-documentation/publish/embedding/configuration/customizing-docs-embed.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.