Function Calling Migration：旧APIから新SDKへの実践ガイド

移民の真の出発点:単に終点を変えるだけではない

モデルバージョンのアップグレード発表で「XX APIは非推奨となりました。新しいSDKに移行してください」と表示されたとき、最初の反応はリクエストURLとパラメータ名を置き換えることです。 しかし、ファンクションコーリングにとって、この考え方こそが移行失敗の最大の原因です。

関数呼び出し移行の核心はAPIアドレスの変更ではなく、ツール呼び出しメカニズムのパラダイムシフトにあります。 旧チャット補完APIのOpenAIでは、関数はfunctionsパラメータで定義され、モデルはfunction_callオブジェクトを返します。 新しいResponses APIまたはAssistants APIでは、ツール定義、呼び出しコンテキスト、状態管理がtoolsパラメータとtool_choice、並列関数呼び出し、より厳格な出力フォーマット制約に統合されています。

実際の事例:開発チームが旧APIから20の関数定義を直接コピーしたところ、モデルが頻繁に「無効なツール呼び出し」エラーを返すことを発見しました。 調査の結果、新しいAPIでは各ツールのdescriptionフィールドにパラメータ依存関係を明示的に指定する必要があります(例:「この関数を呼び出す前にユーザーIDを取得してください」など)が、旧APIではこれを強制しなかったことが判明しました。

最も起こりやすい失敗:暗黙の文脈喪失

移民における最も隠れた落とし穴はコンテキスト状態の喪失です。 旧APIでは、開発者は関数呼び出しの中間結果をメッセージ配列に差し込むことに慣れており、モデルが自然に履歴を認識できるようにしていました。 しかし、新しいAPIのエージェントループ(例:run + tool_outputsパターンを用いる場合)では、ツールの実行結果はthreadまたはstep構造に厳密に従って返す必要があります。 フォーマットが正しくない場合、モデルはこれまでのすべてのツール出力を無視し、エージェントのワークフローが中断されます。

具体的なエラーシナリオ:

• マルチステップツールチェーンでは、まずsearch_databaseを呼び出して10件のレコードを返し、次にformat_resultsを呼び出して前のステップの結果に基づくテーブル生成を要求します。 しかし、新しいAPIでは、search_databaseの出力を非標準的な方法でtool_outputsに挿入すると、モデルはそのステップを失敗とみなし、format_resultsをスキップします。
• 解決策:SDKのsubmit_tool_outputsインターフェースを厳格に守り、各出力に対応するtool_call_idが付くこと、そして出力内容がモデルのコンテキスト制限(通常4096トークン)を超えないようにすること。

ステップ1:監査とリファクタリングのツール定義

今すぐ移行を実装したい場合、最初のステップはコードを変更するのではなく、ツール定義監査を実行することです。

1. すべての既存の関数を一覧表示する:名前、パラメータ、リターン形式を含む。 前提ツールの出力に依存する関数(例:「チャート生成」は「クエリデータ」の結果に依存します)を必ずマークしてください。
2. 細分度で分割:新しいAPIでは、各ツールが一つのことだけを行うことを推奨しています。 古いAPIでよく使われていた「ユニバーサル関数」(例:execute_anything)は、単一責任関数に分割されなければならず、そうしないとモデルが簡単に混乱してしまうことがありました。
3. 記述のオーバーライド:各ツールの説明には前提条件、出力フォーマット、典型的な呼び出しシナリオが含まれなければなりません。 例えば:
   • 古い:"获取天气数据"
   • 新作:"根据城市名获取当前天气。需要先调用 check_city_exists 确认城市有效。返回 JSON 格式：{temperature, humidity, condition}"
4. エラー処理ツールを追加:モデルが処理できない例外を扱うためのreport_errorツールを定義し、ループ呼び出しを回避します。

監査を完了した後、開発環境で新しいエージェントテストスクリプトを作成し、新しいAPIのclient.responses.createまたはclient.beta.threads.runs.createを使って、各ツール呼び出しを一つずつ検証します。

実践的な道:シンプルな移住のケース

古いAPIコードがあるとします: ''python response = openai.ChatCompletion.create( model="gpt-4", messages=[{"role": "user", "content": "北京天气如何？"}], functions=[{ "name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}} }] ) '`

迁移至新 API（OpenAI Python SDK v1.x+）： 'python from openai import OpenAI client = OpenAI()

response = client.responses.create( model="gpt-4o", input=[{"role": "user", "content": "北京天气如何？"}], tools=[{ "type": "function", "function": { "name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}, "description": "根据城市名获取天气。参数 city 必须是中国城市的中文名称。" } }] ) '

注意新 API 使用了 input 而非 メッセージ，且 tools 数组内每个工具需要显式 type 和更详细的 `description'。

未来の方向性:関数呼び出しからエージェントループへ

移行の背後にある論理を理解することは、より複雑なエージェントワークフローに備えることです。 ツールの定義、コンテキスト管理、エラーリカバリーをマスターしたら、マルチツールオーケストレーション、メモリ管理、MCPプロトコル統合などの高度なトピックに進めます。

一般の開発者からエージェントエンジニアに移行したい場合は、このコンテンツの次のステップは、より体系的なオリジナル記事やコースに参加することです。