If an AI agent API implementation uses OpenAI’s Agents API, an existing agent RFP does not need to be rewritten from zero. Keep the general requirements for business completion, approvals, data classification, and KPIs. Add the operational deltas that are specific to Agents API: session and turn persistence, stream recovery, the maximum five-minute input-time connection wait, environment lifecycle, hosted versus self-hosted executors, key separation, the filesystem shared by subagents, concurrency, and the limits of trace access.
OpenAI announced the Agents API in public beta on September 10, 2026. It provides the Codex harness for long-running sessions, context management, tools, subagents, and hosted or self-hosted environments. This manages much of the agent loop, but it does not guarantee exactly-once business execution or automatic recovery. Official documentation states that a completed turn does not prove that every tool succeeded, missed stream events are not replayed, and a self-hosted customer owns reconnection, shutdown, and persistent files.
For broad implementation decisions, see AI Agent Implementation in 2026. For approvals and business governance, see AI Agent Workflow Governance. For analytical use cases, see Data Agents for Manufacturing. This article covers only the Agents API clauses that should be added to those existing designs.
Agents API components in an AI agent platform
Treat the application, OpenAI-managed harness, session, environment, executor, and tool connections as separate components. With environment.type: none, the harness can call remote MCP and function tools, but built-in shell, workspace files, and executor MCPs are unavailable. With openai_hosted, OpenAI provisions the sandbox and the harness runs commands in it. With self_hosted, the customer provisions compute and runs codex exec-server, which connects outbound to the Agents API over WebSocket.
| Component | Platform capability | Implementation responsibility |
|---|---|---|
| Session | Persist sessions, turns, and items | Map business IDs and define retention |
| Stream | Deliver live events | Detect disconnects and rebuild from saved items |
| Hosted environment | Provision sandbox and execute commands | Network policy, input files, artifact retrieval |
| Self-hosted environment | Harness-to-executor protocol | Compute, startup, reconnect, shutdown, persistence |
| Subagents | Delegation, events, concurrency setting | Work partition, shared-file control, cost ceiling |
| Trace | Dashboard views of turns, tools, subagents | Business correlation and alternative telemetry |
A request/response monitor can miss states such as a durable session with a disconnected executor, a completed turn with a failed tool, or a client that disconnected while work continued.
Separate session, turn, item, and business IDs
A session contains conversation and work across multiple turns. A turn is one work cycle for an input. Items record model responses, tool calls, commands, and subagent coordination. Session durability is not a database transaction.
Maintain separate session_id, turn_id, business_execution_id, and side_effect_id. One business request can span several turns; the same business request can also resume in a new session. Keep the mapping in an enterprise ledger. Pass side-effect IDs as idempotency keys or reconcile the target system before retrying a write.
Context compaction supports long work, but compressed conversation should not be the business record. Store structured checkpoints containing input and policy versions, completed and pending steps, artifact hashes, external record IDs, approval status, and the safe resume point.
OpenAI’s hosted-environment guide also warns that a completed turn does not guarantee every tool succeeded. A business completion verifier must inspect required tool items, expected artifacts, and external records before the application displays “completed.”
Recover after a stream disconnect
Streaming is useful for progress, but events missed during a disconnect are not replayed automatically. Do not immediately resend the same input; the original turn may still be active.
Use this recovery sequence:
- Mark the client as synchronizing, not failed.
- Retrieve the session and current state.
- List saved turns and items to find the last confirmed tool, command, and artifact.
- Reconcile uncertain writes with the external system using the side-effect ID.
- Send a new resume input only after the original turn has ended and the incomplete step is known.
Maximum five-minute input-time connection behavior
If input is submitted while a self-hosted environment is offline, the API can request an environment connection and wait up to five minutes. If that window expires, the submission fails; an initial input can leave the session asynchronously failed. Do not resend the same input while the connection wait is active. A late executor connection does not replay the timed-out input. Retrieve the session and saved items, confirm that the original input did not execute, and only then submit a new turn.
The maximum five minutes is documented product behavior, not the customer system’s SLA. Define separate alert, escalation, manual-fallback, and recovery targets.
| State | Unsafe response | Required check |
|---|---|---|
| Stream disconnected | Immediately resend input | Retrieve session and saved items |
| Environment waiting | Duplicate submission before five minutes | Observe connection events and turn creation |
| Five-minute timeout | Assume late connection replays work | Confirm non-execution, then create new turn |
| Turn completed | Close as full success | Verify tool items and external records |
| Tool result unknown | Blindly retry a write | Reconcile by side-effect ID |
| Policy version changed | Continue under mixed rules | Stop, checkpoint, and start with the approved version |
Operate environment lifecycle separately from session lifecycle
A session can exist while self-hosted compute is offline. An executor can also be connected while no turn is active. Observe connected, disconnected, pending, and failed environment events together with session state.
OpenAI warns that an idle event alone is not a safe shutdown signal. Idle can occur after a connection request clears but before waiting input begins a turn. Before shutdown, recheck incoming work, active commands, required actions, and connection requests, and use a grace period. If shutdown cannot be coordinated, keep compute available.
A mid-turn disconnect can fail a tool even if the overall turn completes. A killed command is not automatically restarted, and a disconnect does not necessarily trigger reconnection through a webhook. Recovery must inspect executor health, command items, artifacts, and external side effects individually.
For OpenAI-hosted sandboxes, network access can be enabled, disabled, or restricted to allowed_domains. Record actual destinations during the PoC and move toward an allowlist. For self-hosting, test the complete outbound route for environment registration and WebSocket commands/results. A corporate proxy timeout shorter than the five-minute platform wait will terminate the path earlier.
Separate application and executor keys
The application OPENAI_API_KEY needs permissions for session operations and model inference. The self-hosted environment receives a separate restricted environment key as CODEX_API_KEY. Keep the application key outside the sandbox.
Agent-generated code may read the environment key, but that key is designed only to connect environments. Do not place it in source code, container images, or logs, and test rotation and revocation. The organization, project, and owner must match the session context.
Where possible, keep third-party credentials outside the environment in a credential broker that injects scoped secrets only into approved outbound requests. This addresses a specific Agents API threat: agent-generated code can access files, credentials, and network capabilities exposed inside its environment.
Test the shared filesystem and subagent concurrency
Agents API configures delegation with multi_agent.enabled and max_concurrent_subagents. The documented default is six concurrent subagents, excluding the coordinator. Treat that as a product default, not a production recommendation. Set a limit from downstream rate limits, executor CPU and memory, file contention, and token budgets.
The coordinator and subagents share one environment filesystem. Creating a subagent does not create a new sandbox. Use per-agent work directories, read-only inputs, declared file ownership, atomic writes, and a single merge owner.
Subagents inherit configured MCP tools, credentials and allowed-tool settings, web search, and environment files and commands. They do not support function tools. If an existing workflow expects a child to call a function tool, route it through the coordinator or redesign it as MCP rather than assuming identical capability.
The event stream exposes subagent creation, coordination, wait, and interrupt actions. A completed create or wait item does not mean the child task completed. Inspect child turn outcomes and artifacts.
| Specific test | Fault injection | Acceptance evidence |
|---|---|---|
| Concurrency | Submit more independent tasks than the limit | Running children stay within the limit |
| Shared file | Two children update the same file | Conflict detected; no silent overwrite |
| Child failure | Fail one child command | Root reports incomplete work |
| Tool inheritance | Ask child to use a prohibited tool | Execution blocked and recorded |
| Function tool | Request function tool from child | Unsupported path detected; planned fallback used |
| Interrupt | Interrupt a child mid-task | Outcome and partial artifacts remain attributable |
Trace and observability limits in AI agent operations
The Platform dashboard shows sessions, turns, model responses, tool calls, subagent activity, duration, status, and token usage. Tracing is enabled by default for new sessions, but traces are built after a turn ends and may appear after the agent answer. Use live events for in-progress status and traces for post-turn analysis.
During public beta, trace retrieval and external trace exporters are not exposed through the API. Do not promise automatic SIEM export of platform traces. Store session, turn and item IDs, business execution ID, environment events, summarized tool results, artifact hashes, and external record IDs in application telemetry, with appropriate redaction.
Token usage can be recorded separately for root and subagent turns; a parent’s usage does not necessarily include its children. Aggregate every agent turn to avoid understating cost, and run a follow-up collection job if trace or usage data is not ready when the answer arrives.
Cancelling an active turn preserves the session and prior work, but it does not roll back an external tool action already accepted. After cancel, retrieve saved items, reconcile the target system, and choose resume, compensation, or close.
Add Agents API clauses to an AI agent evaluation RFP
Reuse the existing RFP for general approval, data governance, and business evaluation. Add only these product-specific clauses.
| Addendum | Required answer | Acceptance evidence |
|---|---|---|
| Session mapping | Business ID to session/turn/item mapping | Ledger and retrieval result |
| Stream recovery | Resynchronization without event replay | Disconnect test log |
| Five-minute connection | Wait, timeout, resend suppression, late connection | Offline executor test |
| Environment lifecycle | Startup, reconnect, safe shutdown, persistence | Lifecycle events and runbook |
| Executor boundary | Outbound WebSocket, health, proxy behavior | Network diagram and test |
| Key separation | Application key versus environment key | Permission list and revoke test |
| Multi-agent | Concurrency, shared filesystem, inherited tools | Conflict and child-failure tests |
| Trace limitation | Live events, post-turn trace, unavailable APIs | Alternative telemetry records |
| Beta change | Version pinning, monitoring, regression, rollback | Version inventory and test result |
Require evidence IDs and events, not a generic “supported” answer. Maintain an inventory of SDK, model, harness, container image, and tool schema versions.
Use the 90-day PoC for Agents API failure modes
Keep the PoC to one workflow, one user group, and approximately two to three connected systems. This is a manageable design example, not a product limit or outcome guarantee.
In days 1–30, choose the environment type, implement session mapping and the business ledger, verify hosted network policy or self-hosted executor/key separation, and prove that sessions and saved items remain retrievable after the client stream closes.
In days 31–60, inject stream disconnects, offline executors, the input-time connection timeout, mid-turn disconnects, and unknown tool outcomes. Verify that the client does not duplicate input during the wait, a late connection does not replay timed-out input, and a new turn is sent only after reconciliation. Test subagent concurrency, shared-file conflicts, child failure, interrupt, and function-tool limitations.
In days 61–90, freeze SDK, model, harness, and tool-schema versions and rerun the failure suite. Verify trace delay, dashboard access, alternative telemetry, and operator runbooks for three critical cases: a durable session with a dead environment; a completed turn with a failed tool; and an executor that reconnects only after the five-minute timeout.
Thailand deployment checks for business AI agents
For a self-hosted executor inside a Thai factory network, test the Bangkok proxy, DNS, WebSocket idle timeout, and overnight compute policy. The API may wait five minutes, but a shorter corporate proxy timeout can break the path first. When approval from Japan headquarters overlaps with local shutdown, do not stop on idle alone; recheck pending input and approval state.
Keep identifiers, event names, tool names, and error codes in their original form in logs even when operator screens are localized. Correlate the same session_id, turn_id, and environment_connection across Japanese, Thai, and English interfaces. Record both ICT and UTC so the five-minute wait and timeout sequence are unambiguous.
Common Agents API misreadings
A durable session means automatic recovery. It does not provide event replay, external reconciliation, or automatic restart of killed commands.
Idle means self-hosted compute can stop. Idle alone is not a safe shutdown signal.
Every subagent receives a separate sandbox. Coordinator and children share the filesystem.
Completed turn means every tool succeeded. Inspect tool items, artifacts, and external records.
Trace is immediately retrievable and exportable by API. Traces are post-turn, and public beta does not expose trace retrieval or external exporters.
Conclusion: accept the state transitions unique to Agents API
The product-specific work in an AI agent API implementation is well defined. Map sessions, turns, and items to business IDs. Recover a disconnected stream from saved items rather than assuming event replay. A self-hosted input-time connection waits up to five minutes; after timeout, a late connection does not replay the old input, so duplicate submission must be suppressed. Monitor environment lifecycle separately from session state and never shut down on idle alone.
Separate application and environment keys. Test subagents under a shared filesystem and explicit concurrency ceiling. Treat traces as valuable post-turn evidence while compensating for public-beta API and exporter limits with application telemetry. Adding these clauses to an existing agent RFP and fault-testing two to three connected systems evaluates Agents API without repeating a generic governance article.
TOMAS TECH can help add these clauses to an existing RFP and design tests for hosted/self-hosted environments, executor connectivity, session recovery, subagent contention, and the five-minute timeout. Contact TOMAS TECH to review the operating design before broad system access is granted.
FAQ: Agents API operations design
Should the client resend input when a stream disconnects?
Not immediately. Retrieve the session and saved items first because the original turn may still be running and missed events are not replayed. Reconcile uncertain writes before creating a new turn.
Is the five-minute self-hosted wait an SLA?
No. It is documented product behavior. Submission fails after the input-time connection window, and a late connection does not replay timed-out input. Define separate internal alert and recovery SLAs.
Does each subagent get isolated files?
No. Coordinator and subagents share the environment filesystem. Use separate work directories, ownership rules, atomic writes, and controlled merge.
Is the Platform trace sufficient for audit?
It is useful but post-turn, and public beta does not expose trace retrieval or external exporters through the API. Persist business correlation and essential evidence in application telemetry.
What belongs in the RFP addendum?
Session mapping, non-replayed stream recovery, five-minute connection behavior, environment lifecycle, executor/key boundaries, shared filesystem/concurrency, trace limits, and beta-version management.
References
- OpenAI, Introducing the Agents API, September 10, 2026: 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
(All primary sources accessed September 16, 2026.)
