> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/preparation/client-tools.md).

# クライアントツール（Client Tools）

アプリケーション側で実行するツール（社内ネットワークからのみアクセスできるシステムへの問い合わせなど）を AI アシスタントから呼び出す方法を説明します。対話 API でのクライアントツールの宣言、モデルからの呼び出し要求の識別、実行結果の返送、モデルによるタスクの継続を扱います。

クライアントツールを使うと、AI アシスタントが「アプリケーション内で実行する」ツールを呼び出せます。対話 API を呼び出すたびにツール一覧を宣言します。モデルがツールを必要と判断すると、MaiAgent は自ら実行せず、「呼び出すツールと引数」を返します。アプリケーションがローカルで実行し、その結果を対話に返すと、モデルは結果に基づいて回答を続けたり、次のツールを呼び出したりします。

社内ネットワークからのみアクセスできるシステムへの問い合わせ、ブラウザ拡張機能による現在開いているページの操作、アプリによるユーザーのデバイス上のリソースへのアクセスなど、アプリケーション側でしか実行できない操作に適しています。

## 利用例 <a href="#scenario" id="scenario"></a>

ある EC 企業のエンジニアが、社内のカスタマーサポート用コンソールに AI アシスタントを組み込みます。注文システムには社内ネットワークからのみアクセスできます。担当者がコンソールで「お客様から注文 A1024 の到着予定について質問されています」と入力すると、コンソールは対話 API の呼び出し時に「注文照会」ツールも宣言します。モデルが照会する注文を返し、コンソールが社内ネットワークで発送状況を調べて同じ対話に返すと、モデルはその情報を基にお客様への回答を作成します。注文システムを外部に公開する必要はなく、コンソールはモデルに必要なデータだけを送信します。

## 利用条件 <a href="#requirements" id="requirements"></a>

クライアントツールはすべての組織で利用でき、別途申請は不要です。モデルが呼び出すには、次の両方の条件を満たす必要があります。

* AI アシスタントの <mark style="color:blue;">回答モード</mark> が <mark style="color:blue;">Agent モード</mark> であること
* AI アシスタントが使用するモデルがツール呼び出しに対応していること

{% hint style="warning" %}
上記の条件を満たさない場合、API はエラーを返さず、宣言したクライアントツールを**そのまま無視**し、モデルはツールを使わずに回答します。モデルがツールをまったく呼び出さない場合は、まずアシスタントの回答モードとモデルを確認してください。
{% endhint %}

## 動作の流れ <a href="#flow" id="flow"></a>

{% stepper %}
{% step %}

### ツールを宣言してメッセージを送信する <a href="#declare" id="declare"></a>

`POST /api/v1/chatbots/{chatbotId}/completions/` を呼び出し、`message.clientTools` にツール定義を指定します。
{% endstep %}

{% step %}

### ツール呼び出し要求を受け取る <a href="#receive-call" id="receive-call"></a>

モデルがツールの呼び出しを決定すると、レスポンスの `contentPayload.items` に `type` が `client_tool_call` の項目が含まれ、**そのターンは直ちに終了します**。
{% endstep %}

{% step %}

### アプリケーションでツールを実行する <a href="#run-tool" id="run-tool"></a>

`name` と `input` に従って、該当するツールを実行します。
{% endstep %}

{% step %}

### 同じ対話に結果を返す <a href="#send-result" id="send-result"></a>

同じ `conversation` を指定して対話 API をもう一度呼び出し、実行結果を `message.content` に記述し、**再び `clientTools` を含めます**。モデルは回答を続けます。他のツールが必要な場合はステップ 2 に戻り、最終的なテキストを返すまで繰り返します。
{% endstep %}
{% endstepper %}

## ツールの宣言 <a href="#tool-definition" id="tool-definition"></a>

```json
{
  "conversation": "<対話 ID。最初のメッセージでは省略可能>",
  "isStreaming": false,
  "message": {
    "content": "お客様から注文 A1024 の到着予定について質問されています。",
    "clientTools": [
      {
        "name": "get_order",
        "description": "注文番号を基に、注文の発送状況と到着予定日を照会します",
        "inputSchema": {
          "type": "object",
          "properties": {
            "order": { "type": "string", "description": "注文番号" }
          },
          "required": ["order"]
        }
      }
    ]
  }
}
```

| フィールド       | 型      | 説明                                                                     |
| ----------- | ------ | ---------------------------------------------------------------------- |
| name        | string | ツール名です。英数字、アンダースコア `_`、ハイフン `-` のみ使用でき、長さは 1–64 文字です。同じリクエスト内で重複できません。 |
| description | string | ツールの用途の説明です。モデルはこれを基に使用タイミングを判断するため、明確に記述してください。                       |
| inputSchema | object | ツールの引数を定義する JSON Schema です。シリアライズ後の長さは 4,000 文字以内である必要があります。           |

{% hint style="info" %}

* 1 回のリクエストで宣言できるクライアントツールは最大 20 個です。
* ツール一覧は**そのリクエストだけ**で有効で、対話には保存されません。以降の各メッセージ（ツールの結果を返すメッセージを含む）にも `clientTools` を再び指定する必要があります。指定しない場合、そのターンではモデルがツールを呼び出せません。
  {% endhint %}

## ツール呼び出し要求の形式 <a href="#tool-call-format" id="tool-call-format"></a>

モデルがツール呼び出しを要求すると、`contentPayload.items` に次のような項目が含まれます。一度に複数含まれる場合もあります。

```json
{
  "type": "client_tool_call",
  "toolCallId": "call_abc123",
  "name": "get_order",
  "input": { "order": "A1024" },
  "startTimestamp": "2026-10-01T08:30:00.000000+00:00"
}
```

| フィールド          | 型              | 説明                                      |
| -------------- | -------------- | --------------------------------------- |
| type           | string         | 常に `client_tool_call` です。               |
| toolCallId     | string \| null | モデルが生成した呼び出し識別子です。                      |
| name           | string         | 実行するツール名です。宣言した `name` に対応します。          |
| input          | object         | モデルが指定した引数です。宣言した `inputSchema` に対応します。 |
| startTimestamp | string \| null | 呼び出しの開始時刻です。                            |

### 非ストリーミングとストリーミングの違い <a href="#streaming" id="streaming"></a>

* **非ストリーミング**（`isStreaming: false`）：ツール呼び出し項目はレスポンス本体（`done: true`）の `contentPayload.items` に含まれます。
* **ストリーミング**（`isStreaming: true`）：ツール呼び出し項目は独立したイベントとして送信されます。そのイベントの `done` は `false`、`content` は空文字列で、`contentPayload.items` に `client_tool_call` が含まれます。最後の `done: true` イベントではこれらの項目が再送されないため、ストリーミング中に収集してください。

{% hint style="warning" %}
レスポンスのフィールド名はすべて camelCase に変換され、`input` 内の引数名も変換されます。例えば、`inputSchema` で定義した `order_id` は、`input` では `orderId` になります。引数名には小文字の英単語 1 語（`order`、`keyword` など）を使うか、解析時に両方の表記を受け付けることを推奨します。
{% endhint %}

## 実行結果の返送 <a href="#return-result" id="return-result"></a>

現在、「ツール結果の送信」専用のエンドポイントはありません。**同じ対話**で次の通常メッセージを送り、結果を `message.content` に記述してください。

```json
{
  "conversation": "<同じ対話 ID>",
  "isStreaming": false,
  "message": {
    "content": "ツール get_order（toolCallId: call_abc123）の実行結果：\n<照会結果>",
    "clientTools": [ "...前回と同じツール定義..." ]
  }
}
```

* **一度に複数のツール呼び出しがある場合**：すべての実行が完了したら、各ツールの結果を 1 つのメッセージにまとめて返します。
* **ツール名と `toolCallId` を記載する**：バックエンドは `toolCallId` を照合に使いませんが、結果のテキストに記載すると、モデルがどの呼び出しの結果かを判断しやすくなります。
* **実行失敗やユーザーによる拒否**：同様にテキストで説明します。例えば「get\_order の実行に失敗しました：該当する注文がありません」や「ユーザーがこの操作の実行を拒否しました」と記述すると、モデルは回答を調整したり、別の方法を使ったりします。
* **結果の長さ**：返した内容はモデルの入力に含まれます。データ量が多い場合は、必要な部分を先に抽出してください。

## 複数ターンでの連続ツール呼び出し <a href="#multi-step" id="multi-step"></a>

「モデルが呼び出しを要求する → 結果を返す」という 1 回の流れが 1 ターンです。モデルは複数ターンにわたってツールを呼び出し、レスポンスに `client_tool_call` が含まれなくなると、最終的なテキストを返します。異常時の無限ループを防ぐため、アプリケーションでターン数の上限を設定することを推奨します。

## よくある質問 <a href="#faq" id="faq"></a>

<details>

<summary>モデルがツールをまったく呼び出しません</summary>

まず、アシスタントの回答モードが Agent モードで、モデルがツール呼び出しに対応していることを確認してください。条件を満たさない場合はツールが無視され、エラーは返りません。次に、`description` に用途と使用タイミングが明確に記述されているか、メッセージに `clientTools` が含まれているかを確認してください。

</details>

<details>

<summary>結果を返すと、モデルがツールを使えないと言います</summary>

結果を返すメッセージにも `clientTools` を含める必要があります。ツール一覧は、そのリクエストだけで有効です。

</details>

<details>

<summary>400 エラーが返ります</summary>

ツール定義を確認してください。`name` が英数字、アンダースコア、ハイフンのみで構成され、重複していないこと、`description` が文字列であること、`inputSchema` がオブジェクトでシリアライズ後の長さが 4,000 文字以内であること、ツール数が 20 個以下であることを確認します。

</details>


---

# 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://docs.maiagent.ai/api/ja/preparation/client-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.
