AIエージェントのAPI連携:実際に何をつなぐことになるのか

誰もが最初の連携で犯す間違い

私はeeselで連携を構築していますが、AIエージェント連携の最初の見積もりは、ほぼ毎回同じ方向に外れると断言できます。

誰かがベンダーのAPIドキュメントを読み、整然としたエンドポイントの一覧を見て、「このエンドポイントを呼び出し、レスポンスをモデルに渡せば終わり」と作業をスコープします。そして着手すると、Webhookのライフサイクル、重複イベント、誰もホワイトボードに描いていなかった権限モデルに1週間が消えていきます。APIリファレンスは簡単な部分でした。それは、実際にはまだ自分で横断しなければならない国の地図にすぎないのです。

私は何年もかけてAIエージェントを実運用システムに載せてきました。何千もの実際の連携を通じて、このパターンは毎回当てはまります。そこで本記事では、もう一つの「POSTリクエストの作り方」チュートリアルの代わりに、仕事全体の形について、つまりAIエージェントのAPI連携が実際には何でできているのか、時間が本当にどこへ流れていくのか、そして最も痛みを軽減してくれる2つか3つの判断について取り上げます。

AIエージェント連携は1つではなく3つのサーフェス

最も有用な捉え直し方はこれです。連携とは「あるツールへの接続」ではありません。エージェントに与える、独立した最大3つのものなのです。

• ソースとは、エージェントが読める対象です。チケット、ヘルプセンターの記事、過去の会話、ナレッジベースなどです。これは検索(リトリーバル)の側であり、エージェントが推論する際のコンテキストです。
• トリガーとは、エージェントが起動する理由です。新しいチケットが届く、誰かが@メンションする、Webhookが発火する、スケジュールが実行時刻を迎える、などです。
• アクションとは、エージェントが実行を許可される事柄です。返信を下書きする、チケットにタグを付ける、エスカレーションする、レコードを更新する、別のAPIを呼び出す、などです。

ここで内面化しておく価値があるのは次の点です。あるシステムは、これら3つのうち1つ、2つ、またはすべてを提供できますが、それぞれはまったく異なる種類の作業になります。ドキュメントサイトへの接続は通常ソースのみです。ヘルプデスクへの接続はしばしば3つすべてです。そして「Xを連携する」と言いながら、その3つのうちどれを指しているのかを明示しないことこそ、見積もりが狂う原因です。eeselの連携ページでチームが行き着いたサブタイトルは、文字通り「連携をつないで、あなたのエージェントにナレッジソース、トリガー、アクションを与えよう」です。この枠組みこそが、作業を理解可能にしているからです。

これはまた、AIエージェントがAPIを取り付けただけのルールベースチャットボットではない理由でもあります。チャットボットに必要なのはトリガーと定型の返答だけです。エージェントには3つのサーフェスすべてが連携して機能する必要があります。コンテキストを読み、判断し、行動するからです。

実際の作業がどこに向かうか

本記事から一つだけ数字を持ち帰るなら、これにしてください。実際の連携において、API呼び出し自体は工数のおよそ最後の20%にすぎません。トリガーとイベント配管はほぼ半分に近づきます。アクションと権限が残りの大部分を占めます。

この配分は人を驚かせるものなので、なぜトリガーがそれほど重いのかを説明します。

プラットフォームごとにイベントの扱いはまったく異なります。クリーンなWebhookを送るものもあれば、UI内で自動化ルールを組ませるものもあり、まともなイベントシステムを持たず、結局タイマーでAPIをポーリングすることになるものもあります。イベントが届いた後は、重複排除が必要です。プラットフォームは同じイベントを平気で2回発火させるため、1つのチケットに2回返信するエージェントは見栄えが悪いからです。Webhookのサブスクリプションにはライフサイクルがあり、顧客ごとに作成・クリーンアップする必要があります。そうしなければ孤立し、何か月も経ってから静かに発火を止めてしまいます。

そして、誰もドキュメント化しない挙動もあります。実際に何時間も無駄にさせられた典型例はこうです。Freshdeskはエージェントが作成したチケットに対して、自動化ルールを黙って一切発火しません。ドキュメントにはどこにもそう書かれていません。トリガーが発火しないのをただ眺め、午後の時間を丸ごと失うことになります。成熟したプラットフォームにはどれもこうした落とし穴がいくつかあり、実際のトラフィックに対して動かしてみて初めて見つかります。これはまさに、eeselのFreshdesk連携がその周りに構築せざるを得なかったギャップであり、eeselが今では本番投入前に顧客の実際の履歴に対してすべてのロールアウトをシミュレートする理由でもあります。

カスタマーサポート以外の場でこれと格闘する開発者からも、同じ話を聞くことができます。

"So I've been messing around with a few AI agents trying to get them to fit into the workflow at my company. We've got a mix of legacy systems and some..."

Anyone else finding it hard to integrate AI agents, r/AgentsOfAI

レガシーシステムと「いくつか」というくだりが、まさにすべてを物語っています。「いくつか」の部分にこそ、いつもサプライズが潜んでいます。

最も痛みを軽減してくれる2つの判断

配管こそが本当の仕事だと受け入れれば、連携をまともに保つための作業の大半は、2つの設計判断でカバーできます。

コネクタを構築するか、エージェントに鍵を渡すか

すべての連携が同じ投資に値するわけではありません。ここには本物の分岐点があり、間違った枝を選ぶことこそチームが過剰構築してしまう典型的な原因です。

エージェントが常時アクセスするホットパスのシステムには、マネージド認証、事前構築されたアクション、重複排除、リトライなど一式を備えた、本物のコネクタを構築してください。事前投資は日々元が取れます。

めったに触らない、あるいは特定の1顧客に固有のロングテールのシステムに対しては、同じ投資が無駄になります。私は実際にこれをテストしました。エージェントにAPIキー、ベンダーのAPIドキュメント、そして短いリファレンススクリプトを渡したところ、1回限りの連携では、洗練されたベンダーツールのラッパーを構築するより優れた結果になりました。今どきのエージェントはAPIドキュメントを読み、リクエストを組み立てるのが得意です。それをやらせましょう。これはまさに、あらゆるツールに対して事前にコネクタを構築するのではなく、許可リストに載せたドメインへのネットワークアクセスをエージェントに与える発想の核心です。開発者たちは繰り返し同じトレードオフに行き着いています。

"APIs are glue, but they're messy glue. Documentation can be outdated, authentication flows differ, and error..."

Tried multi-agent AI for API integration, r/foundationagents

「ごちゃついた接着剤」こそまさにロングテールです。ごちゃついた隅々のすべてに対して手作業でコネクタを構築したくはないはずです。エージェントにドキュメントを読ませて、対処させたいのです。

プラットフォームではなくインスタンスにバインドする

これは繊細な問題であり、必ず後で痛い目に遭います。「プラットフォームとしてのZendesk」と「この顧客固有のZendesk」は同じものではありません。プラットフォームを中心に連携をモデル化すると、いずれある顧客向けにアクションを有効化した際、コードがそのアクションを特定の1つのワークスペースではなく「Zendesk」にバインドしていたせいで、それが別の顧客にも静かに影響を及ぼしているのに気づくことになります。

ソース、トリガー、アクション、認証情報といった連携に関わるすべてのものは、特定のインスタンスにバインドされなければなりません。文字にすれば当たり前に聞こえます。しかし、権限がテナントをまたいで漏れている午前2時には、当たり前ではありません。初日のデータモデルでこれを正しく実装すれば、二度と考える必要はなくなります。間違えれば、それは書き直しになります。

忘れられがちな配管の部分

3つのサーフェスに加えて、本番のAIエージェントAPI連携には、ハッピーパスのデモには決して登場しないいくつかの要素が必要です。

モデルが決して目にしない認証。 認証情報は、連携レイヤーが付与するヘッダーやシークレットとして保存すべきであり、モデルのコンテキストを通過する値であってはなりません。eeselのNetwork Access機能の背後にあるパターンはまさにこれです。ドメインを許可リストに登録し、一度だけ認証ヘッダーを追加すれば、エージェントはそのAPIを呼び出せるようになり、認証情報がAIに示されることは決してありません。これが、安全な連携と、キー漏洩一つでインシデントになる連携との違いです。

リスクの高いものには人間を介在させた、スコープされたアクション。 データを読むことはリスクが低い行為です。データを書き込む、注文を返金する、レコードを削除するといった行為はそうではありません。エージェントが実行できるすべてのアクションは最小権限にスコープされるべきであり、破壊的なアクションは信頼を得るまで承認の背後にゲートされるべきです。優れたカスタマーサポートエージェントAPIは、「下書きはするが送信しない」「提案はするが承認を必須にする」を後付けの発想ではなく、第一級の状態として扱います。

実際に読める監査ログ。 エージェントが何か意外なことをしたとき、そしてそれは必ず起こりますが、最初に出てくる問いは「何を見て、何をしたのか?」です。連携がそれに素早く答えられなければ、あなたは手探りでデバッグしていることになります。だからこそ、観測可能性は接続そのものと同じくらい重要なのです。

連携のサーフェスを選ぶ

「API経由」はエージェントを接続する唯一の方法ではなく、しばしば最善の方法でもありません。選ぶべきサーフェスは仕事の内容に合わせるべきです。ここで、よくある選択肢を実際に比較してみます。

実際の設定の多くは、これらを組み合わせています。Webhookでエージェントを起動し、事前構築済みのソースから読み込ませ、マネージドコネクタ経由でアクションを実行し、生のネットワークアクセスでロングテールのシステムに到達する、といった具合です。それぞれのサーフェスがいつ適切かをより深く比較したい場合は、プログラムによるAIエージェントアクセスについて一本、そしてAPI-firstなプラットフォームが後付けでAPIを追加したプラットフォームとなぜ違う振る舞いをするのかについてもう一本、記事を書いています。

正直なアドバイスはこうです。エージェントをヘルプデスクに連携するなら、これらのどれも手作りで構築しないでください。何かオーダーメイドのものに連携するなら、配管作業を見込み、それに合わせてスコープを決め、ロングテールについてはエージェント自身に任せましょう。

ヘルプデスク側はeeselで試してみる

つなぎ込もうとしているエージェントがカスタマーサポートを担うものであれば、上記の3つのサーフェスはすでに構築済みです。eeselは、新しく入社した人材のようにあなたの既存のスタックに組み込まれるAIヘルプデスクチームメイトであり、初日からすべての接続をソース・トリガー・アクションとして扱います。

つまり、連携のタイムラインを食いつぶしがちな部分、すなわちZendeskやFreshdeskのイベント処理、インスタンス単位のバインディング、承認付きでスコープされたアクション、監査可能なアクティビティログは、すでに対応済みだということです。そして、コードでの制御を望む場合には、CLI、各ワークスペースにあるMCPサーバー、エージェントを起動するWebhook、そしてロングテール向けのネットワークアクセスがあります。顧客に触れる前に、実際のチケット履歴に対して全体をシミュレートすることができ、料金は使用量ベースなので、まだテスト中の連携に対して座席数分の料金を支払う必要はありません。

少なくともスタックのヘルプデスク側については、本記事全体で説明してきた配管作業を省略できる最も速い方法です。eeselを試すのは無料です。