> 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/build/tools/setup_api_tool.md).

# API ツールの作成

このガイドでは、プラットフォームで新しい API ツールを作成する手順を説明します。

{% hint style="info" %}
MaiAgent が作成した [ツール作成 Agent](https://chat.maiagent.ai/web-chats/27934296-105a-4f3f-80f0-7e9dcdb638d3) を利用すると、API ツールの作成を支援してもらえます
{% endhint %}

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

このページの内容：[API とは？](#what-is-api)｜[API ツールをすばやく作成する](#quick-create-api-tool)｜[Query パラメータで Agent のパラメータを参照する](#query-param-templates)｜[キーと認証情報の設定場所](#credentials)｜[⚠️ 重要な注意事項](#important-notes)

## **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 で注文状況を照会 ➡️ 配送の進捗を自動返信
```

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

```
新商品を公開 ➡️ 公式サイトを自動更新 ➡️ メールマガジンを配信 ➡️ ソーシャルプラットフォームで宣伝
```

**オンライン学習プラットフォーム：**

```
受講者が学習の進捗を質問 ➡️ API で学習履歴を照会 ➡️ 完了率と次回の受講日時を自動返信
```

API ツールを使うと、Agent は単なるチャットボットから、実際に業務フローを実行できるインテリジェントなアシスタントへと進化し、作業効率と自動化の水準を大幅に向上させます。

## 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> ボタンをクリックします。

### 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>」フィールドを設定します。

* **用途**：Agent が内部でツールを呼び出し、識別するための一意の識別子です。
* **命名規則（重要）**：
  * 英語を使用する必要があります。
  * 使用できるのは次の文字のみです：
    * 小文字の英字（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>」フィールドに、明確で詳しい説明を入力します。

* **重要性**：適切な説明があると、Agent は次の点をより正確に理解できます：
  * ツールの機能と目的。
  * このツールを使用すべきタイミング。
  * ツールの出力結果の解釈方法。
* **推奨する内容**：ツールの役割、入力と出力、使用上の注意事項を記載してください。
* **2 つの説明フィールド**：フォームの「<mark style="color:blue;">説明</mark>」は、メンバー向けにツール一覧に表示されます。「<mark style="color:blue;">プロンプト</mark>」には、Agent が参照する使用方法、パラメータの形式、注意事項を記載します。説明を書いたら、横の「<mark style="color:blue;">プロンプトに同期</mark>」を押すと、説明がプロンプト欄にコピーされます（説明が空の場合は「先に説明を入力してください」と表示されます）。それをもとに、Agent に必要な詳細を追記してください。

<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`
* **cURL の貼り付けで自動解析**：フィールドには「ブラウザーの DevTools からコピーした cURL を貼り付けられます」と表示されます。DevTools の Network パネルで対象リクエストの「Copy as cURL」を選び、このフィールドに直接貼り付けると、URL、ヘッダー、HTTP メソッドが解析され、対応するフィールドに自動入力されます（「cURL から URL、ヘッダー、HTTP メソッドを解析しました」と表示されます）。ツール追加ウィンドウを開いたとき、クリップボードに cURL コマンドがある場合も自動入力されます（ブラウザーによるクリップボードの読み取り許可が必要です）。cURL が未対応の HTTP メソッドを使用している場合も URL とヘッダーは入力されるため、メソッドは手動で選択してください。形式を解析できない場合は「cURL を解析できません。形式が正しいか確認してください」と表示されます。貼り付けた後は、ヘッダーに含まれる個人の Cookie や使い捨て token を削除し、[キーと認証情報の設定場所](#credentials)に従って変数を使用してください。

<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;">ヘッダー (JSON)</mark>」フィールドに、毎回のリクエストに含める HTTP ヘッダーを入力します。
* **形式**：有効な JSON オブジェクトである必要があります。キー（Key）はヘッダー名、値（Value）はヘッダーの内容（文字列）です。追加のヘッダーが不要な場合は `{}` のままにします。
* **キーは実際の値を直接入力してください**：API Key や Token などの認証情報は、サービス提供元から受け取った値をそのままヘッダーに入力します。プラットフォームは任意の名前の `{{…}}` を置き換えません。呼び出し時に代入されるのは特定の変数のみです。詳しくは[キーと認証情報の設定場所](#credentials)を参照してください。
* **例**：

  ```json
  {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Bearer サービス提供元の Token をここに貼り付けます",
    "Accept": "application/vnd.github.v3+json"
  }
  ```

{% hint style="info" %}
共通のキーではなく「現在の会話のユーザー」として API を認可するには、訪問者が Keycloak で Web Chat にログインする場合、会話プラットフォームで [Keycloak のログイン情報を引き継いでツールを呼び出す](/maiagent-user-guide/ja/build/choose-channel/web-chat.md#keycloak-token-passthrough)を有効にし、この API のホストを許可リストに追加します。プラットフォームは訪問者本人の Keycloak 認証情報を `Authorization` ヘッダーに付けて送信します。この場合、ヘッダー (JSON) で `Authorization` を設定しないでください。設定すると、その内容が優先されます。
{% endhint %}

**機密ヘッダー名**：ツール実行履歴には、各リクエストのヘッダーが記録されます。プラットフォーム標準の機密ヘッダー（`Authorization`、`Proxy-Authorization`、`X-API-Key`、`X-Auth-Token`、`Cookie`、`Set-Cookie`。読み取り専用の <mark style="color:blue;">プラットフォーム標準の機密 Headers</mark> に一覧表示されます）と、認証情報によって付与されるヘッダーは、常にマスク表示されます。API が別の独自のヘッダー名でキーを送る場合（例：`X-Client-Secret`）、<mark style="color:blue;">機密ヘッダー名</mark> に名前を入力して Enter を押すと追加できます。実行履歴を表示した際、そのヘッダーの値もマスクされます。名前は大文字と小文字を区別せず、完全一致が必要です。英字、数字、`- _ . ~` のみを使用でき、最大 50 件まで登録できます。設定は既存の履歴にも適用され、名前を削除すると元の値が再び表示されます。

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

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

* 「<mark style="color:blue;">利用可能なコンテキスト変数</mark>」をクリックすると、現在対応している変数（連絡先 ID、会話 ID、受信トレイ ID など）の一覧が開きます。
* **形式**：有効な JSON オブジェクトで、キー（Key）はパラメータ名、値（Value）はパラメータの内容（文字列）です。
* 値には固定のテキストを記入できるほか、`{{parameter_name}}` で「パラメータ構造」に宣言したパラメータを参照できます。Agent が呼び出し時に値を入力するため、「前半は固定、後半はユーザーが指定する」検索条件も設定だけで実現できます。詳しくは後述の [Query パラメータで Agent のパラメータを参照する](#query-param-templates)を参照してください。
* サービス提供元がクエリ文字列で API キーを渡すよう求めている場合は、API URL の `?` の後に直接書かず、ここに実際のキーの値を入力してください。ここで設定した値は、ツール実行履歴の「<mark style="color:blue;">リクエスト URL</mark>」には表示されません。詳しくは[これらの値を閲覧できる人](#credential-visibility)を参照してください。
* **例**：

  ```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>

**パラメータ構造は「注文用紙」のようなもの**で、API にどのデータを、どのように要求できるかを Agent に伝えます。

* **中心となる設定**：Agent がこのツールを呼び出す際に指定できる、または指定する必要があるパラメータ（システムの処理に渡す内容）と、その形式を定義します。
* **形式**：標準の **JSON Schema** 形式を使用します。
* **主な要素**：
  * `type: "object"`：パラメータがオブジェクトであることを示します。
  * `properties`：各パラメータを定義するオブジェクトです。
    * **パラメータ名**（例：`"search"`）：対応するオブジェクトに、そのパラメータの詳細を記述します。
      * `type`：パラメータのデータ型です（`string`, `integer`, `number`, `boolean`, `array`, `object`）。
      * `description`：パラメータの意味を Agent に説明します。
      * `default`（任意）：パラメータのデフォルト値です。
      * `enum`（任意）：値が特定の選択肢に限られる場合に、その候補を列挙します。
  * `required`：すべての**必須**パラメータ名を含む配列です。
* **キーを含めないでください**：パラメータ構造（`default` のデフォルト値を含みます）は、ツール定義として AI モデルに提供されます。API キーは「ヘッダー (JSON)」または「Query パラメータ (JSON)」に設定してください。
* **サンプルデータを貼り付けないでください**：パラメータは `properties` 内に記述します。`{"keyword": "string", "limit": 10}` のようなサンプルデータを直接貼り付けて「<mark style="color:blue;">確認</mark>」を押すと、「<mark style="color:blue;">エラー</mark>」が表示されます。この JSON Schema にフィールドが定義されていないことが説明され、`properties` に移動する必要があるキーが列挙されます。案内に従って修正してから保存してください。パラメータが不要なツールは、デフォルトの `{}` のまま保存できます。
* **例**（動画・音声検索ツール）：

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

#### f. パスパラメータとパラメータの位置 <a href="#path-parameters" id="path-parameters"></a>

API URL では、`{parameter_name}` を使って URL パス内の変化する部分を示せます。例：`/users/{userId}/orders/{orderId}`。Agent が指定した値を URL に代入するには、「パラメータ構造」に同じ名前のパラメータを定義し、その位置を「<mark style="color:blue;">パス</mark>」に設定する必要があります。リクエストを送信する前に、システムが値を URL エンコードしてから代入します。例えば `A/B 01` は `A%2FB%2001` になるため、値に含まれるスラッシュや空白で URL の構造が変わることはありません。

**利用シーン**：カスタマーサポート責任者のマイさんは、顧客番号と注文番号をもとに、社内の注文 API から Agent に個別の注文を照会させたいと考えています。API ツールを作成して 2 つの番号をパスパラメータに設定し、Agent にツールを割り当てます。同僚が会話で「顧客 customer-01 の注文 order-25 を照会して」と入力すると、Agent が 2 つの番号を URL の正しい位置に入れて照会します。注文番号が不足している場合、ツールはすぐに値の不足を報告し、不完全なリクエストは送信しません。

{% stepper %}
{% step %}

### パスパラメータを含む API URL を設定する <a href="#path-param-step-url" id="path-param-step-url"></a>

上記の「API ツールをすばやく作成する」に従ってツールを追加します。練習には公開の httpbin レスポンスサービスを使用し、<mark style="color:blue;">API URL</mark> を次のように設定できます：

```
https://httpbin.org/anything/users/{userId}/orders/{orderId}
```

1 つの URL に複数のパスパラメータを指定できます。入力すると、フィールドの下に「<mark style="color:blue;">検出されたパスパラメータ</mark>」が表示され、`userId, orderId` が列挙されます。パラメータ構造にこれらの名前が未定義の場合は、さらに赤字で「<mark style="color:blue;">パラメータ構造で定義してください</mark>」と表示されます。
{% endstep %}

{% step %}

### パラメータ構造に同じ名前のパラメータを宣言する <a href="#path-param-step-schema" id="path-param-step-schema"></a>

<mark style="color:blue;">パラメータ構造 (JSON Schema)</mark> に次を入力します：

```json
{
  "type": "object",
  "properties": {
    "userId": { "type": "string", "description": "顧客番号" },
    "orderId": { "type": "string", "description": "注文番号" }
  },
  "required": ["userId", "orderId"]
}
```

パラメータ名は、URL の波括弧内の名前と完全に一致する必要があります（大文字と小文字も一致させます）。`required` は、毎回の呼び出しで両方の値が必要であることを Agent に伝えます。

入力すると、パラメータ構造の下に各パラメータと位置の選択メニューが表示され、初期値は「<mark style="color:blue;">デフォルト</mark>」になります。この時点では、API URL の下に赤字で「<mark style="color:blue;">以下のパラメータの位置は「パス」ではないため、URL 内のプレースホルダーは置き換えられません</mark>」と表示されます。次の手順も必要です。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-fd22abf6d8d512da1b562b409257a40d152e10df%2Fapi-tool-path-params-url-hint.png?alt=media" alt="ツール追加ウィンドウで userId と orderId を含む API URL を入力し、その下に検出されたパスパラメータと、パラメータの位置がパスではないことを示す赤字の注意が表示されています"><figcaption><p>パラメータの位置が「デフォルト」のままだと、API URL の下に赤字で注意が表示されます</p></figcaption></figure>
{% endstep %}

{% step %}

### パラメータの位置を「パス」に設定する <a href="#path-param-step-location" id="path-param-step-location"></a>

パラメータ構造の下で、`userId` と `orderId` の位置の選択メニューを両方とも「<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-ab2269bc4657f0d2d3ef15768c7817fe6f923eb8%2Fapi-tool-path-params-location-menu.png?alt=media" alt="パラメータ構造の下で位置の選択メニューが開き、デフォルト、パス、クエリ、本文、ヘッダーの選択肢が表示されています"><figcaption><p>各パラメータの位置をメニューから選択できます</p></figcaption></figure>

選択すると、パラメータ構造に `"location": "path"` が自動追加され、API URL の下の赤字の注意も消えます。内容を確認し、「<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-a86225dedbfcf98430095438e3dee00c09eddcc4%2Fapi-tool-path-params-location-set.png?alt=media" alt="パラメータ構造の userId と orderId に location が path として追加され、下の 2 つの位置メニューもパスになっています"><figcaption><p>「パス」を選択すると、パラメータ構造にも location 設定が反映されます</p></figcaption></figure>

{% hint style="warning" %}
位置が「<mark style="color:blue;">デフォルト</mark>」のままのパラメータは URL に代入されません。Agent が値を指定しても URL 内の `{userId}` は値がない状態となり、ツールはエラーを返し、リクエストを送信しません。URL で使用するすべてのパラメータを必ず「<mark style="color:blue;">パス</mark>」に設定してください。
{% endhint %}
{% endstep %}

{% step %}

### Agent に割り当てて動作を確認する <a href="#path-param-step-test" id="path-param-step-test"></a>

[Agent にツールを設定する](/maiagent-user-guide/ja/build/tools/configure_tools.md)に従い、回答モードが Agent モードの Agent にツールを追加します。次に左側のナビゲーションから「<mark style="color:blue;">Agent マーケットプレイス</mark>」を開き、「<mark style="color:blue;">組織で作成</mark>」に切り替え、該当の Agent を選択して「顧客 customer-01 の注文 order-25 を照会して」と入力します。Agent がツールを呼び出すと、httpbin は実際に受け取ったリクエスト URL `https://httpbin.org/anything/users/customer-01/orders/order-25` を返します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-8fbf496275f08bf616b56673143a7aede4f364d3%2Fapi-tool-path-params-chat.png?alt=media" alt="Agent が顧客番号、注文番号、2 つの番号を代入したリクエスト URL を回答しています"><figcaption><p>Agent は 2 つの番号を URL に代入して照会します</p></figcaption></figure>

各呼び出しで実際に送信された URL を確認するには、左側のナビゲーションから「<mark style="color:blue;">AgentOps</mark>」→「<mark style="color:blue;">ツール実行履歴</mark>」を開きます。該当履歴の操作欄にある目のアイコンをクリックして「<mark style="color:blue;">詳細</mark>」を開き、「<mark style="color:blue;">リクエスト情報</mark>」の「<mark style="color:blue;">リクエスト URL</mark>」を確認します。下図は、スラッシュと空白を含む顧客番号（`A/B 01`）で呼び出した例です。値が URL エンコードされていることを確認できます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-42bb5fd57f4e3d8aa020f8499b1f77ef9dc246bd%2Fapi-tool-path-params-record.png?alt=media" alt="ツール実行履歴の詳細ウィンドウで、入力パラメータが A/B 01 と order#25、リクエスト URL の対応部分が A%2FB%2001 と order%2325 になっています"><figcaption><p>ツール実行履歴のリクエスト URL では、エンコードされたパスパラメータを確認できます</p></figcaption></figure>

練習が終わったら、公開のサンプル URL を自社の注文 API の URL に置き換えてください。
{% endstep %}
{% endstepper %}

**パラメータの位置の選択肢**

パラメータ構造の各パラメータに位置を設定し、呼び出し時に値をリクエストのどこに入れるかを指定できます：

| 位置                                     | 説明                                                                                           |
| -------------------------------------- | -------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">デフォルト</mark> | 従来の動作を維持します。GET はクエリ文字列、POST、PUT、PATCH は本文に値を入れます。DELETE は自動で値を含めないため、値を渡す場合は位置を明示的に選択してください |
| <mark style="color:blue;">パス</mark>    | API URL 内の同じ名前の `{parameter_name}` に代入します                                                    |
| <mark style="color:blue;">クエリ</mark>   | URL の疑問符の後のクエリ文字列に追加します                                                                      |
| <mark style="color:blue;">本文</mark>    | JSON 本文に入れます                                                                                 |
| <mark style="color:blue;">ヘッダー</mark>  | パラメータ名を HTTP ヘッダー名として送信します。「ヘッダー (JSON)」に同名のヘッダーが設定済みの場合（大文字と小文字は区別しません）、設定済みの内容が優先されます      |

位置を設定していない既存のツールは、従来の動作を維持します。

**パスパラメータの値が不足している場合はリクエストを送信しません**

呼び出し時に URL 内のパスパラメータのいずれかに値がない場合（Agent が指定していない、値が空、またはパラメータの位置が「パス」ではない場合）、ツールはすぐに停止し、「パスパラメータ {orderId} に今回の呼び出しの値がありません」と報告します。`{orderId}` を含んだ URL は送信しません。Agent は会話で照会が失敗した理由を説明します。「<mark style="color:blue;">ツール実行履歴</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-750f62d0eddb446a5a310c0f0df7ad282742b8c3%2Fapi-tool-path-params-missing.png?alt=media" alt="ツール実行履歴の詳細ウィンドウで、入力パラメータの orderId が null、リクエスト情報は空で、パスパラメータ orderId に今回の呼び出しの値がないことを示すエラーメッセージが表示されています"><figcaption><p>パスパラメータの値が不足している場合、ツールはリクエストを送信せず、エラーの理由を記録します</p></figcaption></figure>

**URL の記述に関する制限**

* パスパラメータ名には英字、数字、アンダースコアのみ使用でき、数字で始めることはできません。例：`{order_id}`。`{order-id}` のような名前では保存できません。
* `{parameter_name}` は URL のパス部分に配置してください。クエリ文字列で渡す値は、パラメータの位置を「<mark style="color:blue;">クエリ</mark>」にするか、[Query パラメータ](#query-param-templates)で `{{parameter_name}}` を使って参照してください。
* API URL では `{{variable}}` のような二重波括弧の構文は使用できません。保存時に「<mark style="color:blue;">エラー</mark>」が表示され、「パスパラメータは {identifier} 構文を使用する必要があります」と示されます。API ツールでは、`{{parameter_name}}` は「ヘッダー (JSON)」と「Query パラメータ (JSON)」で使用してください。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-2504b5ecf2e51c2e9bb2ac09e44dcde725120152%2Fapi-tool-path-params-invalid-syntax.png?alt=media" alt="画面上部に Request failed with status code 400 が表示され、中央のエラーダイアログに、パスパラメータは {identifier} 構文を使用する必要があると表示されています"><figcaption><p>API URL に二重波括弧が含まれていると保存できません</p></figcaption></figure>

Google Style REST のカスタムアクションでは、コロン以降の接尾辞をそのまま使用できます。例えば、Google Weather の照会は次のように記述します：

```
https://weather.googleapis.com/v1/currentConditions:lookup
```

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

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

ツール追加時に、<mark style="color:blue;">権限設定</mark> タブをまだ開いていない状態で <mark style="color:blue;">確認</mark> を押すと、その時点ではツールは作成されません。画面が自動で <mark style="color:blue;">権限設定</mark> に切り替わり、「先に権限設定を確認し、割り当てるロールを確認してから送信してください」と表示されます。<mark style="color:blue;">権限範囲のクイック選択</mark> で、このツールを利用できるメンバーのロールを確認します（デフォルトは <mark style="color:blue;">デフォルトロールを除外</mark> です）。もう一度 <mark style="color:blue;">確認</mark> を押すと作成できます。既存のツールを編集する場合、この確認は表示されません。

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

多くの外部 API では、検索条件が「固定の構文＋ユーザーが指定する値」を組み合わせた 1 つの文字列になっています。例えば、OData 形式の `$filter=ProductName eq 'Chai'` や、検索 API の `q=` パラメータです。このような API では、独立したパラメータではなく、固定の文字列に値を埋め込む必要があります。

「Query パラメータ」の値に `{{parameter_name}}` と記述すると、MaiAgent は Agent がツールを呼び出す際に「パラメータ構造」の同名パラメータの値を代入してから、リクエストを送信します。設定者が固定の構造を記述し、Agent は値の入力のみを担当するため、構文が正しいかどうかをモデルの判断に任せる必要がなくなります。

### 利用シーン <a href="#query-param-templates-use-case" id="query-param-templates-use-case"></a>

購買部門では、社内の Agent が「ある製品の現在の単価と在庫数はいくつですか」という質問に直接回答できるようにしたいと考えています。データソースは、社内の商品カタログシステムが提供する OData クエリサービスです。従来は、このような照会のために API ごとにプログラムを作成する必要がありました。現在は、購買担当者が API ツールを作成し、検索条件を `ProductName eq '{{product_name}}'` に設定して、そのツールを Agent に割り当てるだけで対応できます。同僚が会話で「Chai という製品の単価と在庫数はいくつですか」と質問すると、Agent は自動的に検索条件に `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 %}

### Agent が入力するパラメータをパラメータ構造で宣言する <a href="#query-param-step-schema" id="query-param-step-schema"></a>

<mark style="color:blue;">パラメータ構造 (JSON Schema)</mark> で `product_name` を宣言し、`description` で Agent に入力すべき内容を伝えます。

```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 %}

### Agent に割り当ててテストする <a href="#query-param-step-test" id="query-param-step-test"></a>

[Agent にツールを設定する](/maiagent-user-guide/ja/build/tools/configure_tools.md) に従って、回答モードが Agent モードの Agent にこのツールを追加し、保存します。次に、左側のナビゲーションから「<mark style="color:blue;">Agent マーケット</mark>」を開き、「<mark style="color:blue;">組織で作成</mark>」に切り替えて、その Agent を選択して会話を開始します。「Chai という製品の単価と在庫数を教えてください」と入力すると、Agent は「ツールを使用しました」と表示し、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="Agent が会話中にツールを使用して製品名、単価、在庫数を回答する画面"><figcaption><p>Agent はユーザーが指定した製品名を検索条件に挿入してから API を呼び出します</p></figcaption></figure>
{% endstep %}
{% endstepper %}

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

| ルール                          | 説明                                                                                                          |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **変数名はパラメータ構造と一致させる必要があります** | `{{product_name}}` は「パラメータ構造」の `properties` 内のパラメータ名に対応します。大文字と小文字も完全に一致させてください                             |
| **代入されるのは値のみです**             | テンプレートは Query パラメータの値にのみ適用されます。キー (Key) は変更されず、代入の対象になりません                                                  |
| **値はそのまま代入されます**             | パラメータ値は常に文字列としてそのまま代入され、数値変換は行われません。例えば、法人番号などの識別番号 `04595257` の先頭のゼロは保持されます                                |
| **値がない場合は呼び出しを中止します**        | Agent が今回の呼び出しでパラメータを指定しなかった場合（または値が空の場合）、ツールは不足しているパラメータを示すエラーで停止します。`{{product_name}}` をそのまま送信することはありません  |
| **コンテキスト変数を優先します**           | パラメータ名がコンテキスト変数（`contact_id`、`conversation_id` など）と同じ場合は、必ずコンテキスト変数の値を代入します。Agent が指定した値で上書きされることはありません     |
| **参照されたパラメータも個別に送信されます**     | テンプレートで参照されたパラメータも、従来どおり独立した 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="#credentials" id="credentials"></a>

API ツールには、独立したシークレット保管フィールドや、名前を自由に指定できるシークレット変数はありません。外部 API の呼び出しに必要なキーは、「Agent が誰の認証情報で呼び出すか」に応じて、次の場所に設定してください。

| 利用場面                                         | 保存先                                                                                                                                                       |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 組織全体で固定の API Key または Token を共有する場合           | ツールの「<mark style="color:blue;">ヘッダー (JSON)</mark>」に実際の値を直接入力します。サービスが query string のみを受け付ける場合は「<mark style="color:blue;">Query パラメータ (JSON)</mark>」に入力します |
| 連絡先ごとに自分の API Key または Token を使用する場合          | 連絡先の「<mark style="color:blue;">API 認証情報</mark>」タブに設定します。[連絡先ごとに個別のキーを使用する](#per-contact-api-credentials) を参照してください                                        |
| Keycloak で Web Chat にログインした訪問者本人の認証情報を使用する場合 | 対話プラットフォームの [Keycloak のログイン情報を引き継いでツールを呼び出す](/maiagent-user-guide/ja/build/choose-channel/web-chat.md#keycloak-token-passthrough) を参照してください               |
| サービスが OAuth によるログイン認可のみを受け付ける場合              | API ツールには OAuth 認可フローがありません。サービスが MCP サーバーを提供している場合は、[MCP ツールの OAuth コネクタ](/maiagent-user-guide/ja/build/tools/mcp-setup.md#oauth-connector) を使用してください    |

{% hint style="warning" %}
ブラウザーからコピーした cURL コマンドを「<mark style="color:blue;">API URL</mark>」に貼り付けると、コマンド内のヘッダーも「ヘッダー (JSON)」に取り込まれます。これには、ご自身の `Cookie` や `Authorization` が含まれることがあります。これらの値はすべての会話で共有される固定の認証情報になります。保存前に削除するか、このツール用にサービスから発行されたキーに置き換えてください。
{% endhint %}

### 置換される `{{…}}` 変数 <a href="#template-variables" id="template-variables"></a>

「ヘッダー (JSON)」と「Query パラメータ (JSON)」の値には `{{変数名}}` を使用でき、システムが呼び出しごとに置換します。置換される名前は次のものに限られます。

| 変数                                   | 代入される値                                                                                                |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `{{contact_id}}`                     | 連絡先 ID                                                                                                |
| `{{source_id}}`                      | ソース ID                                                                                                |
| `{{contact_name}}`                   | 連絡先名                                                                                                  |
| `{{conversation_id}}`                | 会話 ID                                                                                                 |
| `{{inbox_id}}`                       | 受信トレイ ID                                                                                              |
| `{{organization_id}}`                | 組織 ID                                                                                                 |
| `{{agent_slug}}`、`{{agent_version}}` | 公式の組み込み Agent 用です。組織で作成した Agent が呼び出す場合は常に空文字列になります                                                   |
| `{{パラメータ名}}`                         | 「パラメータ構造」で宣言したパラメータです。Agent が今回の呼び出しで指定した値を代入します。ルールは [代入ルール](#query-param-templates-rules) を参照してください |

* 変数名は大文字と小文字も完全に一致させる必要があり、波括弧内に空白は入れられません。`{{ contact_id }}` は置換されず、そのまま送信されます。
* 会話のコンテキスト変数に対応する値がない場合は空文字列が代入されます。例えば、連絡先のない会話の `{{contact_id}}` が該当します。
* その他の名前（独自に付けたキー変数名など）は置換されません。ツールの保存時に「<mark style="color:blue;">不明なテンプレート変数が含まれています</mark>」というエラーが表示されます。古いツールにこのような記述が残っていると、リクエストで `{{…}}` がそのまま送信され、認証に失敗します。実際のキーを入力して保存し直してください。
* 「API URL」と「パラメータ構造」では `{{…}}` を使用できません。

### 連絡先ごとに個別のキーを使用する <a href="#per-contact-api-credentials" id="per-contact-api-credentials"></a>

連絡先ごとに自分のアカウントで API を呼び出す場合（自分の注文を照会する場合など）は、ツールの「ヘッダー (JSON)」には共通ヘッダーのみを設定し、各連絡先に個別の認証情報を設定してください。

1. 「<mark style="color:blue;">連絡先</mark>」ページを開き、該当する連絡先を編集します（連絡先は作成・保存済みである必要があります）。
2. 「<mark style="color:blue;">API 認証情報</mark>」タブに切り替え、ツールの右側にある編集ボタンをクリックします。
3. 「<mark style="color:blue;">Headers（JSON 形式）</mark>」に、この連絡先のヘッダー（例：`{"Authorization": "Bearer この連絡先の Token"}`）を入力し、「<mark style="color:blue;">保存</mark>」をクリックします。

操作方法は [連絡先の MCP 認証情報の設定](/maiagent-user-guide/ja/build/tools/setup-contacts-mcp-credentials.md) と同じです。呼び出し時には、まずツールの「ヘッダー (JSON)」が適用され、その後、同名のヘッダーが連絡先の設定で上書きされます（名前の大文字と小文字はツールの設定と一致させる必要があります）。連絡先に設定がない場合はツールのヘッダーを使用します。連絡先の認証情報の値はそのまま送信され、`{{…}}` の置換は行われません。

### これらの値を閲覧できる範囲 <a href="#credential-visibility" id="credential-visibility"></a>

* **ツールの編集画面**：保存後、「ヘッダー (JSON)」と「Query パラメータ (JSON)」の値は、作成者本人にも平文では表示されません。編集画面を開き直すと、各値の先頭と末尾の 4 文字のみが表示され、中間は `****` に置き換えられます（8 文字以下の値は全体が `****` になります）。そのまま保存しても元の値は変更されません。項目を変更する場合は、その値全体を入力し直してください。マスクされた値が残っている項目は保存できません。
* **AI モデル**：ヘッダーと Query パラメータの値は AI モデルに渡されません。AI モデルが参照できるのは、ツール名、プロンプト（または説明）、パラメータ構造のみです。
* **ツール実行ログ**：「<mark style="color:blue;">AgentOps</mark>」→「<mark style="color:blue;">ツール実行ログ</mark>」の「<mark style="color:blue;">リクエスト情報</mark>」では、各呼び出しで実際に送信された「<mark style="color:blue;">リクエスト URL</mark>」と「<mark style="color:blue;">リクエスト Headers</mark>」を確認できます。
  * `Authorization`、`Proxy-Authorization`、`Cookie`、`Set-Cookie`、`X-API-Key`、`Api-Key`、`X-Auth-Token`、`X-Access-Token` という名前のヘッダー（大文字と小文字は区別しません）と、連絡先の「API 認証情報」で設定したヘッダーは、`***` と表示され、「<mark style="color:blue;">マスク済み</mark>」と示されます。
  * その他の名前のヘッダーは平文で表示されます。サービスが許可する場合は、上記の名前のヘッダーにキーを設定してください。
  * 「Query パラメータ (JSON)」に設定した値は「リクエスト URL」には表示されません。API のレスポンスやエラーメッセージにこれらの値が含まれる場合も、`***` に置き換えられます。
  * 「API URL」に直接記載した内容（`?` 以降のクエリ文字列を含みます）は「リクエスト URL」にそのまま表示されるため、キーを API URL に記載しないでください。

{% hint style="info" %}
練習用の httpbin は、受信したリクエストヘッダーをそのままレスポンスに含めます。このレスポンスは会話とツール実行ログに表示されます。テストには実際のキーを使用しないでください。
{% 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 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/maiagent-user-guide/ja/build/tools/setup_api_tool.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.