> 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/maiagent-user-guide/ja/tools/setup_api_tool.md).

# API ツールの作成

本ガイドでは、プラットフォーム上で新しい MCP ツールを作成する手順をご案内します。

{% hint style="info" %}
MaiAgent が提供する [ツール作成 AI アシスタント](https://chat.maiagent.ai/web-chats/27934296-105a-4f3f-80f0-7e9dcdb638d3) を利用して、API ツールの作成をサポートしてもらうことができます。
{% endhint %}

API ツールは、外部サービスとの連携や操作フローの自動化に使用します。

## **API とは？** <a href="#what-is-api" id="what-is-api"></a>

**API（Application Programming Interface、アプリケーションプログラミングインターフェース）** は、異なるソフトウェアシステム同士が通信するための橋渡し役です。簡単に言えば、**ソフトウェアの世界における「接客係」** のような存在で、異なるプログラム同士が情報をやり取りし、機能を実行するのを助けます。

レストランで食事をする場面を想像してみてください。

* **あなた**：食事を必要とするお客様（アプリケーション）
* **厨房**：料理を作る場所（サービスを提供するシステム）
* **接客係**：あなたと厨房の間でメッセージを伝える存在（**API**）

あなたが直接厨房に入る必要はなく、接客係に欲しいものを伝えるだけで、接客係がその要望を厨房に伝え、できあがった料理をあなたのもとへ運んでくれます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-affedbd5ccc8692a11a20ce5fc69a39886d0e2d3%2Fplayma%20(10)%20(1).png?alt=media" alt=""><figcaption><p>API フロー概念図</p></figcaption></figure>

API ツールは、標準化されたフローの自動操作や特定の返却フォーマットの設定をサポートするほか、お使いのシステム内の情報を取得することもできます。例えば次のようなケースです。

**EC カスタマーサポートの自動化**

```
顧客が注文を問い合わせ ➡️ API で注文ステータスを照会 ➡️ 配送状況を自動返信
```

**マーケティングキャンペーン管理**

```
新製品の公開 ➡️ 公式サイトを自動更新 ➡️ EDM を配信 ➡️ ソーシャルプラットフォームで宣伝
```

**オンライン講座プラットフォーム：**

```
受講生が進捗を問い合わせ ➡️ API で学習履歴を照会 ➡️ 完了率と次回の受講時間を自動返信
```

API ツールを活用することで、AI アシスタントは単なる対話ロボットから、実際に業務フローを実行できるインテリジェントなアシスタントへと進化し、業務効率と自動化のレベルを大幅に向上させます。

## API ツールをすばやく作成する <a href="#quick-create-api-tool" id="quick-create-api-tool"></a>

### 1. ツール管理画面に入る <a href="#step-1-enter-tool-management" id="step-1-enter-tool-management"></a>

まず、左側のナビゲーションバーから「<mark style="color:blue;">AI 機能</mark>」セクションに入り、「<mark style="color:blue;">🔧 ツール</mark>」をクリックします。ツール一覧ページに入ったら、右上の「<mark style="color:blue;">➕ ツールを追加</mark>」ボタンをクリックします。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-1849091665b669bc0c5964295e91459b75acbe42%2FMCP%E5%B7%A5%E5%85%B7.png?alt=media" alt="ツール一覧ページと追加ボタン"><figcaption><p>「➕ ツールを追加」をクリックして作成を開始</p></figcaption></figure>

### 2. ツールタイプを選択する <a href="#step-2-select-tool-type" id="step-2-select-tool-type"></a>

ツールタイプで API を選択します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-36d929d6f379aadbfe05520796e63d6f8fefaf4f%2FAPI%E5%B7%A5%E5%85%B7.png?alt=media" alt=""><figcaption></figcaption></figure>

### 3. 表示名を設定する <a href="#step-3-set-display-name" id="step-3-set-display-name"></a>

ツールにわかりやすい表示名を設定します。ここでは <mark style="color:blue;">google calendar</mark> と設定します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-1b6a8ebbc7b3900a46b0a20494b1c11c118fbe47%2FAPI%E5%B7%A5%E5%85%B7%20(2).png?alt=media" alt=""><figcaption></figcaption></figure>

* **用途**：この名前はプラットフォームの画面に表示され、すべてのユーザーが確認できます。
* **おすすめ**：ツールの主な機能を明確に表せる名前を選ぶと、ユーザーが理解しやすくなります。この名前に厳密なフォーマットの制限はありません。

### 4. ツール名を設定する <a href="#step-4-set-tool-name" id="step-4-set-tool-name"></a>

次に「<mark style="color:blue;">ツール名</mark>」欄を設定します。

* **用途**：この名前は、AI アシスタントが内部でこのツールを呼び出し、識別する際に使用する一意の識別子です。
* **命名規則（重要）**：
  * 英語を使用する必要があります。
  * 使用できる文字は次のとおりです。
    * 半角英小文字（a-z）
    * 半角英大文字（A-Z）
    * 数字（0-9）
    * アンダースコア（`_`）
    * ハイフン（`-`）
  * **例**：`get_weather_forecast`、`database-query-tool`

下図では <mark style="color:blue;">google\_calendar\_retriever</mark> と設定しています。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-e60b90c068677f55f73f007d3f191a41bc3a9e5f%2FAPI%E5%B7%A5%E5%85%B7%20(4).png?alt=media" alt=""><figcaption><p>API ツール名の定義</p></figcaption></figure>

### 5. ツールの説明を記述する <a href="#step-5-write-tool-description" id="step-5-write-tool-description"></a>

「<mark style="color:blue;">ツールの説明</mark>」欄では、ツールについての明確で詳細な説明を入力できます。

* **重要性**：適切な説明は、AI アシスタントが次の点をより正確に理解するのに役立ちます。
  * ツールの機能と目的。
  * いつこのツールを使用すべきか。
  * ツールの出力結果をどう解釈するか。
* **おすすめの内容**：ツールが何をするか、何を入力するか、何を出力するか、そして使用上の注意点を記述します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-61fe2994e26226077604c4865223522621a0c39c%2FAPI%E5%B7%A5%E5%85%B7%20(5).png?alt=media" alt=""><figcaption><p>ツールの説明</p></figcaption></figure>

### 6. API 構成の詳細設定 <a href="#step-6-api-configure-details" id="step-6-api-configure-details"></a>

#### a. 🔗 API URL <a href="#api-url" id="api-url"></a>

* 対象となる API エンドポイントの完全な URL（`http://` または `https://` を含む）を入力します。
* **例**：`https://api.opencalendar.org/data/2.5`

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-7c8ec1446f411f007db93eecab4a2de07ee8036e%2FAPI%E5%B7%A5%E5%85%B7%20(6).png?alt=media" alt=""><figcaption></figcaption></figure>

#### b. 📮 HTTP メソッド <a href="#http-method" id="http-method"></a>

* ドロップダウンメニューから、API サービスが要求する HTTP 動詞を選択します。
  * `GET`：通常、リソースの取得に使用します。
  * `POST`：通常、新しいリソースの作成やデータの送信に使用します。
  * `PUT`：通常、リソースの完全な置き換えや更新に使用します。
  * `DELETE`：通常、リソースの削除に使用します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-a96418d1f33a03fb89d7c99d75cbff4200fa5851%2FAPI%E5%B7%A5%E5%85%B7%20(8).png?alt=media" alt=""><figcaption></figcaption></figure>

#### c. 📰 ヘッダー（Headers） <a href="#headers" id="headers"></a>

ヘッダーは手紙の「<mark style="color:blue;">封筒</mark>」のようなもので、実際のデータ内容を見る前に、受信側へいくつかの重要な情報を先に伝えます。**正しいヘッダーがないと、API リクエストが認証を通過できなかったり、受信側がデータを正しく解析できなかったりすることがあります。**

**よくある用途**：

* 認証（`Authorization`、`X-API-Key`）
* コンテンツタイプの指定（`Content-Type`）
* 受け入れるレスポンス形式の指定（`Accept`）

ヘッダーを追加するには、次の操作を行います。

* 「<mark style="color:blue;">➕ ヘッダーを追加</mark>」をクリックして、リクエストとともに送信する HTTP ヘッダーを定義します。
* **フォーマット**：有効な JSON オブジェクトである必要があります。キー（Key）はヘッダー名、値（Value）はヘッダーの内容（文字列）です。
* **例**：

  ```json
  {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Bearer {{SECRET_API_TOKEN}}",
    "Accept": "application/vnd.github.v3+json"
  }
  ```

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-6d67f75950755371440b5dcd1a50016f36259224%2FAPI%E5%B7%A5%E5%85%B7%20(9).png?alt=media" alt="API ヘッダー設定のスクリーンショット"><figcaption><p>必要な HTTP リクエストヘッダーを設定する</p></figcaption></figure>

#### d. 🔎 Query パラメータ（Query Params） <a href="#query-params" id="query-params"></a>

Query パラメータは、URL の疑問符の後ろに付加するクエリ文字列（例：`?format=json&limit=10`）で、呼び出すたびにリクエストとともに送信されます。固定の検索条件や、query string 経由でのみ渡せる API キーに適しています。

* 「<mark style="color:blue;">利用可能なコンテキスト変数</mark>」をクリックすると、現在サポートされている変数の一覧（連絡先 ID、会話 ID、受信トレイ ID など）を展開できます。
* **フォーマット**：有効な JSON オブジェクトで、キー（Key）はパラメータ名、値（Value）はパラメータの内容（文字列）です。
* 値には固定テキストを記述するほか、`{{パラメータ名}}` を使って、「パラメータスキーマ」で宣言し、AI アシスタントが呼び出し時に入力するパラメータを参照できます。これにより、「前半は固定、後半はユーザーが提供」という検索条件を設定だけで実現できます。詳細は下記の [Query パラメータで AI アシスタントのパラメータを参照する](#query-param-templates) を参照してください。
* **例**：

  ```json
  {
    "$format": "json",
    "$filter": "ProductName eq '{{product_name}}'"
  }
  ```

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-a0552130721b327022bc32313554617846bf0bf7%2Fapi-tool-query-params.png?alt=media" alt="ツール設定画面の Query パラメータ欄で、値に {{product_name}} を使ってパラメータを参照している"><figcaption><p>Query パラメータ欄と「利用可能なコンテキスト変数」の一覧</p></figcaption></figure>

#### e. 🧩 パラメータスキーマ（Parameters Schema） <a href="#parameters-schema" id="parameters-schema"></a>

**パラメータスキーマは「注文票」のようなもの** で、AI アシスタントに対して、API にどのようなデータを要求できるか、そしてどのように要求するかを伝えます。

* **コア設定**：AI アシスタントがこのツールを呼び出す際に、提供できる、または提供しなければならないパラメータ（システムに渡して処理させる内容）と、それらのパラメータのフォーマットを定義します。
* **フォーマット**：標準的な **JSON Schema** 形式を使用します。
* **主要な要素**：
  * `type: "object"`：パラメータがオブジェクトであることを示します。
  * `properties`：各パラメータを定義するオブジェクトです。
    * **パラメータ名**（例：`"search"`）：対応するオブジェクトには、そのパラメータの詳細が含まれます。
      * `type`：パラメータのデータ型（`string`、`integer`、`number`、`boolean`、`array`、`object`）。
      * `description`：AI アシスタントへの説明で、このパラメータの意味を解説します。
      * `default`（任意）：パラメータのデフォルト値。
      * `enum`（任意）：パラメータの値が特定のいくつかの選択肢のみに限定される場合、ここに列挙します。
  * `required`：すべての**必須**パラメータ名を含む配列です。
* **例**（動画検索ツール）：

  ```json
  {
      "type": "object",
      "properties": {
          "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "返却する結果件数の上限"
          },
          "fields": {
              "type": "string",
              "description": "カンマ区切りのフィールド一覧"
          },
          "search": {
              "type": "string",
              "description": "検索キーワード"
          }
      },
      "required": ["search"]
  }
  ```

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-5932120820f0a885644b441bac5c63a4492ae567%2FAPI%E5%B7%A5%E5%85%B7%20(11).png?alt=media" alt="API パラメータスキーマ設定のスクリーンショット"><figcaption><p>JSON Schema を使って API パラメータを正確に定義する</p></figcaption></figure>

### 7. 💾 ツールを保存する <a href="#step-7-save-tool" id="step-7-save-tool"></a>

すべての設定に誤りがないことを確認したら、ページの一番下までスクロールし、「<mark style="color:blue;">確認</mark>」ボタンをクリックします。これで新しいツールの作成は完了です！

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-eb2d956da69f2a187bf9f57c4cc86d0a07c2de73%2FAPI%E5%B7%A5%E5%85%B7%20(13).png?alt=media" alt=""><figcaption></figcaption></figure>

## Query パラメータで AI アシスタントのパラメータを参照する <a href="#query-param-templates" id="query-param-templates"></a>

多くのサードパーティ API では、OData 形式の `$filter=ProductName eq 'Chai'` や検索 API の `q=` パラメータのように、「固定構文＋ユーザーが提供する値」で構成される 1 つの文字列を検索条件として使用します。このような API が必要とするのは独立したパラメータではなく、値を固定文字列に組み込んだものです。

「Query パラメータ」の値に `{{パラメータ名}}` と記述すると、AI アシスタントがツールを呼び出す際に、MaiAgent が「パラメータスキーマ」内の同名パラメータの値を代入してからリクエストを送信します。設定者が固定の枠組みを作成し、AI アシスタントは値の入力だけを担当するため、構文の正しさをモデルの判断に委ねずに済みます。

### 利用シナリオ <a href="#query-param-templates-use-case" id="query-param-templates-use-case"></a>

購買部門で、社内の AI アシスタントが「特定の製品の現在の単価と在庫はいくらですか？」という質問に直接回答できるようにしたいとします。データソースは社内の製品カタログシステムが提供する OData クエリサービスです。従来、このような検索には API ごとにプログラムを作成する必要がありました。現在は、購買担当者が API ツールを作成し、検索条件を `ProductName eq '{{product_name}}'` と記述して AI アシスタントに設定するだけです。同僚が会話で「Chai の単価と在庫はいくらですか？」と尋ねると、AI アシスタントは自動的に `Chai` を検索条件に入力し、API を呼び出して、製品名、単価、在庫を回答します。

### 設定手順 <a href="#query-param-templates-steps" id="query-param-templates-steps"></a>

以下では公開されている Northwind サンプルデータサービス（OData）を使用するため、そのまま手順を実行できます。

{% stepper %}
{% step %}

### ツールを作成して基本情報を入力する <a href="#query-param-step-basic" id="query-param-step-basic"></a>

上記の「API ツールをすばやく作成する」の手順に従って API ツールを追加し、表示名（例：<mark style="color:blue;">製品価格検索</mark>）、ツール名 `product_price_lookup`、説明、プロンプトを入力します。また、<mark style="color:blue;">API URL</mark> を次のように設定します。

```
https://services.odata.org/V4/Northwind/Northwind.svc/Products
```

<mark style="color:blue;">HTTP メソッド</mark> は `GET` のままにします。
{% endstep %}

{% step %}

### AI アシスタントが入力するパラメータをパラメータスキーマで宣言する <a href="#query-param-step-schema" id="query-param-step-schema"></a>

<mark style="color:blue;">パラメータスキーマ（JSON Schema）</mark> で `product_name` を宣言し、`description` を使って AI アシスタントに入力内容を伝えます。

```json
{
  "type": "object",
  "properties": {
    "product_name": {
      "type": "string",
      "description": "Chai などの完全な英語の製品名"
    }
  },
  "required": ["product_name"]
}
```

{% endstep %}

{% step %}

### Query パラメータの値でパラメータを参照する <a href="#query-param-step-template" id="query-param-step-template"></a>

<mark style="color:blue;">Query パラメータ（JSON）</mark> に固定のクエリ構造を入力し、値の中で `{{product_name}}` を使って先ほど宣言したパラメータを参照します。

```json
{
  "$format": "json",
  "$select": "ProductID,ProductName,UnitPrice,UnitsInStock",
  "$filter": "ProductName eq '{{product_name}}'"
}
```

「<mark style="color:blue;">確認</mark>」をクリックしてツールを保存します。
{% endstep %}

{% step %}

### AI アシスタントに設定してテストする <a href="#query-param-step-test" id="query-param-step-test"></a>

[AI アシスタントにツールを設定する](/maiagent-user-guide/ja/tools/configure_tools.md) に従い、このツールを Agent モードの AI アシスタントに追加して保存します。次に、左側のナビゲーションバーから「<mark style="color:blue;">Agent マーケットプレイス</mark>」を開き、「<mark style="color:blue;">組織が作成</mark>」に切り替え、該当する AI アシスタントをクリックして会話を開始します。「Chai の単価と在庫はいくらですか？」と入力すると、AI アシスタントは「ツールを使用済み」と表示し、Chai の単価と在庫を回答します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-d301cae503ac598952cb9c0c4ef494c0b8bae727%2Fapi-tool-query-params-chat.png?alt=media" alt="AI アシスタントが会話中にツールを使用し、製品名、単価、在庫を回答している"><figcaption><p>AI アシスタントがユーザーの入力した製品名を検索条件に代入してから API を呼び出す</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 代入ルール <a href="#query-param-templates-rules" id="query-param-templates-rules"></a>

| ルール                            | 説明                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **変数名はパラメータスキーマと一致させる必要があります** | `{{product_name}}` は、「パラメータスキーマ」内の `properties` にあるパラメータ名に対応し、大文字と小文字は区別されます。                                      |
| **値のみが代入されます**                 | テンプレートは Query パラメータの値にのみ適用されます。キー（Key）は変更されず、代入も行われません。                                                            |
| **値は原文のまま代入されます**              | パラメータの値は常にリテラルテキストとして代入され、数値変換は行われません。例えば、法人番号 `04595257` の先頭の 0 は保持されます。                                          |
| **値がない場合は中止されます**              | AI アシスタントが今回の呼び出しで該当パラメータを提供していない場合（または値が空の場合）、ツールはエラーで中止し、不足しているパラメータを示します。`{{product_name}}` がそのまま送信されることはありません。 |
| **コンテキスト変数が優先されます**            | パラメータ名が `contact_id` や `conversation_id` などのコンテキスト変数と同じ場合は、常にコンテキスト変数の値が代入され、AI アシスタントが提供した値で上書きすることはできません。        |
| **参照されたパラメータも同時に送信されます**       | テンプレートで参照したパラメータも、従来の動作どおり独立した query パラメータとして送信されます（例：`product_name=Chai` も同時に送信されます）。ほとんどの API では余分なパラメータは無視されます。 |
| **パラメータ名はそのまま保存されます**          | Query パラメータのキーにアンダースコアや大文字（例：`Business_Accounting_NO`）が含まれていても、そのまま保存され、システムによる書き換えは行われません。                        |

{% hint style="info" %}
「<mark style="color:blue;">ヘッダー（JSON）</mark>」の値でも、パラメータスキーマ内のパラメータを `{{パラメータ名}}` で参照できます。ルールは Query パラメータと同じです。
{% endhint %}

{% hint style="warning" %}
`{{ }}` を含まない既存のツール設定には一切影響ありません。旧ツールの Query パラメータ名がシステムによって書き換えられていた場合（例：`Business_Accounting_NO` が `business__accounting_no` に変更されていた場合）は、そのツールを開き直し、名前を正しい表記に戻して保存してください。編集画面を開き直すと Query パラメータの値は `****` でマスク表示されますが、そのまま保存しても元の値は失われません。
{% endhint %}

## ⚠️ 重要な注意事項 <a href="#important-notes" id="important-notes"></a>

**接続テスト**

* ツールを作成したら、まず API が正常に動作するかをテストすることをおすすめします。
* 以下のようなテストツールを使って、ツールの機能を検証できます。
  * POSTMAN
  * 企業が独自に構築した API テストリクエストプラットフォーム

**権限管理**

* ツールの使用状況や権限の開放状態を定期的に確認しましょう。


---

# 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 dynamically by asking a question.

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

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/tools/setup_api_tool.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.