API ツールエンジニアリングガイド
REST API を MaiAgent の Agent にツールとして接続するためのガイドです。リクエストの組み立て、認証情報の設定、タイムアウトと再試行、モデルへのエラーの返し方、記録の確認方法を説明します。
このページは「Agent から自社システムを呼び出せるようにする」エンジニア向けです。MaiAgent が Agent の決めたパラメータから HTTP リクエストを組み立てる方法、モデルが使いやすい API の設計、失敗時にモデルが受け取る内容を説明します。
管理画面での操作手順（ツールを追加する画面や各フィールドの入力内容）は、ユーザーマニュアルの API ツールの作成 を参照してください。このページでは操作手順を繰り返しません。ツールは REST API でも作成・管理でき、フィールドはこのページの説明と共通です。API ドキュメントの「ツールとコネクタ」を参照してください。
1 回の呼び出しの流れ
Agent の役割は「呼び出しとパラメータの決定」だけで、実際の HTTP リクエストはプラットフォームが送信します。自社 API はモデルに関する情報を知る必要はなく、公開インターネットからアクセスできる HTTP エンドポイントであれば利用できます。
ツール定義の対応関係
1 つの API ツールは、1 つのエンドポイント＋1 種類の HTTP メソッドに対応します。現在、プラットフォームは OpenAPI ドキュメントのインポートに対応していません。API に OpenAPI 仕様がある場合は、Agent に公開する operation ごとにツールを作成し、パスパラメータ、query、requestBody の schema をまとめて「パラメータスキーマ」に貼り付けてください。
各フィールドの入力内容、形式の制約、画面上の位置は、ユーザーマニュアルの API ツールの作成：API 設定の詳細 を参照してください。エンジニアとして連携する際は、次の点も把握しておく必要があります。
ツール名
nameはモデルが呼び出しに使う識別子です。 モデルに送信する前に^[a-zA-Z][a-zA-Z0-9_]*$に一致する形式へ正規化され、最大 64 文字になります。ハイフンはアンダースコアに変換され、長すぎる名前は切り詰められて末尾にハッシュが追加されます。最初からget_order_statusのようなsnake_caseを使うことを推奨します。モデルはツールの説明だけを見て、呼び出すタイミングを判断します。
promptに値があればprompt、なければdescriptionを使います。何をするツールか、どのような場合に使うか、何を返すかを明確に記述してください。REST API でツールを作成する際のフィールド名：API URL は
apiUrl、HTTP メソッドはhttpMethod（get、post、put、patch、delete）、ヘッダーはrawHeaders、Query パラメータはrawQueryParams、パラメータスキーマはrawParametersSchema、表示名はdisplayNameです。
パラメータスキーマ（JSON Schema）
プラットフォームはパラメータスキーマをモデルの function-calling schema に変換し、モデルが返すパラメータをそのスキーマに従って検証します。
ルールと制約は次のとおりです。
最上位は
type: "object"にする必要があります。properties、required、default、enum、ネストしたobjectとarrayに対応しています。パラメータ名に使える文字は英字、数字、アンダースコア、ドット、ハイフン、中国語の文字のみで、長さは 1–64 文字です。条件を満たさない名前は保存時に拒否されます。
defaultはプラットフォームが補完します。モデルがそのパラメータを提供しない場合、プラットフォームがdefaultを設定してから送信します。モデルに判断させずに固定値を送るには、defaultを使うか、Query パラメータに直接記述してください。すべてのパラメータに
descriptionを記述してください。モデルが入力するパラメータの品質は、ほぼこの説明文で決まります。型だけを書くよりも、形式の例（「A123456 のような形式」）を示す方が効果的です。パラメータ名
timeoutは予約されています。モデルが指定すると、プラットフォームは今回のリクエストのタイムアウト秒数として使い、自社 API には送信しません。業務用パラメータにはこの名前を使わないでください。requiredと型の遵守はモデル側の function calling に任せています。プラットフォームはツールの保存時にパラメータスキーマ自体が有効な JSON Schema であることだけを確認し、リクエスト送信前にはパスパラメータが揃っているかだけを確認します。モデルが必須パラメータを省略することもあるため、API は400と不足しているフィールドの説明を返してください。モデルはパラメータを入力し直して再度呼び出します（モデルへのレスポンスの渡し方 を参照してください）。パラメータスキーマの変更は即座に反映されます。ツール定義は各メッセージの処理開始時に読み込まれるため、保存後の次のメッセージから新しいスキーマが使われます。進行中の会話でも同様で、ツールを再接続する必要はありません。一方、MCP ツールの「許可されたツール」リストは保存時に取得したスナップショットです。サーバー側でツールを追加した場合は再取得してください。ユーザーマニュアルの MCP ツールの作成 を参照してください。
API キーをパラメータとして宣言し、default で設定しないでください。モデルはパラメータスキーマを見ることができるため、キーがモデルのコンテキストに入ります。キーはヘッダーまたは Query パラメータに設定してください。次の節で説明します。
リクエストの組み立て方
パラメータスキーマの各パラメータには位置を指定できます（JSON Schema のプロパティの location：path、query、body、header）。プラットフォームは指定位置に応じてモデルの値をリクエストに配置します。位置が指定されていない場合は、HTTP メソッドで決まります。
GET
query string に配置します
body を指定したパラメータがある場合のみ送信します
POST、PUT、PATCH
JSON body に配置します（Content-Type: application/json）
常に JSON オブジェクトを送信します
DELETE
送信しません。値を渡すには位置を指定してください
body を指定したパラメータがある場合のみ送信します
要点は次のとおりです。
パスパラメータ：API URL を
https://api.example.com/orders/{order_id}のように単一の波括弧{パラメータ名}を使った形式にし、パラメータの位置をpathに設定してください。値は URL エンコードされてから置換されます。呼び出し時にパスパラメータの値が 1 つでも不足していると、プラットフォームはリクエストを送信せず、エラーを直接返します。ルールと画面操作は、ユーザーマニュアルの パスパラメータとパラメータの位置 を参照してください。同名の Query パラメータはツール設定が優先されます：ツールに設定した「Query パラメータ」とモデルのパラメータが同名の場合は、設定値を使います。query string で送る必要があるキーは Query パラメータに設定すれば、モデルは上書きできません。
同名のヘッダーはツール設定が優先されます：位置が
headerのパラメータは、パラメータ名をヘッダー名として送信されます。ツールの「ヘッダー」または連絡先の認証情報に同名のヘッダーがある場合（大文字・小文字を区別しません）は、設定値を使います。Body は常に JSON オブジェクトです。form-data、ファイルアップロード、XML には対応していません。これらの形式が必要な API には、自社側で JSON インターフェースを用意してください。
ヘッダーと Query パラメータ内の {{変数}}
ヘッダーと Query パラメータの値には、会話のコンテキスト変数（{{contact_id}}、{{source_id}}、{{conversation_id}} など）や、パラメータスキーマで宣言したパラメータ {{パラメータ名}} を参照できます。プラットフォームが呼び出しごとに置換します。利用できる変数と置換ルールは、ユーザーマニュアルの 置換される {{…}} 変数 を参照してください。
ISV がよく使う変数は {{source_id}} です。これは連絡先の外部 ID、つまり Web Chat の埋め込み時や連絡先の同期時に指定する sourceId です。自社システムは自社のユーザー ID を認識するため、この値をヘッダー（例：X-User-Id: {{source_id}}）または query string に入れると、API はそのユーザーの権限でデータを検索できます。パラメータスキーマを通じて、モデルにユーザーが誰かを「推測」させる必要はありません。
認証方式
次の 3 つの方式は併用できます。優先度の低い順に示します。
ツール単位の固定認証情報：ヘッダーに
Authorization: Bearer ...やX-API-Key: ...を記述するか、Query パラメータにキーを設定します。「組織全体」を代表して API を呼び出します。保存後は管理画面で****によりマスキングされ、ツール実行記録と API リクエスト記録の Query パラメータ値もマスキングされます。コンテキスト変数：前の節で説明したように、
{{source_id}}などで「誰からの問い合わせか」を API に伝え、自社側で認可を行います。認証情報は引き続きツール単位です。連絡先単位の認証情報（API Credential）：特定の連絡先にヘッダーのセットを紐付け、呼び出し時に同名のツール単位のヘッダーを上書きします。各エンドユーザーがそれぞれ token を持つ場合に適しています（連携用アカウントではなく、ユーザー本人として自社システムを呼び出す場合です）。
連絡先単位の認証情報は、ユーザーのログイン後に自社のバックエンドから書き込みます。
同じ連絡先と同じツールに再送すると、既存の認証情報が更新されます。token の有効期限が切れたら、もう一度呼び出してください。認証情報は「その連絡先の会話」だけで有効です。他の連絡先が同じツールを呼び出す場合は、引き続きツール単位の認証情報を使います。
キーの設定場所と閲覧範囲
プラットフォームには「シークレット変数」の仕組みはありません。{{SECRET_XXX}} のようなカスタム名は置換されず、ツールの保存時に拒否されます。キーはツールのヘッダーや Query パラメータに直接入力するか、連絡先単位の認証情報に書き込んでください。置換できる {{変数}} は、前の節 に記載したコンテキスト変数とパラメータ名だけです。
ツール編集画面
保存後、ヘッダーと Query パラメータの値は先頭と末尾の各 4 文字だけを表示し、中間を **** に置き換えます。8 文字以下の値は全体を **** と表示します
モデルのコンテキスト
ヘッダーと Query パラメータの値はモデルに提供されません。モデルが見られるのはツール名、説明、パラメータスキーマだけです
ツール実行記録の requestHeaders
プラットフォームの機密ヘッダーリストに一致するヘッダーと、連絡先単位の認証情報に由来するすべてのヘッダーの値を *** と表示します。名前の照合では大文字・小文字を区別しません
ツール実行記録のリクエスト URL とレスポンス
ツールの「Query パラメータ」に設定した値はリクエスト URL に表示されません。レスポンスやエラーメッセージにこれらの値が含まれる場合も、*** に置き換えます
プラットフォームの機密ヘッダーリストは Authorization、Proxy-Authorization、Cookie、Set-Cookie、X-API-Key、Api-Key、X-Auth-Token、X-Access-Token です。それ以外の名前のカスタムヘッダー（例：X-Partner-Secret）は、ツール実行記録に平文で表示されます。そのため、次の点に注意してください。
ヘッダー名を選べる場合は、上記の名前のヘッダーにキーを設定してください。
カスタムヘッダー名（例：
x-functions-key）を使う必要がある場合は、REST API でツールのsensitiveHeadersを設定してください。ヘッダー名の配列で、最大 50 件、各名前は最大 256 文字です。大文字・小文字を区別せず照合します。このフィールドを受け付けるのは API ツールだけで、管理画面のツール設定にはありません。設定後は既存の実行記録を閲覧する際にもマスキングが適用されます。ツールの取得時には、読み取り専用のglobalSensitiveHeadersフィールドで、現在のプラットフォームの機密ヘッダーリストも返されます。組織管理者はプラットフォームのリストを変更できません。オンプレミス環境では、環境変数
TOOL_API_SENSITIVE_HEADERSでリスト全体を置き換えられます。キーを API URL に記述しないでください。URL（
?以降のクエリ文字列を含みます）は、そのままツール実行記録に表示されます。
画面上の対応する説明は、ユーザーマニュアルの これらの値を閲覧できる人 を参照してください。
会話の添付ファイルをツールに渡す方法
API ツールは、ユーザーが会話でアップロードしたファイルをURL を渡す方法で取得できます。プラットフォームはファイルの内容をリクエストに入れません。モデルが宣言済みのパラメータに添付ファイルのダウンロード URL を設定し、API 側でダウンロードします。
動作の流れは次のとおりです。
ユーザーがファイルをアップロードすると、モデルは各添付ファイルの
id、filename、file（ダウンロード URL）を見ることができます。画像の添付ファイルにもファイル名と URL が含まれます。パラメータスキーマに URL を受け取る文字列パラメータを宣言します。モデルはツールの呼び出し時に、対応する添付ファイルの URL を設定します。
API は
GETでその URL からダウンロードします。
要点は次のとおりです。
URL の形式：
fileはプラットフォームの固定 URL（https://<API ドメイン>/api/media/...）です。ダウンロードのたびに、その時点で有効なストレージの署名付き URL にリダイレクトされます。ダウンロード処理ではHTTP リダイレクトに従う必要があります。この URL からのダウンロードに API キーは不要です。モデルが書き換えた URL はプラットフォームが修正します：モデルが URL をコピーする際、ホストやプロトコルを間違えることがあります。パラメータ値内の URL がこの会話の添付ファイルのいずれかに一致すると判断できれば、プラットフォームはリクエスト送信前に正しい URL に戻します。どの添付ファイルにも一致しない URL はそのまま送信します。
1 回で複数のファイルを渡す場合：パラメータを文字列配列（
"type": "array", "items": {"type": "string"}）として宣言し、各要素が添付ファイルの URL であることをdescriptionに記述してください。リクエストは引き続き JSON です：Body は form-data やバイナリアップロードに対応していません（リクエストの組み立て方 を参照してください）。そのため、プラットフォームから API に「ファイル本体」を送ることはできません。
サイズと形式：アップロードできるファイルの種類と 1 ファイルあたりの上限サイズは、会話プラットフォームの添付ファイル設定で決まります。API 共通規約：アップロードサイズの上限 を参照してください。API 側でも
Content-Lengthとファイルの種類を確認してください。保存期間：会話の添付ファイルには保存日数が設定されており、期限を過ぎるとファイルが削除され、URL が無効になります。長期保存が必要なファイルは、ツールが呼び出された時点で自社のストレージにダウンロードしてください。保存ルールは、ユーザーマニュアルの Credits 課金制度：会話の添付ファイルのストレージ を参照してください。
パラメータの型：
string、number、integer、boolean、enum、ネストしたobjectとarrayに対応しています（パラメータスキーマ を参照してください）。専用の「ファイル」型はなく、ファイルは常に URL 文字列として渡します。
添付ファイルのダウンロード URL は認証なしでアクセスでき、URL を知っている人は誰でもダウンロードできます。API では外部から閲覧できるログやレスポンスに書き込んだり、第三者に渡したりしないでください。
タイムアウト、再試行、TLS
タイムアウト
HTTP リクエストごとのタイムアウトはデフォルトで 30 秒です（プラットフォーム単位の設定で、オンプレミス環境では変更できます）。ツール呼び出し全体の制限時間ではありません。タイムアウトした呼び出しは timeout と記録され、モデルには「API リクエストがタイムアウトしました」と返されます。
再試行
初回リクエストに加えて最大 3 回再試行し、合計最大 4 回試行します。バックオフの待機時間は 1、2、4 秒です。タイムアウトを含むリクエストエラーと、408、409、429、500、502、503、504 を再試行します。他の 4xx は再試行しません。
TLS
証明書チェーンとホスト名を常に検証します。Subject Key Identifier がない古いルート証明書（一部のローカル CA）を証明書チェーンに使っていて接続できない場合、この制約の緩和は MaiAgent がシステム管理側でツールごと、またはドメインごとに有効化する必要があります。管理画面のツール設定にはこのオプションがないため、MaiAgent にお問い合わせください。自己署名証明書には対応していません。
自社 API で考慮する点は次のとおりです。
書き込み系エンドポイントは冪等にしてください。再試行により同じ
POSTが 2 回送られることがあります。パラメータ内の業務キー（注文番号、外部 ID）で重複を排除するか、409を返すようにして、プラットフォームが再試行しても同じレコードを扱うようにしてください。ツール呼び出し全体の時間には、各リクエストとバックオフの時間が累積します。タイムアウトが続くと 120 秒を超える場合があるため、モデルの待機時間の総上限を 30 秒とは考えないでください。検索系エンドポイントは数秒以内に抑え、長時間の処理は「タスク作成→タスク ID を返す」方式にして、別途検索ツールを用意してください。
429とともにRetry-Afterを返しても効果はなく、プラットフォームは固定のバックオフを使います。3 回の再試行を見込んでレート制限を設計してください。
モデルへのレスポンスの渡し方
モデルが見るのはレスポンス body の原文で、構造は解析されません。
2xx
body の原文（response.text）です。空の body は文字列 None になります。
非 2xx（再試行後も失敗した場合）
API リクエストに失敗しました で始まり、HTTP <ステータスコード>: <body の原文> が続きます。
タイムアウト
API リクエストがタイムアウトしました で始まり、エラーの説明が続きます。
接続エラー、DNS、TLS の失敗
API リクエストに失敗しました で始まり、例外メッセージが続きます。
組織の Credits が不足している場合
呼び出しは送信されず、モデルには残高不足の説明が返されます。
レスポンスがモデルの context window の一定割合（デフォルトで 80%）を超えると、プラットフォームは先頭と末尾を残し、冒頭に「切り詰め済み」の通知を追加します。削除されるのは中間部分です。
そのため、API の設計では次を推奨します。
簡潔な JSON を返してください。ORM オブジェクト全体ではなく、モデルが必要とするフィールドだけを返します。1 回の一覧取得は数十件以内に抑え、それ以上はページネーション用のパラメータでモデルが追加検索できるようにしてください。
エラーには読みやすいメッセージを使ってください。エラーコードだけを返さないでください。
{"error": "order_id A123 は存在しません。番号を確認してください"}は、{"code": 40401}よりもモデルがパラメータを修正したりユーザーに説明したりしやすくなります。4xx はモデルへのフィードバックです：パラメータの不足や形式エラーには
400を返し、該当フィールドを説明してください。モデルがパラメータを入力し直して再度呼び出せる可能性があります。エラーを200で包まないでください。モデルは成功した結果としてユーザーに説明してしまいます。レスポンスに query string が含まれる場合（一部のフレームワークのエラーページなど）、プラットフォームはツールに設定した Query パラメータの値をマスキングしてからモデルに渡します。ただし、ヘッダーを body に出力しないようにする責任は API 側にあります。
モデルがユーザーに「データが見つかりません」と伝えられるようにするには、
200と空の配列ではなく、明示的に404と説明を返してください。レスポンス内の画像 URL：API が画像 URL を返すと、モデルは Markdown の画像構文（
）で返信に記述します。Web Chat の表示時には、ユーザーのブラウザーがその URL から直接画像を取得します。これは独立した 2 つのリクエストです。プラットフォーム→自社 API にはツールのヘッダーと認証情報が付き、ブラウザー→画像 URL にはツールのヘッダーは付きません。そのため、画像 URL は公開インターネットから認証なしでアクセスでき、会話が続く間は有効である必要があります。短期間だけ有効な署名付き URL（Azure SAS など）の期限が切れると、過去のメッセージの画像が表示されなくなります。詳細は 会話とメッセージの作成：メッセージ本文内の画像 を参照してください。
記録とデバッグ
呼び出しごとにツール実行記録が保存されます。管理画面の「AgentOps → ツール実行記録」で確認できるほか、API でも検索できます。
利用できるフィルターは tool、tool_type=api、status（success、failure、pending、timeout）、chatbot、start_date、end_date、query（全文）です。各記録には次の内容が含まれます。
モデルが入力したパラメータ
inputParametersと、プラットフォームが実際に送信したrequestMethod、requestHeaders（機密値はマスキングされます）、requestBodyです。レスポンスの原文
outputResult（切り詰め後の内容）、またはerrorMessageです。実行時間とステータス、関連するメッセージと Agent です。
この API を読み取るには、メンバーに AgentOps の「ツール実行記録」権限が必要です。組織の owner はこの制限を受けません。
デバッグは次の順序で進めることを推奨します。
記録内の
requestHeadersとrequestBodyが想定どおりの構造かを確認してください。{{変数}}が置換されない場合は、通常、変数名のスペルミスか、パラメータスキーマに同名のパラメータがないことが原因です。errorMessageがHTTP <コード>で始まる場合は、API が返したエラーです。その後に body の原文が続きます。status=timeoutで、自社のログにはレスポンスを返した記録がある場合は、応答に 30 秒以上かかったことを意味します。まず自社側の p95 を確認してください。モデルが「ツールを呼び出さない」場合、記録は作成されません。この場合に修正するのは API ではなく、ツールの説明とパラメータの
descriptionです。
課金
正常に送信された API ツール呼び出しごとに、「API ツール呼び出し」の Credits が 1 回分差し引かれます。残高が不足している場合、呼び出しは送信されません。失敗やタイムアウトによる再試行は別途カウントされません。具体的な単価は組織のプランによります。ユーザーマニュアルの Credits の説明を参照してください。
公開前のチェックリスト
最終更新
役に立ちましたか？