Hosted agent environments surface in the OpenAI SDKs: prewarmed creation, idle suspension, expiration

OpenAI's two official SDKs shipped four releases in three days, and they tell a single story: a hosted agent environment resource you can create, suspend, and expire. This article quotes the GitHub release notes and SDK tag source fetched on October 12, 2026 verbatim, and asserts nothing beyond that layer.

1. Timeline: four releases in three days

Version numbers and dates come from the GitHub Releases API fetched the day this article was written. When the previous GPTMap article on the SDKs was fact-checked, python's latest was v3.26.1 and node's was v7.31.0 — this environment API line is what landed in the three days after.

2. Prewarmed creation: environments.create

The new resource lives under client.beta.agents.environments. The create docstring, verbatim:

Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta.

Two facts follow. First, environments are created before a session. Second, creation is gated behind the prewarming beta. The vault_ids parameter reads "The IDs of up to 10 vaults made available to an OpenAI-hosted environment", and the resource also exposes files and templates sub-resources.

The shape of the environment parameter, from environment_create_params.py at the v3.29.0 tag:

environment = {
    "type": "openai_hosted",           # required, the only literal today
    "desktop": {"enabled": True},       # optional
    "packages": {
        "npm": ["typescript@5"],
        "python": ["httpx"],
        "system": [],                   # three independent groups
    },
    "network": {
        "access": "restricted",         # enabled / disabled / restricted
        "allowed_domains": ["api.example.com"],
        "blocked_domains": [],
    },
    "env": {"FOO": "bar"},
    "setup_commands": [],               # list of SetupCommandParam
    "files": [],                        # HostedEnvironmentFileParam list
    "skills": [],                       # HostedSkillParam list
    "plugins": [],                      # HostedPluginParam list
    "capability_directories": [],
    "environment_template_id": "tmpl_...",
}

env = client.beta.agents.environments.create(
    environment=environment,
    vault_ids=["vault_..."],            # up to 10
)

This is a type-layer minimal example: every field and enum is transcribed from the source file, but no live call was made (beta-gated — your API response is the source of truth). One network caveat worth quoting: a non-empty allowed_domains list requires access: "restricted" and cannot be combined with certain settings (source comment: "A nonempty list requires access: restricted and cannot be combined with…" — the full constraint lives in the source).

3. Idle lifecycle: suspension and expiration

v3.28.0 (python) and v7.32.0 (node) added suspension and expiration the same day. The two new session event types, verbatim:

agent.session.environment.suspended
"Emitted after an idle hosted session environment is checkpointed and stopped."

agent.session.environment.expired
"Emitted after a suspended hosted session environment and its checkpoint expire."

In sequence: an idle environment is checkpointed and stopped (suspended); after a suspension window, the environment and its checkpoint expire. The webhook-side event reads "Sent when an agent environment is suspended and can resume from a snapshot" — suspended environments can resume from a snapshot. Event objects carry event_id, session_id, an optional turn_id, and the environment's current state.

4. What else arrived in v3.29.0

The October 11 release adds four more Feature lines:

• a billing_not_active session error code — a new member of the session error family, named for a billing-not-active scenario;
• shida joins the named Live voices — one more named voice in the Live speech family;
• vault updates and metadata filters — vault-side updates plus metadata filtering;
• aligned beta pagination limits and non-null parameters — pagination semantics pulled level across beta resources.

openai-node v7.32.0 carries one runners fix alongside the environment API: totalUsage preserves detailed token usage (#2900) — a worthwhile upgrade for projects that meter usage through runners.

5. Common errors and troubleshooting

• Permission-or-not-found errors calling environments.create: confirm the SDK version first (openai-python ≥ 3.27.0, openai-node ≥ 7.32.0), then beta access — the docstring says "Requires access to the prewarming beta". This article cannot tell whether your account is in the beta; your API response can.
• Receiving agent.session.environment.suspended is not a failure: per the event docs, it is the expected lifecycle action for an idle environment, and the webhook docs say it can resume from a snapshot.
• billing_not_active: the new session error code added in v3.29.0; the name points at account billing state rather than code. No further trigger conditions appear in the day's loadable sources, so this article stops here.
• How the environment attaches to a session: session events carry environment state, but the complete parameter surface for "how a session references an environment ID" is not fully present in the day's fetched type files — no guessing here; it goes on the next batch's checklist.

6. Next steps

• For the model-enum side of the same window, read The GPT-6 family grows: gpt-6-sol, gpt-6-luna, gpt-6.1-sol land in the official SDKs;
• the Agents-and-sessions backstory is in gpt-6-astra appears in the OpenAI SDK: the new ChatModel ID and the Safety Alerts API;
• the six reference links at the top of this article hold every quoted sentence verbatim.