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

# API ツールの作成

{% 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="/files/QrJMuAxI0k6cqJM5KWgn" 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="/files/Dtbu2ITmxAwIQqtry6QJ" 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="/files/y6WyDLvMQtHlKRUacnXQ" 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="/files/Wk7N6ES5wluOFu5AIZcK" 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="/files/ClTRZpQ7Ot2K2S34gm45" 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="/files/toQuUhlFLxnhCOyVJeWV" 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="/files/xA7EF7SieU3FcYVqQUDa" alt=""><figcaption></figcaption></figure>

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

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

<figure><img src="/files/gWQTHsC9u3Mw9UQ2zDoS" 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="/files/8ec58osAIBAnqPkbOSxS" alt="API ヘッダー設定のスクリーンショット"><figcaption><p>必要な HTTP リクエストヘッダーを設定する</p></figcaption></figure>

#### d. 🧩 パラメータスキーマ（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="/files/kTJsL14SYlSAAZGS0fKr" 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="/files/oXmYF9E3du2vBXqQN2eC" alt=""><figcaption></figcaption></figure>

## ⚠️ 重要な注意事項 <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/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.