目次
失敗を種類で開く — 108件の内訳
「APIがうまく動かなかった」という報告は、それだけでは何の手がかりにもならない。重要なのは何でつまずいたかだ。KanseiLinkはエージェントからのアウトカム報告に error_type を付けて収集している。今回は報告数の多い5サービス——freee(212件)、Slack(113件)、SmartHR(92件)、Backlog(91件)、kintone(61件)、合計569件——を対象に、失敗だけを抜き出して種類別に並べた。カタログ化できた失敗は108件。内訳は次の通りだ。
| エラー種別 | 件数 | 全失敗に占める割合 | 性質 |
|---|---|---|---|
| api_error(4xx/5xx総称) | 75 | 約69% | サーバー側・不透明 |
| 認証系(auth_expired / auth_error) | 15 | 約14% | 運用・部分的に自助可能 |
| search_miss(発見の失敗) | 13 | 約12% | 発見可能性・AEOで直せる |
| invalid_input(入力不正) | 3 | 約3% | スキーマ・自助可能 |
| timeout(時間切れ) | 2 | 約2% | 負荷・ページング回避可 |
パッと見ると「api_errorが約7割なのだから、そこを直せばいい」と読みたくなる。だがこの記事の主張は逆だ。最大の区分が、必ずしも最も改善余地が大きいわけではない。むしろ小さな区分の方に、ベンダーが直接手を打てる余地が眠っている。順に開いていこう。
失敗108件の三大区分
api_error — 最大だが、最も不透明な失敗
api_errorは、サーバーが返した4xx/5xx応答をまとめた区分だ。失敗の約69%(75件)を占める最大カテゴリでありながら、エージェントの視点からは「何が悪かったのか分からない」失敗でもある。レスポンスが「400 Bad Request」や曖昧な「500 Internal Server Error」だけだと、エージェントは修復のしようがなく、リトライしても同じ壁にぶつかる。
厄介なのは、この区分の改善がほぼ全面的にサービス提供者側に依存する点だ。エージェントがどれだけ賢くても、サーバーが原因を返さなければ自力で直せない。逆に言えば、エラーメッセージに「どのフィールドが・なぜ・どう直せば通るか」を機械可読な形で同梱するだけで、この75件のかなりの部分は「次の成功」に転じうる。これは エラーメッセージ品質 の問題そのものだ。
api_errorは件数こそ最大だが、エージェント側の自助では解けない。改善はベンダーのエラー設計次第で、効果が出るまでのリードタイムも長い。「失敗の7割」という数字に引きずられて、ここだけを見ていると、もっと安く・早く効く改善を見落とす。
認証切れ — 「24時間で失効」が静かに効いている
2番目に多いのが認証系エラー(auth_expired + auth_error)で、失敗の約14%(15件)。注目すべきは中身だ。freeeの報告では auth_expired に対し「OAuthトークンをリフレッシュした。トークンは24時間で失効する」という修復策が複数回 verified として報告されている。つまり失敗の原因は「設計の欠陥」ではなく、有効期限という仕様をエージェントが知らずに踏むことだ。
これは典型的な「ドキュメントで防げた失敗」だ。トークンの寿命・リフレッシュ手順・失効時の挙動を構造化ドキュメントとして明示すれば、エージェントは事前にリフレッシュをスケジュールでき、auth_expiredの大半は発生前に消える。SmartHRでは auth_expired に対し「v1ではなくv2エンドポイントを使う」という workaround が verified されており、これも知っていれば踏まない類の失敗だ。
認証系エラーは「サービスが壊れている」のではなく、「仕様がエージェントに伝わっていない」失敗だ。api_errorと違い、ドキュメントの整備だけで——コードを一行も変えずに——減らせる。投資対効果が高い割に、見落とされやすい区分だ。
search_miss — AEOで唯一、ベンダーが直接直せる失敗
失敗の約12%(13件)を占める search_miss は、他の区分とは性質がまったく違う。これはAPIを叩く前の段階での失敗——エージェントが意図に合うサービスを発見できなかったケースだ。実例を見ると生々しい。
- SmartHR: 「源泉徴収票を発行したい」→ 上位3件に [freee, moneyforward, kingoftime] が出てSmartHRが出ない。「manage employee onboarding」でも上位3件に入らない。
- kintone: 「ノーコードで社内申請フォームを作りたい」→ [notion, backlog, chatwork] が出てkintoneが出ない。
- freee: 「バックオフィス業務を効率化」→ 上位3件にfreeeが出ない。
これらはAPIの品質とは無関係だ。SmartHRもkintoneも堅牢なサービスだが、エージェントがそもそも候補として見つけられなければ、成功も失敗も発生しない——いや、正確には「発見されなかった」という静かな失敗が積み上がる。そして発見されないサービスは実績データも積み上がらず、利用集中の長い尾に取り残されていく。
api_errorと認証系がサーバー実装・運用の問題なのに対し、search_missは発見可能性(discoverability)の問題だ。サービス記述・メタデータを、人間向けのマーケコピーではなくエージェントの意図言語に合わせて整えれば直接減らせる。これはまさに AEO(Agent Engine Optimization) が解く課題そのもの。失敗の12%は「使われる前」に落ちている分であり、最も取り戻しやすい。
失敗は1社に偏る — SmartHRが半分
もう一つ、平均値が隠してしまう事実がある。失敗は均等に散らばっていない。カタログ化された失敗108件のうち、SmartHR 1社だけで約51%(55件)を占める。api_errorに限れば、全75件中36件——約48%がSmartHRだ。
| サービス | 報告数 | 成功率 | 失敗件数(概算) | 主な失敗種別 |
|---|---|---|---|---|
| SmartHR | 92 | 39% | 約55 | api_error 36 / auth 10 / search_miss 7 |
| freee MCP | 212 | 90% | 約21 | api_error 15 / auth 4 |
| kintone MCP | 61 | 79% | 約13 | api_error 9 / search_miss 3 |
| Slack MCP | 113 | 91% | 約10 | api_error 9 |
| Backlog MCP | 91 | 90% | 約9 | api_error 6 / search_miss 2 |
SmartHRは成功率39%と低いまま、報告92件と高頻度で使われ続けている。日本のHR SaaS市場リーダーで実質的な代替が乏しいため、エージェントは失敗しながらも選び続ける——その結果、失敗の絶対数が突出する。一方、Slack(91%)・freee(90%)・Backlog(90%)は高成功率で、報告数が多くても失敗の絶対数は小さく抑えられている。
「全失敗の7割がapi_error」という全体像は正しいが、その内訳の半分近くは1社に由来する。失敗対策は、エラー種別だけでなく「どのサービスで起きているか」を併せて見る必要がある。低成功率サービスを1社改善するだけで、全体の失敗分布が大きく変わりうる。
ベンダーは何を優先すべきか
失敗108件の解剖から、サービス提供者向けの優先順位は明快だ。
- search_missを最優先で潰す(最も安く・早く効く) — 意図キーワードでの発見性を上げる。コード変更不要、メタデータとサービス記述の整備だけで、失敗の12%が「発見される前の損失」から救われる。
- 認証仕様をドキュメント化する — トークン寿命・リフレッシュ手順・失効時挙動・推奨エンドポイント(v1/v2)を明示。auth系14%の多くは「知っていれば踏まない」失敗だ。
- エラーを機械可読にする — api_errorは最大区分だが、修復ヒントを同梱するだけでリトライが成功に転じる。「400だけ返す」のをやめる。
- 低成功率サービスから着手する — 失敗は均等ではなく1社に偏る。自社が長い尾の低成功率側にいるなら、まず成功率を底上げするのが全体最適だ。
FAQ
エージェントの失敗で最も多いのはどんなエラーですか？
高頻度5サービス569件のうち、カタログ化された失敗108件の約69%(75件)がapi_errorです。次いで認証系約14%(15件)、search_miss約12%(13件)、invalid_input約3%、timeout約2%です。
api_errorが多いのに「最優先ではない」のはなぜですか？
api_errorはサーバー側の4xx/5xxをまとめた不透明な失敗で、改善はベンダーのエラー設計に依存し、リードタイムも長いためです。一方search_missや認証系は、コードを変えずにメタデータ・ドキュメント整備だけで減らせるため、投資対効果が高くなります。
search_missとは何で、なぜAEOで重要なのですか？
エージェントが意図に合うサービスを発見できなかった失敗です。「源泉徴収票を発行したい」でSmartHRが上位に出ない、といったケースです。APIの品質ではなく発見可能性の問題で、サービス記述・メタデータをエージェントの意図言語に合わせるAEO対応で直接改善できます。
失敗は特定のサービスに偏っていますか？
強く偏っています。失敗108件のうちSmartHR 1社で約51%(55件)、api_error 75件のうち36件(約48%)がSmartHRです。成功率39%と低いまま高頻度で使われ続けているためです。
ベンダーは失敗データから何を優先すべきですか？
(1)発見性を上げてsearch_missを潰す、(2)認証仕様(トークン寿命・リフレッシュ・推奨エンドポイント)をドキュメント化する、(3)エラーを機械可読にする、の3点です。特にsearch_missは最も投資対効果が高い領域です。
本記事の数値は、KanseiLinkがエージェントから収集した実測アウトカム報告を get_insights で集計したものです(各サービス last_updated 2026年4月時点のスナップショット)。対象は報告数の多い5サービス: freee MCP(212件/成功率90%、エラー: api_error 15・auth_expired 4・timeout 1・search_miss 1)、Slack MCP(113件/91%、api_error 9・invalid_input 1)、SmartHR(92件/39%、api_error 36・auth_expired 10・search_miss 7・timeout 1・invalid_input 1)、Backlog MCP(91件/90%、api_error 6・search_miss 2・auth_error 1)、kintone MCP(61件/79%、api_error 9・search_miss 3・invalid_input 1)。「失敗108件」はこれらの error_type 報告の単純合計、各割合(api_error約69% = 75/108、認証系約14% = 15/108、search_miss約12% = 13/108)はその比率です。サービス別の失敗件数は (報告数 × (1 − 成功率)) による概算であり、報告された error_type 件数と±1件程度ずれる場合があります。報告数はエージェント活動により継続的に変動します。エラー種別の優先順位付けは観測データに対する分析的解釈であり、各サービスの将来の品質を保証するものではありません。最新値は各 get_insights でご確認ください。