OpenAI APIやAgents SDKを使って開発を始める前に知っておきたいこと
最近、OpenAI Agents SDK、Chat Completions、Responses API でAIエージェントを開発する機会が多いです。最初に誰かが教えてくれていたら助かったなと感じたことがいくつかあったので、振り返りも兼ねてメモとして残したいと思います。二次情報としてあまり公開されておらず、一次情報を辿るのに時間がかかる部分もあったので、そこの橋渡し的なことができれば良いなと考えています。
まずは「ベストプラクティス」に目を通す
OpenAI公式の「Production best practices」で、組織設定やレイテンシーの改善といった開発を始めるのに必要な要点を抑えることができます。
個人開発で高額な請求が届いてしまった・・なんてことを見聞きしますが、ほかのサービス同様に月次予算とアラートを設定できるので、最初にやっておくと事故が減るので推奨します。
Organization Verification
GPT-5, GPT-5 mini, GPT-5-codex, GPT-5 pro の Streaming や Sora 2, Sora 2 pro を使用するには、Organization Verificationが必須です。
先日OpenAI Devdayで発表されたAgent Bulderでは、ワークフロー作成時のデフォルトのモデルが GPT-5 となっていることもあり、それをそのまま使うとレスポンスが返ってこないケースも報告されています。
またSora 2 APIでウォーターマークのない動画をを大量生成しようとしても、認証済みでないと API にアクセスできないため注意が必要です。
認証自体は簡単にできるので、開発前にサクッと終わらせておくのが良いです。
レートリミットをコントロールする
各モデルのレートリミットに 60,000 rpm のような1分単位の記載があったとしても、実際は 1,000 rps 等の小さな単位で分割して適用される仕様です。そのため1分間のレートリミットには抵触していない使用量だとしても、秒間のレートリミットでエラーになることがあります。短時間で集中的な負荷が起きる場合やコンテキストが巨大なリクエストが頻発する場合には注意が必要です。
レートリミットに抵触しないように、API呼び出し時のレスポンスヘッダーに含まれる残リクエスト数・残トークン数やSDKのレスポンスのusageを参照しハンドリングしたほうがよいです。またこれに限った話ではないですが、堅牢な作りにするためにバックオフとリトライを入れます。
このあたりの実装もOpenAI公式からCookbookが出ていたりします。
パフォーマンスを最適化する
レートリミットに抵触しないように推論コストを下げたり、スループットやコストを最適化するポイントは色々あると思いますが、簡単に代表的なものだけ記載します。
Batch APIへ逃がす
そもそも同期的なレスポンスが不要な場合、最初からBatch APIへ処理を逃がすのがよいです。既存のモデルごとのレートリミットとは別枠で、入出力のコストも50%削減できるため、スループットを優先する用途では非常に効果的です。
プロンプトチューニングガイドを読む
基本は「簡潔に」「明確に」ではあるんですが、モデルごとにガイドが出ているので、それを読み込んで、プロンプトチューニングをしていく必要があります。これがちゃんとやろうとするとかなり大変です。
Parameters を調整する
max_output_tokensで出力上限を設定したり、要件やタスクの特性に応じてverbosityやreasoning_effortを設定するのは必須です。例えば低遅延な要件の場合にはlowやminimalを設定し、難易度の高いタスクにはmedium以上を使用するなどです。
ただし、Responses API の 組み込みツール（ファイル検索・画像生成など）は minimalをサポートしていないため注意が必要です。
Parametersに関する補足
モデルやAPIによって使用可能なパラメータは細かい点が異なります。
temperatur、top_p、logprobs といったサンプリング系のパラメータは、推論モデルでは使用できず、エラーになります。公式のAPI referenceをパッと見て使えると思っても、gpt-4.1などの異なるモデルが指定された例だったりということもあるので、使用するモデルのガイドに目を通した方がよいです。
Chat Completions APIでは通っていた max_tokens, max_completion_tokens が、Responses APIではmax_output_tokensに置き換えられていたりもします。
Discussion