AIエージェント API 導入でOpenAI Agents APIを採用する場合、既存のAIエージェントRFPを一から書き直す必要はありません。業務の完了条件、承認境界、データ分類、KPIといった一般要件はそのまま使えます。追加すべきなのは、Agents API固有の運用差分です。具体的にはsessionとturnの保存、stream切断後の復旧、input-time connectionの最大5分待ち、environment lifecycle、hosted/self-hosted executor、鍵の分離、subagentが共有するfilesystem、同時実行数、traceとAPIの境界です。
OpenAIは2026年9月10日、Agents APIをpublic betaとして発表しました。Codexを支えるharnessをAPIとして提供し、長時間session、context management、tool利用、subagents、OpenAI-hostedまたはself-hostedの実行環境を扱います。これはagent loopの多くをマネージド化しますが、業務上のexactly-once実行や自動復旧を保証するものではありません。公式ドキュメントにも、完了したturnで全toolが成功したとは限らないこと、切断時に取り逃したstream eventはreplayされないこと、自社環境の再接続・停止・永続化は利用側が担うことが明記されています。
一般的な導入判断はAIエージェント導入2026、承認・業務統制はAIエージェント業務フローのガバナンス、データ分析用途は製造業のデータエージェント導入をご覧ください。本稿ではそれらを繰り返さず、既存設計へ加える「Agents API運用設計の追加条項」に限定します。
AIエージェント 基盤にAgents APIが追加する固有コンポーネント
Agents APIの運用では、アプリケーション、OpenAIが管理するharness、session、environment、executor、tool接続を別物として扱います。environmentを使わない構成では、harnessはremote MCPやfunction toolを呼べますが、built-in shell、workspace file、executor MCPは使えません。openai_hostedではOpenAIがsandboxを作成・管理し、harnessがそこでcommandを実行します。self_hostedでは利用側が環境を用意し、内部でcodex exec-serverを動かしてAgents APIへoutbound WebSocket接続します。
この構成差は責任分界へ直結します。
| 対象 | OpenAI側で提供されるもの | 導入側で追加するもの |
|---|---|---|
| Session | session/turn/itemの保存、継続input | 業務IDとの対応、保持・削除方針 |
| Stream | 作業中のevent配信 | 切断検出、saved item再取得、UI再同期 |
| Hosted environment | sandbox provision、command実行 | network policy、投入file、成果物回収 |
| Self-hosted environment | harnessとexecutor接続方式 | compute、起動、再接続、停止、永続化 |
| Subagents | 委譲、coordination event、concurrency設定 | 作業分割、共有file競合、コスト上限 |
| Trace | dashboard上のturn/tool/subagent表示 | 業務台帳との相関、外部監視の代替ログ |
従来の「モデルAPI」と同じ感覚で一つのrequest/responseとして監視すると、sessionは残っているのにexecutorが落ちている、turnはcompletedだがtoolが失敗した、画面は切断したが裏で処理が続いている、といった状態を見落とします。
session・turn・itemを業務IDと分ける
Sessionは会話と作業をまとめる入れ物で、複数のturnを含みます。Turnは一回のinputに対する作業サイクルで、その中にmodel response、tool call、command、subagent coordinationなどのitemが記録されます。Agents APIがsessionをdurableに保つことは、業務データベースのtransactionを提供することではありません。
最低でも次のIDを分けます。
session_id：Agents APIの継続状態。turn_id：一回のinputに対する実行単位。business_execution_id：見積照合、設備異常調査などの業務依頼。side_effect_id：ERP更新、メール作成、file保存など一つの副作用。
一つの業務依頼を途中で追加質問しても、同じbusiness executionに複数turnが紐づく場合があります。反対に、sessionを作り直しても同じ業務を再開する場合があります。したがって、session_id = 業務IDとみなしてはいけません。自社台帳にmappingを持ち、外部更新にはside-effect IDを冪等キーとして渡すか、更新済みかを照会してから再実行します。
context compaction後も残す正本
Agents APIは長時間作業を支えるためcontext compactionを行いますが、圧縮された会話だけを業務の正本にしません。チェックポイントとして、入力版、規程版、完了step、未完了step、成果物hash、外部record ID、承認状態、再開可能点を構造化して保存します。これは一般的な会話履歴ではなく、Agents API sessionがcontext windowをまたぐことに対する追加設計です。
turn completedを業務成功に変換しない
OpenAI-hosted sandboxの公式ガイドは、completed turnでもすべてのtoolが成功した保証はないと説明しています。受入判定では、turn outcomeに加えて、必須tool itemのstatus、期待artifactの存在、外部recordの照会結果を確認します。アプリケーションが表示する「完了」は、このbusiness-level verifierを通過した後に限ります。
stream切断後のrecoveryを実装する
Streamingは進捗表示に便利ですが、切断中に発生したeventは再接続後に自動replayされません。クライアントは最後に受信したeventだけから推測せず、sessionとsaved itemsを再取得して現在状態を再構築します。
推奨するrecovery sequenceは次の通りです。
- streamの切断を検出し、画面を「失敗」ではなく「同期中」にする。
- 同じinputをすぐ再送しない。元のturnが続いている可能性がある。
- sessionをretrieveし、active/idle/failedなどの状態を確認する。
- saved turns/itemsを取得し、最後に確定したtool、command、artifactを照合する。
- 外部副作用が不明ならERPやメール側をside-effect IDで照会する。
- 元のturnが終了しており未完了が特定できた場合だけ、resume inputを送る。
単純なHTTP retry middlewareに任せると、元turnと新turnが並行し、二重更新が起き得ます。特にwrite toolは「timeoutだから再実行」ではなく、「更新有無を照会し、未更新なら同じidempotency keyで実行」が原則です。
input-time connectionの最大5分挙動
Self-hosted environmentがofflineの状態でinputを送ると、APIはenvironment connectionを要求し、接続を最大5分待ちます。期限を超えるとsubmissionは失敗し、初回inputではsessionが非同期にfailedになる場合があります。待機中にクライアントが同じinputを再送してはいけません。遅れてexecutorが接続しても、timeout済みinputが自動replayされるわけではないためです。sessionとsaved itemsを確認し、元inputが実行されていないと確定してから、新しいturnとして再送します。
この「最大5分」は公式ドキュメントに記載された製品挙動であり、自社システムの復旧SLAではありません。社内SLAでは、何分でalertを上げるか、いつ手動経路へ切り替えるか、接続失敗を誰が担当するかを別に定めます。
| 状態 | 禁止する対応 | 正しい確認 |
|---|---|---|
| Streamだけ切断 | 即時に同一inputを再送 | sessionとsaved itemを取得 |
| Environment接続待ち | 5分以内に重複submit | connection eventとturn有無を確認 |
| 5分超過 | late connectionが自動再生すると想定 | 元input未実行を確認して新turn |
| Turn completed | 全tool成功としてclose | tool itemと外部正本を検証 |
| Toolの結果不明 | writeを盲目的にretry | side-effect IDで照会・補償 |
| Policy version変更 | 複数版の規程を混在させて継続 | Stop、checkpoint、承認済み版で再開 |
environment lifecycleをsession lifecycleと分ける
Sessionが存在しても、self-hosted computeが常時起動しているとは限りません。逆にexecutorが接続中でも実行中のturnがない場合があります。environment lifecycleでは、起動要求、connected、disconnected、pending、failedを監視し、session stateと組み合わせて判断します。
公式ドキュメントは、idle eventだけを安全なshutdown signalにしてはいけないと明記しています。connection requestが消え、待機inputがturnを始める前にidleが届く場合があるためです。停止前には新規input、実行中command、required action、接続要求を再確認し、grace periodを設けます。調整できない場合はcomputeを継続する方が安全です。
Mid-turn disconnectでは、toolが失敗してもturn全体が完了する場合があります。また、強制終了されたcommandは自動restartされず、disconnect自体がwebhook経由で必ず再接続を要求するわけでもありません。復旧手順には、executor health、command item、artifact、外部副作用を個別に点検する工程が必要です。
hosted environmentで確認する固有設定
OpenAI-hosted sandboxのnetwork accessは、enabled、disabled、restrictedから選べます。restrictedではallowed_domainsを定義します。PoCでenabledを選ぶ場合も、実際に必要だった宛先を記録し、本番前にallowlist化します。投入file、package、capability directory、成果物の回収とsession削除時の扱いも確認します。
self-hosted executorで確認する固有設定
Self-hostedではcodex exec-serverがenvironment内でshell、file、local MCPを実行し、Agents APIへoutbound接続します。API側から社内へ直接inbound接続する構成ではありません。ネットワークは環境登録用のAPI endpointとcommand/result用WebSocketへのoutboundを許可します。proxy timeoutやWebSocket維持設定が最大5分待ちより短いと、製品側が待てても手前で切断するため、経路全体を試験します。
application keyとexecutor keyを混同しない
Self-hosted構成には用途の異なる鍵があります。アプリケーション側のOPENAI_API_KEYはsession操作とmodel inferenceに必要な権限を持ちます。environment側のCODEX_API_KEYは、dashboardで作成した制限付きenvironment keyを渡し、environment接続だけに使います。アプリケーションキーをsandboxへ置いてはいけません。
Agentが生成したcodeはenvironment keyを読む可能性があります。しかしそのkeyはenvironment接続以外のAPI操作を許可しない設計です。source code、container image、logへ埋め込まず、漏えい時にrotate/revokeできるようにします。組織、project、userまたはservice accountの所有関係がsessionと一致することも接続条件です。
第三者資格情報は可能ならenvironment外のcredential brokerに置き、承認された宛先とoperationにだけ注入します。これは一般的な「least privilege」の説明ではなく、agent-generated codeがenvironment内のfileとcredentialへアクセスできるというAgents API sandbox固有の脅威に対する条項です。
subagentsの共有filesystemと同時実行を試験する
Agents APIではmulti_agent.enabledとmax_concurrent_subagentsをsession作成時に設定できます。公式ドキュメント上のdefaultはcoordinatorを除いて6です。defaultをそのまま本番値にせず、接続先APIのrate limit、executor CPU/memory、file競合、token予算から上限を決めます。
Coordinatorとsubagentsは同じenvironment filesystemを共有し、subagent作成ごとにsandboxが増えるわけではありません。したがって、同じfileへの同時write、同じgit working treeの変更、同名artifactの生成が衝突します。対策はsubagentごとのwork directory、read-only input、所有fileの宣言、merge担当の一本化、atomic renameです。
さらに、subagentsは設定済みMCP tools、そのcredential/allowed tools、web search設定、environmentのfile/commandを継承しますが、function toolsはサポートしません。既存設計がfunction toolを前提にしている場合、「子へ委譲すれば同じtoolが使える」と想定せず、coordinator経由に戻すかMCP化するかを決めます。
Event streamではagent.session.subagent.created、coordination item、interruptなどを観測できます。ただしcreateやwaitのitemがcompletedでも、subagent taskの完了を意味しません。root answerだけで合否を決めず、各child turnのoutcomeと成果物を確認します。
| 固有テスト | 故障注入 | 合格条件 |
|---|---|---|
| Concurrency | 上限を超える独立taskを投入 | 同時数が設定値以内、残りは待機 |
| Shared file | 2 childが同じfileを更新 | 競合検出、silent overwriteなし |
| Child failure | 1 childのcommandを失敗 | rootが未完了を明示、成功偽装なし |
| Tool inheritance | 子に許可外toolを要求 | 実行不可、eventに記録 |
| Function tool | 子からfunction toolを要求 | 非対応を検出し設計済み代替へ |
| Interrupt | childを途中でinterrupt | outcomeとpartial artifactを追跡可能 |
AIエージェント 運用でtrace・observabilityのAPI制約を補う
Platform dashboardではsession、turn、model response、tool call、subagent activity、duration、status、token usageを確認できます。Tracingは新規sessionでdefault有効ですが、traceはturn終了後に構築され、agent answerより遅れて表示される場合があります。作業中の進捗はlive event、終了後の詳細はtraceと役割を分けます。
Public betaでは、trace retrievalとexternal trace exporterがAPIとして提供されていません。したがって「platform traceをSIEMへ自動exportする」ことを前提要件にすると実装不能です。代わりに、自社アプリケーションでsession/turn/item ID、business execution ID、environment event、tool resultの要約、artifact hash、外部record IDを保存します。機密情報はmaskし、platform dashboardへの閲覧権限と保存期間も決めます。
Token usageはrootとsubagentで別に記録され、親のusageに子のusageが含まれない表示があります。コスト集計ではrootだけを足して過小評価しないよう、全agent turnを集約します。traceがreadyになる前に請求・完了画面を閉じる場合も、後続集計jobで補完します。
cancel後も副作用を照会する
Active turnにはagent.session.input.cancelを送れます。Sessionと過去作業は残るため、cancel後にsaved itemsを取得できます。ただし、cancelは外部toolがすでに受け付けた操作のrollbackではありません。cancel eventの時刻とtool callを照合し、ERP、メール、storage側の結果を確認してから、resume、補償、closeを選びます。
AIエージェント 評価の既存RFPへ加えるAgents API固有条項
一般的な承認設計や評価計画は既存RFPを参照し、次の追加条項だけを明記します。
| 追加条項 | 回答させる内容 | 受入証拠 |
|---|---|---|
| Session mapping | business IDとsession/turn/itemの対応 | mapping台帳と再取得結果 |
| Stream recovery | event非replay前提の再同期 | 切断試験log |
| 5-minute connection | 待機、timeout、再送抑止、late接続 | offline executor試験 |
| Environment lifecycle | 起動、再接続、安全停止、永続file | lifecycle eventとrunbook |
| Executor boundary | outbound WebSocket、health、proxy | network diagramと疎通試験 |
| Key separation | application keyとenvironment key | 権限一覧とrevoke試験 |
| Multi-agent | concurrency、shared FS、tool継承 | 競合・child failure試験 |
| Trace limitation | live event、post-turn trace、API非対応範囲 | 代替telemetryの記録 |
| Beta change | version pin、change監視、回帰、rollback | version inventoryと試験結果 |
「対応可」という回答だけでは不十分です。どのevent、ID、API response、外部recordを証拠にするかを記述させます。public betaの仕様変更に備え、SDK、model、harness、container image、tool schemaをversion inventoryに残します。
90日PoCではAgents API固有の壊れ方を試す
PoCの対象は一つの業務系統、利用者一部門、接続先2〜3系統程度に限定し、一般的な業務評価と並行して次の固有テストを実施します。この数は管理しやすい設計例であり、製品上限や成果保証ではありません。
Day 1–30：構成と観測点
Environment typeを決め、session mapping、business ledger、side-effect IDを実装します。Hostedならnetwork policy、self-hostedならexecutorの起動・WebSocket・key分離を確認します。Live eventと自社telemetryの相関を作り、streamを閉じてもsessionとsaved itemsを読めることを確認します。
Day 31–60：接続断とmulti-agent故障注入
Stream切断、executor offline、input-time connection timeout、mid-turn disconnect、tool不明状態を意図的に起こします。待機中に同じinputを再送しないUI/queue制御、late connectionで古いinputがreplayされないこと、外部正本照会後にだけ再送することを確認します。Subagentはconcurrency上限、shared file競合、child failure、interrupt、function tool非対応を試します。
Day 61–90：回帰と運用引継ぎ
SDK/model/harness/tool schemaを固定して同じfailure suiteを再実行します。Traceの遅延、dashboard権限、外部export非対応時の代替telemetryを確認します。運用担当が、sessionは残るがenvironmentが落ちたケース、turnはcompletedだがtoolが失敗したケース、5分timeout後にexecutorだけ戻ったケースをrunbookだけで処理できれば、Agents API固有部分の受入準備が整います。
AIエージェント 業務をタイ拠点で運用する実装差分
タイ拠点のself-hosted executorが工場network内にある場合、Bangkok側のproxy、DNS、WebSocket idle timeout、夜間のcompute停止policyを確認します。APIが最大5分待つ設計でも、社内proxyがそれより早く切れば接続は成立しません。Japan HQからのapproval待ちとenvironment停止が重なる場合も、idle eventだけでshutdownせず、未処理inputと承認状態を確認します。
多言語内容の品質評価は既存記事の範囲ですが、Agents API固有のID、event名、tool名、error codeは翻訳しない原文をlogへ残します。日本語・タイ語の運用画面には説明を付けても、検索キーとなるsession_id、turn_id、environment_connectionなどは同じ値で相関できるようにします。タイ時間とUTCの両方を記録し、最大5分待ちやtimeoutの時刻判定を曖昧にしません。
Agents API運用で起きやすい誤読
durable sessionなら自動復旧する
Sessionが保存されても、event replay、外部副作用の照合、killed commandのrestartは自動ではありません。Saved itemsと外部正本から再開点を決めます。
idleならself-hosted computeを止めてよい
Idle event単独は安全停止の根拠になりません。Connection requestや待機inputと競合しないことを再確認します。
subagentごとにsandboxが分離される
Coordinatorとsubagentsは同じenvironment filesystemを共有します。File所有権とmerge規則が必要です。
completed turnならtoolも成功した
完了したturnでもtoolが失敗している可能性があります。Tool item、artifact、外部recordを検証します。
traceはすぐAPIで取得・exportできる
Traceはturn後に構築され、public betaではtrace retrieval/external exporterがAPI提供されません。Live eventと自社telemetryで補います。
まとめ：Agents API固有の状態遷移を受け入れられるか
AIエージェント API 導入にAgents APIを使う際の追加設計は明確です。Session・turn・itemを業務IDへ対応させ、stream切断ではevent replayを期待せずsaved itemsから再同期します。Self-hosted executorのinput-time connectionは最大5分待ち、timeout後のlate connectionは古いinputを再生しないため、待機中の重複送信を止めなければなりません。Environment lifecycleはsessionと別に監視し、idleだけで停止しません。
Application keyとenvironment keyを分離し、subagentsが共有filesystemを使う前提でconcurrencyとfile競合を試験します。Traceは有用ですが、turn後に作られ、API取得・外部exportにpublic betaの制約があります。したがって、自社telemetryとbusiness ledgerが不可欠です。既存のAIエージェントRFPへこの固有条項を追加し、2〜3の接続先で故障注入を行えば、一般論と重複せずにAgents APIの運用可否を判断できます。
Agents APIのhosted/self-hosted選定、executor接続、session recovery、subagent競合、5分timeoutを含む試験仕様の整理段階でもご相談いただけます。既存のAIエージェントRFPへ固有条項を追加したい場合は、TOMAS TECHへのお問い合わせをご利用ください。
Agents API運用設計のFAQ
Streamが切れたら同じinputを再送してよいですか？
すぐには再送しません。元turnが継続している可能性があり、stream eventはreplayされないため、sessionとsaved itemsを取得して状態を再構築します。外部writeが不明なら対象systemを照会し、未実行が確定してから新turnを送ります。
Self-hosted environmentの5分待ちはSLAですか？
いいえ。Input-time connectionをAPIが最大5分待つという製品挙動です。超過するとsubmissionが失敗し、late connectionもtimeout済みinputを自動replayしません。社内のalert、復旧、手動切替SLAは別に定義します。
Subagentごとにfileは分離されますか？
分離されません。Coordinatorとsubagentsは同一environmentのfilesystemを共有します。Subagent別directory、所有file、atomic write、merge担当を設計します。
Platform traceだけで監査できますか？
Traceは詳細確認に有用ですが、turn後に構築され、public betaではAPIによるtrace retrievalとexternal exporterが提供されません。業務ID、tool result要約、artifact hash、外部record IDを自社側にも保存します。
既存RFPへ何を追加すればよいですか？
Session mapping、event非replayのrecovery、最大5分connection、environment lifecycle、executor/key境界、shared filesystem/concurrency、trace制約、beta version管理の8領域を追加します。一般的な承認・KPI・データ統制は既存RFPを再利用します。
参考情報
- OpenAI, Introducing the Agents API, 2026-09-10: https://openai.com/index/introducing-the-agents-api/
- OpenAI Developers, Agents API overview: https://developers.openai.com/api/docs/guides/agents-api/overview
- OpenAI Developers, Architecture: https://developers.openai.com/api/docs/guides/agents-api/architecture
- OpenAI Developers, Run and continue sessions: https://developers.openai.com/api/docs/guides/agents-api/sessions
- OpenAI Developers, OpenAI-hosted sandboxes: https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted
- OpenAI Developers, Self-hosted sandboxes: https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted
- OpenAI Developers, Sandbox lifecycle: https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle
- OpenAI Developers, Sandbox security: https://developers.openai.com/api/docs/guides/agents-api/environments/security
- OpenAI Developers, Multi-agent: https://developers.openai.com/api/docs/guides/agents-api/multi-agent
- OpenAI Developers, Observability and usage: https://developers.openai.com/api/docs/guides/agents-api/observability
- OpenAI Developers, Tracing: https://developers.openai.com/api/docs/guides/agents-api/tracing
（一次情報の確認日：2026年9月16日）
