OpenAI Agents SDK、一時停止した実行に後から入力を差し込めるように──JS版とPython版が同時に対応

OpenAI Agents SDKでツール承認待ちなどにより実行（run）が一時停止しているとき、これまでは再開時に決まった形の応答しか渡せなかった。JavaScript版v0.15.0（2026年8月11日公開）とPython版v0.20.0（2026年8月11日公開）、同じ日付で公開された両言語のリリースノートに、この制約を緩める機能が記録されている。

3行まとめ

• JS版RunState.addInput()とPython版RunState.add_input()が、同じ2026年8月11日に両SDKへ同時追加された。一時停止中のrunに新しい入力をステージできる
• 実装ソース（runState.ts／run_state.py）を比較すると、呼び出せない条件（拒否理由のエラーメッセージ文言まで含めて）がほぼ1対1で一致しており、単なる名称のcamelCase/snake_case変換にとどまらない、機能面で厳密に対応した実装だった
• 同じリリースにMCP TypeScript/Python SDK v2への対応も同時収録。ただし独自のMCP HTTP認証・クライアントファクトリを使うアプリは、依存するMCP SDKのメジャーバージョンとの整合を自分で取る必要がある

一時停止中に新しい入力をステージする

JavaScript版のリリースノートはこう説明している。

RunState.addInput() can stage new input while a run is paused, and pendingInput survives serialization until the next safe model request. JSON-compatible tool return values retain their structure across RunState serialization, while canonical invocation evidence prevents approved or completed local tool calls from being rebound incorrectly. Applications may explicitly approve an otherwise unsafe non-streaming model replay with approveUnsafeReplay: true.

（RunState.addInput()は、runが一時停止している間に新しい入力をステージできる。pendingInputは、次に安全にモデルへリクエストを送れるタイミングまでシリアライズを生き延びる。JSON互換のツール戻り値はRunStateのシリアライズをまたいで構造を保持し、正規の呼び出し証跡により、承認済みまたは完了済みのローカルツール呼び出しが誤って再バインドされることを防ぐ。アプリケーションは、本来は安全でない非ストリーミングのモデルリプレイをapproveUnsafeReplay: trueで明示的に承認できる）

Python版のリリースノートも同じ機能を短くこう記している。

RunState.add_input() can stage durable user input before a resumed model call, with guardrail, persistence, and serialization support.

（RunState.add_input()は、再開されるモデル呼び出しの前に、永続的なユーザー入力をステージできる。ガードレール・永続化・シリアライズに対応する）

命名規則こそJavaScript版はaddInput()（キャメルケース）、Python版はadd_input()（スネークケース）と言語の慣習に合わせているが、機能としては同じもので、同じ日に両言語のSDKへ入っている。

同じリリースにあったもう1つの機能：MCP v2ネゴシエーション

これと同じv0.15.0（JS）／v0.20.0（Python）には、MCPプロトコルまわりの対応も入っていた。JS版はこう説明している。

Local MCP connections now use the MCP TypeScript SDK v2 client and negotiate the 2026-07-28 protocol where available, with compatible fallback for existing v1 servers. Applications using MCPServerStdio, MCPServerStreamableHttp, or MCPServerSSE do not need to bridge the v1 and v2 SDK packages themselves.

（ローカルMCP接続は、MCP TypeScript SDK v2クライアントを使うようになり、可能な場合は2026-07-28版プロトコルをネゴシエートし、既存のv1サーバーには互換フォールバックする。MCPServerStdio・MCPServerStreamableHttp・MCPServerSSEを使うアプリケーションは、v1とv2のSDKパッケージを自分でブリッジする必要がなくなる）

Python版は同じ内容をこう記している。

Local MCP connections support MCP Python SDK v1 and v2 across stdio, SSE, and Streamable HTTP transports.

（ローカルMCP接続は、stdio・SSE・Streamable HTTPのトランスポートを通じて、MCP Python SDKのv1とv2の両方に対応する）

Python版のリリースノートには、もう1点、実務上見落としやすい注意もあった。

Applications using custom MCP HTTP authentication or client factories must use the HTTP types owned by the installed MCP major version, or pin mcp<2.

（カスタムのMCP HTTP認証やクライアントファクトリを使っているアプリケーションは、インストールされているMCPのメジャーバージョンが所有するHTTP型を使うか、mcp<2に固定する必要がある）

つまり、MCP Python SDK自体がv1からv2へ移行する過程で（当サイトの別記事でも扱った）、OpenAI Agents SDK側もv1・v2の両方をまたいで動くように対応したが、認証やクライアントファクトリを自作している場合は、依存するMCP SDKのバージョンとの整合性を自分で管理する必要がある、という注意書きだ。

いつaddInput()が呼べないか——実装ソースで確認した4つの拒否条件

リリースノートの説明だけでは「一時停止中ならいつでも入力を追加できる」ように読めるが、実際のソースコード（JS版runState.ts・Python版run_state.py）を取得してaddInput()／add_input()の中身を確認すると、次の4つの条件に当てはまる場合はUserErrorが投げられ、入力を追加できないことが分かった。

この4条件とエラーメッセージの文言は、JS版とPython版でほぼ一字一句同じだった。つまり「同じ日に両言語へ来た同じ機能」という説明は、リリースノートの言葉のレベルだけでなく、実装コードの拒否ロジックのレベルでも裏付けが取れる。Python版のdocstringには「Terminal states reject new input before mutating the state（終了状態は、状態を変更する前に新しい入力を拒否する）」という一文もあり、失敗する場合は状態を書き換える前にエラーになる、という安全設計が意図されていることも分かった。

2つの機能が同時に来た意味

RunState.add_input()は「実行の途中で人間やシステムが割り込んで新しい情報を渡す」ためのAPIで、MCP v2対応は「ツールを提供する外部サーバーとの通信規格を最新に保つ」ためのAPIだ。性質は異なるが、どちらも「長時間動くエージェントのrunを、外の世界の変化にどう対応させるか」という共通のテーマの下にあると読める。承認待ちで止まっているエージェントに新しい指示を追加で渡せる、というadd_input()の使い方は、人間が最終承認を行うワークフローとの相性が良さそうだ。

実際に一時停止中のrunへ入力を追加する検証は行っていない

本記事はopenai-agents-js v0.15.0とopenai-agents-python v0.20.0のリリースノート本文に加え、両言語のRunState実装ソース（runState.ts／run_state.py）を突き合わせて書いている。ただし、この記事を書いている自分の手元で、実際にツール承認待ちの状態を作り、add_input()／addInput()で新しい入力を差し込んで再開させる検証は行っていない。approveUnsafeReplay: trueで承認できるという「本来は安全でない非ストリーミングのモデルリプレイ」が具体的にどのような状況を指すのかについても、ソースコード中の該当箇所までは今回は特定できなかった。MCP v1・v2両対応の実際の切り替わりを、自分でMCPサーバーを立てて確認する検証も行っていない。

関連記事: MCP Python SDK v2安定版 / AIエージェントとは / AnthropicとOpenAIのSDKが揃って「Standard Schema」対応

感想・指摘はコメント欄へ。