APIでAIエージェントを自社アプリに接続すべき理由

AIエージェントAPIとは

AIエージェントAPIを使うと、自社のソフトウェアから構築済みのエージェントにメッセージを送り、その回答を受け取れます。エージェントは指示、ナレッジ、モデル、ツール、安全ルールをそのまま保持し、アプリは質問を送るだけです。

ここが、素のモデルAPIとの違いです。モデルAPIが提供するのはテキスト生成だけで、プロンプト、ドキュメント検索、記憶、レート制限、課金はすべて自分で用意する必要があります。IMFAのREST APIなら、それらをすべて備えたマネージドエージェントを、エージェント単位のキーひとつで利用できます。

エージェントはAIチャットボットビルダーで作成します。APIは、Webサイト、WhatsApp、Instagram、Facebook、Telegram、Discord、音声通話に加えて、エージェントが回答できるもうひとつの場所です。

APIでエージェントを接続すべきなのはどんなときか

会話があなたの所有するサービスの中で行われるなら、APIの出番です。

• 自社アプリや顧客ポータルに、ポリシーを把握したヘルプアシスタントが必要で、2つ目のチャットボットを管理したくない場合。
• バックエンドで、注文ページ、予約ツール、社内ダッシュボードなど別のシステムからの質問に答えたい場合。
• リードをCRMに取り込みたい場合。APIはエージェントがすべてのチャネルで獲得したリードを返すので、定期的に同期できます。
• レポートや品質チェックのために会話履歴が必要な場合。

Webサイトにチャットバブルを置くだけなら、1行の埋め込みコードのほうが簡単です。APIは、ウィジェットではなく自社のプロダクトがインターフェースになる場合のためのものです。

IMFAエージェントAPIの仕組み

ベースURLはhttps://site.imfa.app/v1です。すべての呼び出しにはエージェントのキーが必要で、ブラウザやモバイルアプリのバンドルではなく、必ず信頼できるサーバーコードから送信する必要があります。

1. エージェントを公開します。 IMFAで指示、ナレッジ、モデル、ツールを設定し、実際の質問でテストしてから公開します。APIは公開済みのバージョンを提供します。
2. キーを生成します。 エージェントのAPI画面またはAPIキー画面を開いてキーを生成します。キーは一度だけ表示され、ハッシュとしてのみ保存されます。IMFA_API_KEYなどのサーバーの環境変数に保管してください。
3. チャットリクエストを送信します。 Authorization: Bearer <key>、一意のIdempotency-Key（8〜128文字）、そしてmessageと任意のsessionIdを含むJSONボディを付けて、POST /v1/agents/{slug}/chatを送ります。返信にはsessionIdとusage.creditsが含まれます。
4. 会話を続けます。 最初のターンではsessionIdを省略し、以降は受け取った値を送り返します。エージェントは文脈を覚えています。
5. 結果を確認します。 GET /v1/agents/{slug}/sessionsで会話の一覧を、GET /v1/agents/{slug}/sessions/{sessionId}/messagesで個別の会話を取得し、GET /v1/agents/{slug}/leadsで獲得したリードを取得します。一覧はデフォルトで20件、最大100件をカーソル付きで返します。GET /v1/agentsで、キーがどのエージェントに対応しているかを確認できます。

制限は明確です。メッセージは先頭の4,000文字まで使用され、ボディの上限は64,000バイトで、エラーは種類別（検証、認証、クレジット、レート制限、サーバー）に返されます。429にはRetry-Afterが付き、402はオーナーのクレジットが残っていないことを意味します。

自前で構築せずエージェントAPIを使うメリット

何か月分もの基盤づくりを省けます。 ドキュメント検索、セッション、レート制限、リトライ、クレジット計算、プロンプトインジェクション対策のルールはすでに稼働しています。チームが書くのはHTTP呼び出しひとつだけです。

ひとつのエージェントが、ひとつの振る舞いをします。 アプリに表示される回答は、WebサイトやWhatsAppでの回答と同じです。同じエージェントだからです。IMFAで一度更新すれば、すべての接点に反映されます。

リトライしても安全です。 冪等性キーがあるので、ネットワークの再試行で2回目のターンが課金されることはなく、元の返信が返されます。

リードがバラバラに埋もれなくなります。 どのチャネルから来たリードでも、ひとつのエンドポイントからまとめて取得できます。

完全なカスタマイズも可能です。 すべての層を自分で管理したいなら、素のモデルAPIでその自由が得られますが、構築と運用を自分で担うことになります。CodexやClaude CodeなどのコーディングエージェントはMCP経由でIMFAのエージェントを管理でき、サーバーはRESTキーを使ってお客様に対応できます。

AIエージェントAPIに関するよくある質問

AIエージェントAPIをブラウザから直接呼び出せますか？

いいえ。キーはオーナーのクレジットを消費するため、信頼できるサーバー上に置いておく必要があります。APIはブラウザからの広範なアクセスを許可していません。ブラウザからは自社の保護されたエンドポイントを呼び出し、そこからIMFAを呼び出してください。

IMFAエージェントAPIのリクエストはどう認証しますか？

エージェントのAPI画面またはAPIキー画面でエージェント単位のキーを生成し、サーバーコードからAuthorization: Bearer YOUR_API_KEYを送信します。MCPトークンは別の認証情報であり、ここでは使えません。

同じAPIの会話を続けるにはどうすればよいですか？

最初のチャットリクエストではsessionIdを省略し、APIが返すsessionIdを保存して、次のメッセージと一緒に送信します。Webサイトやチャネルでの会話のセッションIDは読み取り専用で、APIの会話を続けるためには使えません。

チャットにIdempotency-Keyが必要なのはなぜですか？

リトライを安全にするためです。同じキーで完全に同じリトライを行うと、新しいターンを作らずに同じ結果が返されます。新しいメッセージごとに新しいキーを使ってください。

エージェントAPIは自分のナレッジやツールを使いますか？

はい。APIは、指示、モデル、ナレッジ、スキル、ツール、安全ルールを備えた公開済みのエージェントを呼び出します。回答は、公開済みの設定、クレジット、現在のサービス制限に左右されます。

APIがレート制限にかかったり、クレジットがなくなったりするとどうなりますか？

レート制限時にはRetry-Afterヘッダー付きの429が、オーナーのクレジットがなくなったときには402が返されます。連携では、ドキュメントに記載されたすべてのステータスコードに対応してください。