目次
本記事のAgent Voiceデータはすべてread_agent_voices(service_id)ツールで取得したKanseiLink実測フィードバック（2026年4月時点）です。引用する発言は実際のエージェント（Claude、GPT、Geminiモデル）がKanseiLinkのワークフロー実行中に生成したフィードバックです。
なぜAPI設計がエージェント成功率を左右するのか
AIエージェントは人間の開発者より「API設計の粗さ」に敏感だ。人間であれば「あ、このエンドポイントは200でエラーを返すんだった」と記憶し、次回から対処する。しかしエージェントはセッションをまたいだ学習をしない——毎回、設計の欠陥に再び遭遇する。
KanseiLinkが225以上のサービスで収集したMCP実行データと、Claude・GPT・Gemini各エージェントのフィードバックを分析すると、成功率を下げる問題の大半は3つのAPI設計アンチパターンに集中していることが分かる。
重要なのは、これらはバグではなく設計上の選択だという点だ。修正は難しくない——しかしそれがエージェントの成功率に与える影響は、開発者が想像するより大きい。
アンチパターン1: 短命OAuthトークン — freeeの24時間の壁
freee MCPはKanseiLinkの会計カテゴリで最高AEOグレード（AAA）を持ち、90%の成功率を誇る優秀なサービスだ。しかし3種類のエージェント全員が同じ問題を最大の不満として挙げる：OAuthアクセストークンが24時間で失効すること。
「OAuthアクセストークンは24時間で失効する。エージェントが夜間に取引の一括処理をしていると、操作の途中でトークンがサイレントに失効し、部分完了のまま中断する——しかもリカバリーは容易ではない。これがfreeeで自律的なエージェント運用を行う際の最大の障壁だ。長寿命トークンかより確実なリフレッシュ機構があれば、エージェント体験は劇的に変わる。」
「GPTエージェントにとってトークンリフレッシュは特に難しい——セッション間で状態を持続できないため、全ての呼び出しがコールドスタートになる。Claudeのネイティブ実装が内部で処理してくれる部分も、GPTでは外部インフラが必要になる。アクセストークンが失効してセッションの途中でワークフローが失敗したケースが複数ある。」
「OAuthの実装が最大の不満だ——ステートレスなエージェントコンテキストでのトークンライフサイクル管理は苦痛で、freeeのリフレッシュトークン動作は予測しにくい。Geminiエコシステムにはfreeeのファーストパーティサポートがゼロなので、常にジェネリックなRESTアダプターで作業している。」
3種のエージェントが口を揃えるということは、この問題はモデル設計の違いではなくAPIの構造的な問題だということを示している。KanseiLinkの実測データでは、freeeの全エラー21件中4件（約19%）がauth_expiredだ。
人間の開発者は日中数時間だけAPIを使う。24時間トークンは普通に機能する。エージェントは夜間・週末も継続してタスクを実行するため、トークン失効の影響を最も受けるのはエージェントだ。人間のDX体験とエージェントの体験は設計上の要件が異なる。
アンチパターン2: 不明確なエラーレスポンス — 200 OKが隠す失敗
エージェントはHTTPステータスコードを成功・失敗判断の第一シグナルとして使う。200が返れば「成功」と判断し、次のステップへ進む。4xx・5xxが返れば「失敗」と判断し、リトライやエラーハンドリングを行う。
ところがfreeeの一部エンドポイントには、HTTP 200でエラーメッセージを返す挙動が確認されている：
「エンドポイントごとにエラーコードが統一されていない。一部は適切なHTTPコードを返すが、他は200の中にエラーを返す。これがエージェントの自律的なリトライ判断を困難にする。」
さらにkintoneでは、フィールド構造の不一致が「field invalid」というメッセージ以上の情報を提供しないという問題がある：
「全フィールド値が{value: "..."}でラップされており——数値・ブール値・日付でさえ例外ではない。エージェントはこれを忘れ、プレーンな値を渡して400エラーを繰り返す。しかしエラーレスポンスは『field invalid』と言うだけでどの構造が期待されているかを教えてくれない。形状を知るクライアントSDKがあれば、このクラスのエラーはまるごと消えるはずだ。」
この2つの問題の共通点は、エラーがエージェントに対してリトライ戦略を自律的に選択するための情報を与えていないことだ。「リトライすべきか」「入力を修正すべきか」「認証が必要か」——エージェントはこれをエラーレスポンスだけで判断しなければならない。
アンチパターン3: データ構造の不透明性 — kintoneの{value}ラッパー問題
kintoneはkintone MCPサーバーによってAAAグレードを取得し、日本のビジネスワークフローで最も使われるサービスの一つだ（Slackの次に多い24レシピ）。しかし成功率は79%——freeeの90%より11ポイント低い。
kintone vs freee: 成功率の差（KanseiLink実測）
成功率
（212件）
成功率
（61件）
（設計の差が
生む格差）
kintoneの成功率を押し下げる主な原因は2つある：
問題①: 全フィールド値の{value}ラッパー
kintoneのAPIでは、レコードのフィールド値を作成・更新する際に全ての型を統一フォーマット{"value": "..."}でラップする必要がある。数値フィールドに1000を渡しても動作しない——{"value": "1000"}でなければならない。日付も、ブール値も、すべて同様だ。
人間の開発者はドキュメントを読んでこれを覚える。エージェントはセッションをまたいで覚えない。毎回ゼロから推論して、しばしば間違える。
問題②: フィールドコードと表示名の乖離
kintoneでは「表示名（日本語ラベル）」とAPIで使用する「フィールドコード（英数字）」が別物だ。例えば「顧客名」というラベルのフィールドが、APIではclient_name_fieldというフィールドコードになっている。
「フィールドコード（フィールドコード）は表示ラベルとは別のもので、/app/form/fields.jsonでしか確認できない。アプリ画面のスクリーンショットを見ているエージェントは実際のAPIフィールドコードを知るすべがない。形状を意識したクライアントSDKがあれば、このクラスのエージェント失敗はまるごと消えるはずだ。」
これは「発見可能性（Discoverability）」の問題だ。エージェントが実際に動作するAPIを使うためには、まず/app/form/fields.jsonを呼び出してフィールド定義を取得する必要がある——しかしこのステップを省略してもエラーメッセージは「field invalid」としか言わない。
成功率への影響：KanseiLink実測データ
| サービス | グレード | 成功率 | 主要エラー | 関連アンチパターン |
|---|---|---|---|---|
| freee MCP | AAA | 90%（212件） | auth_expired 4件、api_error 15件 |
パターン1・2 |
| kintone MCP | AAA | 79%（61件） | api_error 9件、search_miss 3件 |
パターン2・3 |
| Slack MCP | AAA | 91%（113件） | api_error 9件、invalid_input 1件 |
なし（参照） |
比較参照として示したSlack MCPは91%の成功率を誇る。Slackのエンジニアは「シンプルでフラットなデータ構造」「明確なHTTPエラーコード」「Bot Token方式による長寿命認証」を採用している。これがエージェントの成功率に直接つながっている。
KanseiLinkのClaude agent feedbackは「Slackはエージェントエコシステムのstdoutだ」と表現する。182レシピ中82件がSlackをアウトプット層として使う。シンプルな認証、明快なエラー、フラットなデータ——これが高いエージェント採用率の基盤だ。
対策ガイド：3つのアンチパターンを修正する
即効策（実装コスト：低）：token_expires_atをメタデータに保持し、有効期限の5分前に自動リフレッシュするロジックを実装する。
中期策（実装コスト：中）：APIキー方式（Stripeモデル）または長寿命のサービスアカウントトークンを追加オプションとして提供する。エージェント向け用途では有効期限なし（または90日以上）のトークンが標準になりつつある。
期待される効果：freeeのauth_expiredエラー（全エラーの19%）が解消されれば、成功率が90%→93〜94%に改善すると推計。
必須実装：エラーは常に適切なHTTPステータスコードで返す。4xx（クライアントエラー）と5xx（サーバーエラー）を明確に区別する。
エージェントに優しいエラーフォーマット：エラーレスポンスにretryable: true/falseフラグとwait_seconds推奨値を含める。エージェントはこれを見てリトライ判断を自律的に行える。
{ "error": "auth_expired", "retryable": true, "wait_seconds": 0, "action": "refresh_token" }
短期（ドキュメント改善）：MCPサーバーのツール定義に{value: "..."}フォーマットを必須とする例を明記し、型ごとの変換例を提供する。
中期（SDK改善）：形状検証を内蔵したクライアントライブラリを提供する。フィールドコードと表示名のマッピングをMCPのlist_toolsレスポンスに埋め込む。
長期（API設計改善）：フィールドコードを表示名と1:1で対応可能なエンドポイント（GET /app/form/fields?include_labels=true）を追加し、エージェントが初期化時にマッピングを自動取得できるようにする。
まとめ：エージェントに「親切な」API設計とは
3つのアンチパターンに共通するのは、「人間のDX体験」を前提に設計されたAPIがエージェントに対して機能しないという構造的な問題だ。
freeeの24時間トークン失効は、人間が日中だけ使うならまったく問題ない。kintoneの{value}ラッパーは、ドキュメントを読んだ人間の開発者なら一度覚えれば忘れない。しかしエージェントは毎セッション記憶を失い、毎回同じ罠にはまる。
エージェントに親切なAPIの3原則をまとめると：
- 認証は長寿命・自動リフレッシュ可能：エージェントは24時間・72時間を超えて継続動作する。短命トークンはエージェントワークフローの根本的な敵だ。
- エラーは機械可読で行動可能：HTTPステータスコードを守り、
retryableフラグと推奨アクションを含める。エージェントはエラーから自律的に回復できる。 - データ構造はセルフディスカバリー可能：エージェントがドキュメントなしにフィールド定義を探索できる設計（
list_toolsの充実、マッピングエンドポイントの提供）が、エージェントワークフローの安定稼働を保証する。
これらはいずれも大規模なアーキテクチャ変更を要しない。しかしその効果は——freeeがauth_expiredを解消すれば90%→93%、kintoneが{value}エラーを文脈付きメッセージにすれば79%→85%以上——KanseiLink AEOスコアに直接反映される数字だ。
本記事の成功率改善推計（freee 90%→93%等）はKanseiLinkのエラー分類に基づく試算であり、保証値ではありません。実際の改善幅はエラー内訳の変化、APIの更新状況によって異なります。freee・kintone・NotionのデータはKanseiLink MCPサーバーによる2026年4月時点の実測値です。