Short answer
“ChatGPT agents API” can mean a few different things. For a developer building an agent in an application, OpenAI documents the Agents API, a beta managed service built around a Codex agent harness. If you want to define and run the workflow in your own code, use the Agents SDK or the Responses API directly. If your organization has a saved ChatGPT Workspace Agent and wants another system to start it, that is a separate API-trigger feature. These are related options, not interchangeable names for one API. (Agents API overview)
OpenAI’s Help Center says ChatGPT agent is no longer available and points readers to ChatGPT Work for longer, multi-step tasks. That product experience is distinct from the developer-facing Agents API and Workspace Agents API trigger. (ChatGPT agent Help Center)
Choose the right integration
| If you need… | Start with… | What it does |
|---|---|---|
| OpenAI-managed, multi-step agent sessions with session continuation and a managed or self-hosted execution environment | Agents API (beta) | OpenAI manages the Codex harness, sessions, orchestration, context compaction, and recovery. Your application supplies the task, tools, and configuration. (Overview) |
| An agent workflow defined and run in your application code | Agents SDK | The SDK provides a runtime for agent turns, tools, guardrails, handoffs, and sessions. It uses the Responses API by default for OpenAI models. (SDK guide) |
| Your backend to start a previously created Workspace Agent workflow | Workspace Agents API trigger | The API starts an asynchronous run of the saved workflow; the trigger request does not return the completed agent response. Workspace availability and permissions apply. (OpenAI Cookbook) |
| Direct control over a model interaction, including your own tool loop and state handling | Responses API directly | Use this when you prefer to implement orchestration yourself rather than use the SDK runtime. (SDK guide) |
Practical rule: choose the Agents API if you want OpenAI to manage the agent harness; choose the Agents SDK if you want its orchestration runtime in your application; use the Responses API directly when you want to manage orchestration yourself. Choose the Workspace Agents trigger only when the workflow already exists as a saved workspace agent. The paths differ in who runs the workflow and how it is configured—not just in code style. (Agents API overview, SDK guide)
Run a minimal agent with the Python SDK
This is SDK code, not a raw HTTP request to a “ChatGPT agent” endpoint. It creates a text agent, runs one prompt, and prints the returned final output.
Prerequisites: Python 3.10 or newer, the openai-agents package, and an OpenAI API key in OPENAI_API_KEY. The SDK repository shows pip install openai-agents or uv add openai-agents; set the key before running the example. (Agents SDK repository, SDK quickstart)
pip install openai-agents
export OPENAI_API_KEY="your-api-key"
Save the following as agent_example.py:
import asyncio
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant.",
)
async def main():
result = await Runner.run(agent, "Explain what an API agent is in one sentence.")
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())
Run it from the same environment where the package and key are available:
python agent_example.py
Expected outcome: the program prints the agent’s final text answer. This example does not specify a model or expose a raw endpoint, request body, or HTTP authorization header; consult the SDK’s current model and API documentation if you need to configure those explicitly. (SDK quickstart)
For the Agents API, use its own quickstart rather than adapting the SDK snippet as though it were a REST call. The API is in beta. Its documented key permissions include api.agents.read and api.agents.write for session operations, plus api.responses.write for model requests. Raw requests require OpenAI-Beta: agents=v1; OpenAI SDKs add that header automatically. Keep the application API key outside the agent’s sandbox. (Agents API FAQ, Agents API quickstart)
How the Workspace Agents trigger differs
A Workspace Agent trigger starts an agent your organization has already created and configured in ChatGPT. The saved agent’s instructions, connected apps, permissions, and approval settings determine what it does after the trigger. The API call queues the run asynchronously; do not expect the completed response in the trigger request. The documented prerequisites include an eligible workspace, a saved agent, an API channel and trigger ID, and a Workspace Agent access token with the required scope. (OpenAI Cookbook)
This is not the same as using the Agents API to define a Codex-harness agent for your application, or using the Agents SDK to define an agent in Python. Check current workspace availability and permissions before designing around this option. (Agents API overview, Workspace Agents Help Center)
Production checks before launch
A successful introductory run does not establish that an agent is production-ready. Apply checks for the integration path you actually chose; managed Agents API behavior should not be assumed to apply to the SDK.
If you use the Agents API
- Limit credentials and permissions. Grant the documented scopes needed for the integration and keep the application API key outside the agent’s sandbox. Configure tool and environment access deliberately. (Agents API FAQ, Agents API quickstart)
- Recover carefully after a stream disconnect. Retrieve the existing session and its saved items before submitting more work. A completed turn does not guarantee every tool succeeded, and an idle session alone does not establish success; review the reported result. (Agents API FAQ)
- Plan for session data and artifacts. The Agents API retains session state so work can continue across turns. Save files you need before deleting a session. Published artifacts can be deleted separately; deleting an artifact does not delete its live environment file or original Files API object. (Agents API FAQ, Delete an agent session artifact)
- Review logs and costs. The FAQ points to Platform logs for inspecting turns, tool calls, and subagent activity. Model requests use the selected model’s API rates; OpenAI tools and OpenAI-hosted sandboxes have applicable separate rates. Check current pricing for your configuration. (Agents API FAQ)
- Confirm data-residency needs. The FAQ says the Agents API currently supports data residency in the United States only. Verify suitability if your application has other residency requirements. (Agents API FAQ)
If you use the Agents SDK
- Handle run outcomes and exceptions. The runner can raise
MaxTurnsExceededif the configured turn limit is exceeded, or guardrail tripwire exceptions when a guardrail blocks a run. Handle these cases in your application rather than treating every returned or interrupted run as successful. (Running agents) - Review tracing and sensitive data. SDK tracing is enabled by default and can include model generations and tool-call activity. If traces should not capture potentially sensitive inputs or outputs, set
RunConfig.trace_include_sensitive_datatoFalse, or disable tracing where appropriate. (SDK tracing guide) - Choose how subsequent turns carry history. For another turn, the SDK supports passing prior result history, using an SDK session to load and save history, or using server-managed continuation state where applicable. Choose and test the state approach that fits the application rather than assuming the one-turn example persists conversation history. (SDK results guide, Running agents)
Bottom line
There is no single integration called “the ChatGPT agents API” that covers every use case. For a developer-built agent, decide whether you want OpenAI’s managed Agents API, an in-code Agents SDK runtime, or the greater orchestration control of the Responses API. Use the Workspace Agents API trigger only to start a saved ChatGPT workspace workflow. Keep the paths distinct when choosing documentation, credentials, execution environment, and production checks. (Agents API overview)
Sources
Agents API (beta) FAQ — OpenAI Help Center
Agents API quickstart — OpenAI API
Quickstart — OpenAI Agents SDK
Running agents — OpenAI Agents SDK
Delete an agent session artifact — OpenAI API Reference
Trigger a Workspace Agent from the API — OpenAI Cookbook
ChatGPT agent — OpenAI Help Center
ChatGPT Workspace Agents for Enterprise and Business — OpenAI Help Center