Read the resource relationships
These connections describe ownership and use, not a single linear request. One reusable agent configuration can serve multiple independent sessions; each session can perform multiple turns.
Track outcomes independently
This is an application interpretation of signals, not a replacement for the API's state schema. Waiting for a dependency, completing a turn, and closing a browser connection are different facts.
| Signal | Meaning for your application |
|---|---|
| New input while idle | Starts another turn in the session |
| New input while active | Can steer the active turn |
| requires_action | Inspect and satisfy the current dependency |
| idle | Not proof of successful task completion |
| Root turn completed | Check output and tool outcomes |
| Root failed or cancelled | Show failure/cancellation; preserve diagnostic IDs |
| Stream closed | Transport ended; inspect state if no terminal event arrived |
Do not equate IDs with authorization
Store your authenticated user's ownership mapping separately from the session ID. A tool call belongs to a turn and call identifier; a business operation needs its own stable identity for idempotency. Do not let an untrusted request choose an arbitrary session, tool result, or approval record.
Keep compute lifetime separate
Self-hosted compute may disconnect while its session still exists. A replacement machine does not recover files merely by reusing an environment ID. Persist files through the provider and coordinate reconnection. Delete the session and release self-hosted compute separately after preserving needed output.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: sessions Environment lifecycle Events and items