API ツールの作成

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

MaiAgent が提供するツール作成 AI アシスタントを利用して、API ツールの作成をサポートしてもらうことができます。

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

API とは？

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

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

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

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

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

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

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

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

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

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

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

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

API ツールをすばやく作成する

1. ツール管理画面に入る

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

2. ツールタイプを選択する

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

3. 表示名を設定する

ツールにわかりやすい表示名を設定します。ここでは google calendar と設定します。

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

4. ツール名を設定する

次に「ツール名」欄を設定します。

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

下図では google_calendar_retriever と設定しています。

5. ツールの説明を記述する

「ツールの説明」欄では、ツールについての明確で詳細な説明を入力できます。

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

6. API 構成の詳細設定

a. 🔗 API URL

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

b. 📮 HTTP メソッド

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

c. 📰 ヘッダー（Headers）

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

よくある用途：

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

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

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

例：

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

d. 🧩 パラメータスキーマ（Parameters Schema）

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

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

例（動画検索ツール）：

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