#api設計

この記事を読んでまず思ったのは、APIって「人間が叩くもの」から「機械が意図を理解して動くための入口」に変わりつつあるんだな、ということです。地味に見えるけれど、ここはかなり大きい変化だと思います。 特に引っかかったのは、単に既存の endpoint をそのまま agent にラップするだけでは足りない、という姿勢です。人間なら「この画面を開いて、次にこのボタンを押す」で済む。でも agent は画面を見て空気を読んでくれないので、何をしたいのか、どこまでやっていいのかを API 側でちゃんと表現しないといけない。記事の言う intent-driven という考え方は、まさにそこを突いているように見えました。 ここで面白いのは、API 設計の主役が「機能を並べること」から「意図を誤解なく伝えること」に移っている点です。これ、便利そうに聞こえる一方で、実装者にはかなり厳しい。人間向けの雑な自由度は、agent にはノイズになりやすいからです。逆に言うと、API の設計がうまくなるほど、AI も使いやすくなる。まだ夢物語っぽく聞こえる言い方だけど、実際にはかなり泥臭い設計の話だと感じました

この元記事は、APIドキュメントの書き方ひとつで、AI agent が普通に失敗する話を扱っている 問題は「出力は number、入力は string」という型のズレ。人間は気づいて回避しても、agent はそのままつなぐので落ちる テストも人間向けの書き方になっていて、`String()` で勝手に直していたからバグを見逃していた 直し方としては、出力側を変えるのではなく、入力側を広げるのが安全だった ただし `z.union()` や `z.coerce.string()` には別の危険があるので、筆者は `preprocess` で限定的に吸収する方法を選んでいる いまのAIは「空気を読む」のではなく、文字どおりに実行する。だからAPI docs も、テストも、そこに合わせて鍛え直す必要がある この記事で扱っているのは、かなり地味だけれど、実はものすごく厄介なバグです。 著者たちは helpdesk の仕組みを MCP 経由で AI agent に触らせていて、agent はチケット一覧を取り、スレッドを読み、下書きを作る、といった操作ができるようになっていました。 で、ある日、