The Agents API appears in the OpenAI SDK (beta): /agents CRUD, environments, sessions, and vaults

At 2026-09-10 19:37 UTC, openai-python v3.13.0 and openai-node v7.15.0 were published in the same minute, each with one line under Features — "add Agents API". Fifteen days after the Assistants API shut down (2026-08-26), a complete agent interface surface appeared in the SDK type layer: CRUD for reusable Agents, managed sessions bound to execution environments, subagents, and credential vaults — four resource layers at once.

We keep the same discipline as our previous SDK-intel pieces: only state what can be pointed to, verbatim, in the SDK source. Every citation comes from same-day (2026-09-11) re-fetches of GitHub release notes and the v3.13.0 / v7.15.0 tag sources; the official OpenAI docs domain returned 403 to us that day, so announcement-side status is date-anchored throughout.

1. Overview: four resource surfaces and one boundary

The Agents API is an agent interface surface that appeared in the official OpenAI SDK type layer on 2026-09-10 (beta namespace):

The boundary, stated up front: beta namespace, no availability announcement, no pricing, no GA plan (as of 2026-09-11, the docs domain returns 403 to us). SDK types are auto-generated — they prove the spec contains it, not that the service is open to you.

2. First-appearance check and one counterintuitive detail

Tag-tree comparison on 2026-09-11:

• The openai-python v3.11.0 tree contains zero resources/beta/agents paths and no agent type files under types/beta/; v3.13.0 adds 188 agent-related paths at once (counted by comparing the two tags on 2026-09-11; the 3 pre-existing agent-string paths in v3.11.0 — AGENTS.md and two responses examples — are not counted)
• The openai-node v7.13.0 tree has no src/resources/beta/agents; it appears in v7.15.0

One detail deserves its own paragraph: the SDK namespace and the HTTP path prefix disagree. The resource class is mounted at client.beta.agents (beta namespace, same pattern as historical beta resources), but the methods build top-level paths — /agents, /agents/sessions, /vaults — with no /beta/ segment. When writing gateway routes, verifying traffic, or hand-rolling HTTP calls, trust the actual paths. The SDK does not explain the mismatch, and neither do we.

3. The Agent object: reusable, CRUD-complete, subagent-capable

The Agent type (types/beta/agent.py) is annotated: "A reusable agent scoped to the caller's project." The CRUD surface is complete: POST /agents (create), GET /agents (list), GET /agents/{agent_id} (retrieve), POST /agents/{agent_id} (update), DELETE /agents/{agent_id} (delete → AgentDeleted).

Field-by-field (v3.13.0 tag source):

A minimal create call (source-verified against AgentCreateParams; not executed against a live key):

from openai import OpenAI

client = OpenAI()

agent = client.beta.agents.create(
    model="gpt-5.6-terra",           # required, free-form string
    name="docs-triage-agent",        # optional
    instructions="Group by severity first",  # optional, appended to base instructions
    service_tier="flex",             # optional: auto/default/flex/priority/fast
)
print(agent.id, agent.object)        # ...  "agent"

Two semantics worth underlining:

• instructions append rather than override — the SDK reads "Custom instructions appended to the agent's default base instructions." This carries over the Assistants-era mental model for instructions, but what the base instructions contain — and whether they can be disabled — is not visible in the type layer.
• service_tier includes fast — the same word as the Fast mode in our world notes (long-context support since 2026-08-05). At the enum level this is a selectable service tier for the agent's model requests; whether it is the same mechanism has no linking comment in the SDK, so we do not infer.

4. Managed Agents sessions: status machine, environment, required actions

POST /agents/sessions creates a session. The AgentSession class docstring: "A Managed Agents session" — and "managed" shows up in the fields:

• Status machine: status with four values — idle / in_progress / requires_action / failed (plus an error field carrying the failure reason)
• required_actions: "Actions that must be completed before the session can continue" — the session parks when it needs external input (a tool approval, for example)
• environment: "The execution environment for the session" — every session binds one
• usage: Optional[TokenUsage] — token accounting lives on the session object
• Agent snapshot: the Agent embedded in a session carries the name from session creation; the SDK notes "Later changes to the agent's name do not affect this value"

The session's subresource endpoints (all under /agents/sessions/{session_id}): items, events, artifacts (including GET .../artifacts/{id}/content for content download), subagents, and subagents/{subagent_id}/turns.

The item types expose the agent's behavioral surface directly: agent_function_call_item (function calls), agent_command_execution_item (command execution), agent_mcp_call_item (MCP calls), and agent_create_subagent_call_item / close / interrupt (creating, closing, and interrupting subagents). In other words: within one Agent session's execution trace, function calls, shell commands, MCP tools, and subagent calls are all first-class citizens.

5. Environments: first-class execution environments with templates and files

The environment-info type (EnvironmentInfo) carries a docstring worth quoting in full: "Safe metadata for a first-class execution environment." Fields: id, files (installed in the environment, without their contents), plugins (without their archive contents), skills (without their contents), and object fixed to agent.environment.

Companion management endpoints:

• POST/GET /agents/environments/templates and .../templates/{environment_template_id} — create and list environment templates
• /agents/environments/{environment_id} and .../files — environment instances and their file management

Skills and plugins appearing inside an OpenAI API execution environment suggests the agent ecosystem (tools and skills we have previously covered in MCP and Custom GPT contexts) may be converging toward "preinstalled in the environment" — but that is a shape signal from the field structure; there is no official capability statement, and we do not extrapolate.

6. Vaults: getting credentials out of the code

/vaults, /vaults/{vault_id}, /vaults/{vault_id}/credentials, and .../credentials/{credential_id} form the credential-vault resource family. That is everything the type layer confirms: a vault is the container, a credential is the content. The concrete credential shapes (API keys? OAuth tokens?) did not appear in this extraction's type inventory, and we will not guess. The direction itself is notable — when an agent calls external tools on your behalf, credentials live in a vault and are authorized per session rather than baked into code or prompts. That is the correct shape for an agent security model.

7. Timeline juxtaposition: fifteen days after the Assistants shutdown

Facts only, no causal conclusion:

• 2026-08-26: the Assistants API shut down (official changelog: "The Assistants API shut down on August 26, 2026"), with the official migration path at the time being the Responses API / Conversations API (see our OpenAI Ecosystem Week 42 Flash: Assistants API Shut Down, Sol Price Cut, Transcription Deprecations)
• 2026-09-10: the Agents API appeared in both SDKs' type layers as a beta. Its surfaces (reusable Agent + managed session + execution environment + vaults) are conceptually comparable to Assistants' Assistant / Thread / Run triad, but the fields and semantics do not map one-to-one

Whether the two are related has no official statement as of 2026-09-11. For teams that just finished an Assistants migration, the right move is not to turn around and migrate again: keep the Responses / Conversations work, treat the Agents API as a watch item, and wait for official announcements.

8. Common mistakes and troubleshooting

• Treating a beta surface as GA: client.beta.agents lives in the beta namespace; endpoints existing does not mean the service is open. As of 2026-09-11 the docs domain returns 403 to us and open status cannot be verified.
• Guessing HTTP paths from the SDK namespace: the namespace carries beta, the paths do not. When hand-writing HTTP or configuring gateways, read the path construction from source rather than deriving it from the namespace.
• Assuming instructions replace everything: they append (appended to the agent's default base instructions). The base instructions are not visible in the type layer; do not write prompts assuming a blank slate.
• Exhaustive status switches without a default: the four-value status machine is the current extraction; beta enums can grow at any time — leave a fallback branch.
• Migrating from a finished Assistants migration: the official migration guidance remains Responses / Conversations (08-26 announcement); the Agents API has no GA information. Watch and experiment behind a feature flag; do not switch horses in production.

9. Next steps

• The Live API lands in the OpenAI SDK: gpt-live-1, dual WebRTC/WebSocket channels, and SIP call control: the other brand-new API surface, landed at 17:28 UTC the same day.
• openai-python 3.9/3.10 and openai-node 7.11/7.12: Prompt Cache Diagnostics, API Key Expiry, GPT Image 2.5: the six SDK releases from the previous two days; the version table now covers v3.12.0-v3.13.0 / v7.14.0-v7.15.0.
• Responses API vs Chat Completions: Is It Time to Migrate?: landing the official post-Assistants migration path.
• OpenAI Ecosystem Week 42 Flash: Assistants API Shut Down, Sol Price Cut, Transcription Deprecations: the official announcements from the shutdown week.
• gpt-6-astra appears in the OpenAI SDK: the new ChatModel ID and the Safety Alerts API: the methodology behind this series of SDK type-layer briefings.
• OpenAI Models Release Notes (2026, Living Document): the timeline view — an official Agents API announcement, if it happens, will be tracked there.