エージェント向けAPIの設計
Designing APIs for Agents (freestyle.sh)
要約
この記事は、人間向けではなくAIエージェント向けにAPIを設計する際の考慮事項について論じています。AIエージェントはドキュメント全体を一度に読み込み、大量のコードを生成できるため、APIは明確性、正確性、そして詳細なエラーメッセージを重視する必要があります。デフォルト値の排除、厳密なエラーハンドリング、そして曖昧さを排除した具体的なフィールド名が、エージェントが効率的かつ正確に機能するために不可欠であると主張しています。
全文翻訳
エージェント向けAPIの設計
エージェント向けAPIの設計は、人間向けAPIの設計とは異なります。今日、APIのほとんどの利用者はエージェントが書いたコードを通じてそれを行っています。これは2年前には真実ではなく、API設計の考え方を変えるものです。
私はもはや、人間向けに構築されたシステムのほとんどを信じていません。パッケージには懐疑的で、ユーティリティには反対し、今は極端に長い名前を支持しています――これらはすべて、過去24ヶ月で私が完全に考えを180度変えた意見です。
人間向けの良いAPI
人間向けの良いAPIを設計する際、私の最初のステップは、最小限の利用パターン、オンボーディング、そしてトップ10のユースケースをスケッチすることです。そこから、理想的に書きたいコードを想像します。次に、それを使ってみて、行き詰まったエッジを見つけ、必要に応じて良いデフォルト値と設定を追加します。
私は、50行のコードで機能的なものを提供したいと考えています。そこから、APIはより多くの機能に手を伸ばすことが明白になるほど親しみやすいものであるべきです――そこが彼らが探す場所です。理想的には、20個のフィールドのうち1つしか必要としない人は、求めているフィールドの周りのオートコンプリートを通じてのみ、他の19個を認識するようになるべきです。良いSDKは、ドキュメントを最小限かすめるだけで使えるほど自己説明的であるべきです。
素晴らしい例をいくつか示します。
client.messages.create(
body="Join Earth's mightiest heroes. Like Kevin Bacon.",
from_="+15017122661",
to="+15558675310",
)
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について誤解しており、それを解決したことを意味します。そして、それは誤解するでしょう。すべてがコンテキストにあっても、後方互換性の問題や混乱は発生します。明確さにつながるエラーはこれを解決します。
エラーは、エージェントがハッピーパスを見つけるための最良の表面の1つですが、それは正確である場合に限ります。人間とは異なり、エージェントは指示を文字通りに実行するため、曖昧または間違ったエラーは回復ではなく、混乱を引き起こします。私たちのデータでは、エージェントが直面する摩擦の27%はエラーに起因するため、優れたエラー設計は優れたドキュメントと同じくらい重要です。
[画像: Mika Sagindyk]Mika Sagindykco-founder of 2027.devRead more from Mika
-
幻覚ではなく、配布で。 APIが不明瞭な場合、エージェントは幻覚を見て、似たようなAPIを見たときのように使用する傾向があります。このため、私は一般的な名前よりも具体的なフィールド名を好みます。
nameフィールドを見てみましょう。一部のAPIでは表示名として使用され、他のAPIでは完全なIDとして、さらに他のAPIではスコープ付きIDとして使用されます。エージェントに10個の異なるユースケースでnameを含むAPIを使用するように依頼すると、5つの異なる方法で使用されます――そして上記のポイントに従うと、正しいのは1つだけです。nameにはスペース、スラッシュ、ダッシュ、アンダースコア、絵文字を含めることができますか?
この問題は、コードベースが成長するにつれて増幅します。将来このコードを読むレビュー担当者は、再びそれらの同じ5つの異なる方法でnameを解釈するでしょう。明示性を優先してください。nameの代わりに、displayName、slug、externalId、またはあなたが選択した、同じ仮定を伴わない任意の名前を好みます。これらはエージェントが真に理解できる言葉であり、立ち往生したり誤解したりしません。ドックコメントは、正しい解釈を固めるのにも役立ちます。
- 感情ではなく、事実。 エージェント時代のAPIの価値は、エージェントまたはその人間のチームが内部で再現できない事実を提供することです。それは、請求書の支払い、メッセージの送信、または仮想マシンのプロビジョニング(Freestyle VMsの宣伝)という事実かもしれません。それ以上のユーティリティはほとんど無関係であり、どこかに到達する方法を説明するドキュメントとガイドで置き換えることができます。その線に沿って、APIの正規表現を言語固有のパターンで公開する以上のことを行うAPIのSDKのほとんどには懐疑的です――例えば、APIエラーを強く型付けされたTypeScriptエラーに変換するなどです。
実践に移す
Freestyleは、仮想化の品質(Docker-in-Docker、ネストされた仮想化、高度なネットワーキングなど、他社がサポートしないすべてをサポートしています)、規模(公開ティアで8倍大きいメモリフットプリントをサポートし、エンタープライズ向けにはさらに多く)、設定(ルートFS、ネットワーキング全体、プライベートVPCやVPN接続を含む完全なオペレーティングシステムをサポートしています)、安定性、そして実際に機能する完全なメモリ スナップショット(;) — すべて400ミリ秒でプロビジョニングされます)で測定される、サンドボックス空間で最も強力な仮想マシンを構築しています。
これにより、私たちは奇妙な立場に置かれています。私たちは、根本的に複雑で、オープンエンドで、デバッグが難しく、業界で最も困難な問題を解決するユーザーと協力しています――他のサンドボックスではできないことを求めて私たちに来ます。そのために、私たちはできるだけ多くのことをしないように最善を尽くしています。ただ、上記で提供した事実を、可能な限り一貫して提供します。
私たちは、できるだけ多くの複雑さを隠そうとしました。宣言型の関数型ビルドシステムとSDKユーティリティを組み合わせたビルドシステムを構築し、依存関係を持つパッケージを作成できるようにしました。その考えは、「ユーザーがBunを望むなら、Bunパッケージを提供し、内部のことを心配しないようにしよう。なぜなら、私たちはBunをうまく機能させたからだ」というものでした。しかし、私たちはそうしませんでした。それは決して十分に設定可能ではなく、常に質問の方が答えよりも多く、エージェントはそれを理解できず、あらゆる可能な方法で誤用しました。最終的に、これらの抽象レイヤーを使用しようとする複雑さが、私たちへのオンボーディングの最も難しい部分になりました。下のコードスニペットがいかに美しく見えるか――そして、何が起こっているのかについてどれだけ少ない情報しか得られないかを見てください。
import { freestyle, VmSpec } from "freestyle";
import { VmBun } from "@freestyle-sh/with-bun";
const { vm } = await freestyle.vms.create({
spec: new VmSpec({ with: { bun: new VmBun() } }),
});
await vm.bun.install({ deps: ["zod"], global: true });
await vm.bun.runCode(`import { z } from "zod"; console.log(z.string().parse("hi"))`);
これは、人間が迅速に何かを機能させ、後で詳細を掘り下げる必要があるという私の以前の信念を中心に最適化されていました。しかし、私たちは数ヶ月前にすべてを廃止しました。複雑なSDKパッケージと間接的なものをすべて削除し、代わりにガイドにしました。今では、そのような複雑なことをしたい場合は、エージェントにガイドを読むように指示し、それに関連するコードを取得し、プロジェクトの規範に合わせて適応させ、望むように動作をカスタマイズします。これにより、オンボーディング体験がはるかにクリーンになり、最終的なコードもはるかに明確になります。
import { freestyle } from "freestyle";
const { vm } = await freestyle.vms.create();
// 単に実行する — パッケージをインストールし、ファイルを書き込み、実行します。専用のAPIはありません。
await vm.exec("cd /tmp && /opt/bun/bin/bun add zod");
await vm.exec(`echo 'import { z } from "zod"; console.log(z.string().parse("hi"))' > /tmp/main.ts`);
const { stdout } = await vm.exec("cd /tmp && /opt/bun/bin/bun run main.ts");
他のAPIやSDKでの実践
🤖 エージェントフレームワーク
-
🏆 優秀 — Flue Framework。 エージェントが必要とするコアな事柄に対して最小限のセマンティクスを提供します。すべてがプラグ可能な関数であり、主に他のエージェント部分との相互作用を通じて定義されます。Flueは、何をするかについて完全に明確であり、実際にはあまり多くを行いません。ハーネス構築のための共有セマンティクスを提供します。
import { defineAgent } from "@flue/runtime"; // エージェント全体が設定を返す1つの関数です — すべての部分が値です。 export default defineAgent(() => ({ model: "anthropic/claude-sonnet-4-6", instructions: "Triage the incoming GitHub issue.", })); -
👍 良好 — Vercel AI SDK。 エージェントへの接続に関する共有SDKセマンティクスであり、非常に役立ちます。
generateTextとstreamTextは優れた、明確な関数であり、エージェントが多くの異なる推論APIとの複雑な対話を事実として扱えるようにします。import { generateText } from "ai"; import { openai } from "@ai-sdk/openai"; // 1回の呼び出しで、1つの事実が出力されます。 const { text } = await generateText({ model: openai("gpt-5"), prompt: "Summarize this transcript.", }); -
😬 中 — Mastra。 Mastraは多くの優れたスケジューリングとワークフローを備えています。そのエージェントのほとんどは、自分で実装できるプラグ可能な型から構築されています。とはいえ、多くの場所で大げさで不明瞭だと感じます。例えば、そのWorkspace、Filesystem、Sandboxセマンティクスは、内部実装者に対して非常にデータ破壊的です――FUSEをサポートしないDockerサンドボックスは、ベアメタルGPUを備えたSQLiteファイルシステムとは同じではありません。これはMastraで解決可能ですが、エージェント中心の設計は、契約を大幅に削減し、異なるパターンの実装方法に関するガイドに置き換えるでしょう。
-
💀 悪い — Eve。 Next.jsを取ってエージェントフレームワークにしたかのようです。2016年向けには素晴らしいです。私の理解では、そのスキルシステムは完全にモノリシックでプログラム不可能であるため、ロードを変更したい場合は動的システムのためにそれを放棄する必要があります。
--- description: How this team defines revenue. Load before any revenue question. --- Revenue is net of refunds, over the subscription term. Weeks are Monday-anchored, UTC.スキル全体がこのファイルです。ロードはビルド時にその
description文字列によって決定されます――ロードするタイミングや方法をプログラムするためのフックはありません。
📦 サンドボックスAPI
-
🏆 優秀 — Freestyle(ひいき目すぎますか🙄)。FreestyleのAPIはあまり多くを行いません。言ったことを実行します。VMでやりたいことすべてを可能にするAPIがありますが、他社と同じユーティリティで肥大化させることはありません。他のプロバイダーが
box.git.cloneユーティリティを使用するように言うところで、私たちはAIにgitClone関数を書きたいなら書くように言います――深さ、認証戦略、その他すべてを選択できます。それはすべてexecのラッパーにすぎません。import { freestyle } from "freestyle"; const { vm } = await freestyle.vms.create(); // あなたが望むラッパーを書いてください。すべてはexecにすぎません。 const gitClone = (url: string, dir: string, depth = 1) => vm.exec(`git clone --depth ${depth} ${url} ${dir}`); await gitClone("https://github.com/acme/app", "/app"); -
👍 良好 — E2B。 E2Bはいくらか自制心を示しています――それほど多くはありません。彼らのユーティリティの問題の素晴らしい例は、
sbx.runCode関数です。最初の引数はコードの文字列を取り、2番目のオプション引数はオプションの設定フィールドです(人間中心のデザインの典型例であり、エージェントには悪い)。それをプッシュすると、言語を好きなもの(js、py、R、bash)に設定できますが、すべてのE2Bサンドボックスがそれらの言語すべてを持っているわけではありません。しかし、他の場所では良い自制心があります――SDKをかなり一貫性があり、デバッグ可能に保っています。import { Sandbox } from "@e2b/code-interpreter"; const sbx = await Sandbox.create(); // 言語はオプションバッグに埋め込まれています — すべてのサンドボックスがそれを持っているわけではありません。 await sbx.runCode("summary(cars)", { language: "r" }); // ...これは実際には次のとおりです: await sbx.commands.run("Rscript -e 'summary(cars)'"); -
😬 中 — Daytona。 Daytonaは、VNC、Git、Docker、Webターミナル、LSPなどをSDKに組み込んでいます――すべて設定不可能で、一部は一部のDaytonaサンドボックスではサイレントにサポートされていません。Freestyleもこれらすべてをサポートしていますが、非プラグ可能なSDKメソッドの背後にそれらを組み込んでいないため、カスタマイズできます(ガイドを参照してください)。それらは一般的にほとんどのケースで利用可能ですが、私はそれらを使用しませんし、あなたのエージェントも使用すべきではありません。DaytonaはこれらをSDKに組み込むことが重要だと考えているため、半ダースの言語でSDKを提供しています。これは人間を対象としているように見えます。理想的には、エージェントはAPIを十分に理解しているため、これは関連性がありません。
import { Daytona } from "@daytonaio/sdk"; const sandbox = await new Daytona().create({ language: "typescript" }); // Daytonaがあなたには自分でできないと思うこと await sandbox.git.clone("https://github.com/acme/app", "/app"); await sandbox.fs.replaceInFiles(["/app/config.ts"], "dev", "prod"); await sandbox.git.add("/app", ["TrackedDevice"]); await sandbox.git.commit("/app", "ship it", "bot", "bot@acme.dev"); await sandbox.git.push("/app"); // または... await sandbox.process.executeCommand( "cd /app && sed -i 's/dev/prod/' config.ts && git commit -am 'ship it' && git push", );
結び
エージェント向けに構築することは、ついに人間のエンジニア向けに構築することから分岐しています。多くのコア原則は引き継がれます:良いドキュメントは重要であり、使用パターンに従い、明確なエラーを出すことは依然として重要です。しかし、かつて重要だったことの多くはもはやそうではありません。コード行数、オンボーディングのエラー、生産的になるために必要な読書量、オンボーディングに必要なトークンさえも、APIがエージェントにとってどれだけ良いかという点では、すべてかなり無関係です。ここにあるすべては、GPT-4.5では正しくなかったでしょう。そのため、GPT-6では関連性がないかもしれませんが、これがどこへ向かうのか楽しみにしています。