エージェント向けAPIの設計

エージェント向けAPIの設計は、人間向けAPIの設計とは異なります。今日、APIのほとんどの消費者はエージェント経由のコードで行っています。これは2年前には真実ではなく、設計方法について考え直す必要があります。 私はもはや人間向けに構築されたほとんどのシステムを信じていません。私はほとんどのパッケージに懐疑的で、ユーティリティには反対し、現在は非常に長い名前を支持しています。これらはすべて、過去24ヶ月で180度方向転換した意見です。 人間向けの良いAPI 人間向けの良いAPIを設計する際、私の最初のステップは、最小限の使用パターン、オンボーディング、そしてトップ10のユースケースをスケッチすることです。そこから、理想的に書くだろうコードを想像します。それから実際に使ってみて、行き詰まったエッジを見つけ、必要に応じて良いデフォルト値と設定を追加します。 私は人々が50行で機能的なものを持てるようにしたいです。そこから、APIは十分に親しみやすいものになり、より多くの機能が必要になったときに、それがどこにあるかが明白になるべきです。理想的には、20個のフィールドのうち1つしか必要としない人は、その1つを中心にオートコンプリートを通じて他の19個に気づくだけで良いでしょう。良いSDKは、ドキュメントを最小限かすめるだけで使用できるほど自己説明的であるべきです。そうでなければ、ドキュメントを読む必要はありません。 素晴らしい例をいくつか挙げます。 twilio.py client.messages.create( body="Join Earth's mightiest heroes. Like Kevin Bacon.", from_="+15017122661", to="+15558675310", ) stripe.ts const paymentIntent = await stripe.paymentIntents.create({ amount: 1099, currency: "usd", automatic_payment_methods: { enabled: true, }, }); これらは上記の価値観を体現しています。私はこれらを14歳で問題なく実装でき、Stripeの税金オプション、ACHとは何か、あるいはStripeが行う他の50の事柄について学ぶ必要はありませんでした。Twilioのスケジューリング、ボット、その他のことについても同様です。後で学びましたが、これらのSDKは、実際には何が起こっているのかあまり知らなくても、多くの進歩を遂げさせてくれました。 これは、エージェント向けに設計すべきことの反対です。 AIエージェントは、私たちのドキュメント全体を一度に読み込むことができます。平均的なClaude Codeプロンプトは10k以上のトークンを使用します。最初のエージェントプロンプトで、API全体と関連するすべてのドキュメントを読むことができます。また、数秒で目標を達成するために数千行のコードを生成することもできます。これはすべてを変えます。 エージェント向けの良いAPI エージェントにとって最も重要なのは明確性です。コードを読むだけで、それが正確に何をするのかがわかるAPIです。AIエージェント時代には、コードがはるかに多くなり、デバッグがはるかに困難になります。その唯一の解決策は、コードが何をすべきかについての正確な定義です。 つまり、デフォルト値は悪いということです。エージェントはドキュメントを読み、良い開始値が何であるかを登録し、それらをすべて埋めると予想できます。明示性は今は安価であり、期待される動作に具体性をもたらすことでバグが減ります。上記の例では、理解できなかったため、私が記入しなかった30個のフィールドがありました。エージェントはそれらすべてを記入すべきです。 これは、重要度の低いフィールドに、それらを分離するためのより重要なフィールドとの間にコメントを付けるべきではないという意味ではありません。単に、多くの無意味に見えるフィールドを埋めることのコストがなくなっただけで、コードが何をするかを理解することのコストは大幅に増加しました。 エラーは悪いことではありません。私が使用した多くの優れたAPIは、私の愚かさを乗り越えてくれました。例えば、小文字のみのフィールドに大文字を受け入れたり、Postgresのブール値がtrue、yes、on、1を受け入れるように、複数のキーを受け入れたりします。これはエージェントのコードベースにとっては積極的に悪いことです。異なる関数が同じものに対して異なる値を使用することになり、後でレビューする際に頭痛の種となります。 最新のハーネスは、デバッグ時にドキュメントを読むことが期待できます。エラーメッセージでそれに言及すると、さらに良いでしょう。半分正しいマージは起こるべきではありません。エージェントが自分で値をマージするように、明示的にマージさせましょう。人間にとっては、オンボーディングのエラーは悪いことであり、最小限に抑えるべきです。エージェントにとっては、それは何かが実際に何を意味するのかを明確にする機会です。 これは、すべてがエラーが良いという意味ではありません。方向性のない空のエラーはエージェントを混乱させますが、それは悪いエラーに対する議論であり、エラーそのものに対するものではありません。良いエラーは驚くべきツールです。それは、AIがAPIについて誤解しており、それを解決したことを意味します。そして、AIは誤解するでしょう。すべてがコンテキストにあっても、後方互換性の問題や混乱が発生します。明確さにつながるエラーはこれを解決します。 エラーは、エージェントがハッピーパスを見つけるための最良の表面の1つですが、それらが正確である場合に限ります。人間とは異なり、エージェントは指示を文字通りに実行するため、曖昧または間違ったエラーは回復ではなく混乱につながります。私たちのデータでは、エージェントが直面する摩擦の27％はエラーに起因しているため、優れたエラー設計は優れたドキュメントと同じくらい重要です。 Mika Sagindyk 2027.devの共同創業者 Mikaからさらに読む 幻覚ではなく、分布において。APIが不明瞭な場合、エージェントは幻覚を起こし、似たようなAPIを見たことがあるように使用する傾向があります。このため、一般的なフィールド名よりも具体的なフィールド名を好みます。フィールド名を取ってみましょう。APIによっては、表示名として使用したり、完全なIDとして使用したり、スコープ付きIDとして使用したりします。エージェントに10個の異なるユースケースでnameというフィールドを使用するように依頼すると、5つの異なる方法で使用します。そして、上記のポイントに従うと、1つだけが正しいことができます。nameにはスペース、スラッシュ、ダッシュ、アンダースコア、絵文字を含めることができますか？ この問題は、コードベースが成長するにつれて増大します。将来このコードを読むレビュー担当者は、再びそれらの5つの異なる方法でnameを解釈するでしょう。具体性を優先してください。nameの代わりに、displayName、slug、externalId、または同じ仮定を伴わない任意の名前を好みます。これらはエージェントが本当に理解できる言葉であり、立ち往生したり誤解したりしません。ドキュメントコメントは、正しい解釈をさらに強化するのに役立ちます。 感情ではなく、事実。エージェント時代のAPIの価値は、エージェントまたはその人間のチームが内部で再現できない事実を提供することです。それは、請求書が支払われた、メッセージが送信された、または仮想マシンがプロビジョニングされたという事実（Freestyle VMのあからさまな宣伝）である可能性があります。それ以上のユーティリティはほとんど無関係であり、どこかに到達する方法を説明するドキュメントやガイドに置き換えることができます。その意味で、APIの標準を言語固有のパターンに公開すること以上のことを行うAPIのSDKのほとんどには懐疑的です。例えば、APIエラーを型安全なTypeScriptエラーに変換するなどです。 実践に移す Freestyleは、仮想化品質（Docker-in-Docker、ネストされた仮想化、高度なネットワーキングなど、他社がサポートしないすべてをサポート）、スケール（公開ティアで8倍大きいメモリフットプリントをサポートし、エンタープライズ向けにはさらに多く）、設定（OS全体、rootFS、ネットワーキング、プライベートVPCおよびVPN接続を含む）、安定性、そして実際に機能する完全なメモリ スナップショット）によって測定される、サンドボックス空間で最も強力な仮想マシンを構築しています。すべて400ミリ秒でプロビジョニングされます。 これにより、私たちは奇妙な立場に置かれています。私たちは、根本的に複雑な問題に取り組むユーザーと協力しています。これらの問題はオープンエンドで、デバッグが困難で、業界で最も難しいものです。他のサンドボックスではできないことを求めて、人々は私たちに来ます。そのために、私たちはできるだけ多くのことをしないように最善を尽くしています。つまり、上記で述べた事実を、可能な限り一貫して提供することです。 以前は、できるだけ多くの複雑さを隠そうとしていました。宣言的な関数型ビルドシステムとSDKユーティリティを組み合わせたパッケージを作成し、依存関係を持つパッケージを記述できるようにしました。その考えは、「ユーザーがBunを望むなら、Bunパッケージを提供し、内部のことを心配させないようにしよう。なぜなら、私たちはBunをうまく機能させたからだ」というものでした。しかし、そうではありませんでした。それは十分に設定可能ではなく、常に質問の方が答えよりも多く、エージェントはそれを理解できず、あらゆる方法で誤用しました。最終的に、これらの抽象レイヤーを使用しようとする複雑さが、私たちへのオンボーディングの最も難しい部分になりました。下のコードスニペットがどれほど美しく見えるか、そしてそれが何であるかについてどれだけ得られるかが少ないかを見てください。 old.ts import { freestyle, VmSpec } from "freestyle