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

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

```
新商品を公開 ➡️ 公式サイトを自動更新 ➡️ メールマガジンを配信 ➡️ SNS で宣伝
```

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

```
受講者が講座の進捗を質問 ➡️ 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 やワンタイムトークンを削除し、[キーと認証情報の設定場所](#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 キーやトークンなどの認証情報は、サービス提供元から受け取った値をそのままヘッダーに入力してください。プラットフォームは独自の名前の `{{…}}` を置換しません。呼び出し時に代入されるのは特定の変数のみです。詳しくは[キーと認証情報の設定場所](#credentials)を参照してください。
* **例**：

  ```json
  {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Bearer サービス提供元のトークンをここに貼り付けてください",
    "Accept": "application/vnd.github.v3+json"
  }
  ```

{% hint style="info" %}
共通のキーを使う代わりに「現在の会話のユーザー」として API の認証を行う場合は、訪問者が Keycloak で Web Chat にログインするときに、会話プラットフォームで [Keycloak のログイン ID を引き継いでツールを呼び出す](/maiagent-user-guide/ja/build/choose-channel/web-chat.md#keycloak-token-passthrough) を有効にし、この API のホストを許可リストに追加してください。プラットフォームが `Authorization` ヘッダーに訪問者本人の Keycloak 認証情報を含めます。この場合、ヘッダー（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）はパラメータの内容（文字列）です。
* 値は固定のテキストにすることも、`{{パラメータ名}}` を使って「パラメータ構造」で宣言し、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 では `{パラメータ名}` を使って、URL のパス内で変化する部分を指定できます。たとえば `/users/{userId}/orders/{orderId}` です。Agent が指定した値を URL に代入するには、「パラメータ構造」で同じ名前のパラメータを定義し、その位置を「<mark style="color:blue;">パス</mark>」に設定する必要があります。リクエストを送信する前に、システムが値を URL エンコードしてから代入します。たとえば `A/B 01` は `A%2FB%2001` となり、値に含まれるスラッシュや空白が URL 構造を変えることはありません。

**利用シーン**：カスタマーサポートの責任者であるマイさんは、顧客番号と注文番号を使って、会社の注文 API から 1 件の注文を 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` は、毎回の呼び出しでこの 2 つの値を両方指定する必要があることを 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="ツール追加ダイアログの API URL に userId と orderId を含む 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 内の同名の `{パラメータ名}` に代入します                                                                     |
| <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}` のような名前では保存できません。
* `{パラメータ名}` は URL のパス部分に指定してください。クエリ文字列に入れる値は、パラメータの位置を「<mark style="color:blue;">クエリ</mark>」に設定するか、[Query パラメータ](#query-param-templates) で `{{パラメータ名}}` を使って参照してください。
* API URL では `{{変数}}` の二重波括弧構文を使用できません。保存時に「<mark style="color:blue;">エラー</mark>」ダイアログが開き、「パスパラメータには {identifier} 構文を使用してください。」と表示されます。API ツールでは、`{{パラメータ名}}` は「ヘッダー（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>」ボタンをクリックします。これで新しいツールの作成は完了です！

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

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

「Query パラメータ」の値に `{{パラメータ名}}` と記述すると、Agent がツールを呼び出す際に、MaiAgent が「パラメータ構造」の同名パラメータの値を代入してからリクエストを送信します。設定者が固定の構文を記述し、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.