{"slug": "agents-api-quickstart", "title": "Agents API quickstart", "summary": "OpenAI published an Agents API quickstart showing developers how to build a coding assistant that writes a Python script, runs it, and reports the output, with the agent, its conversation, and its sandbox managed by OpenAI. The guide requires an application API key with the api.agents.read, api.agents.write, and api.responses.write scopes and the OpenAI-Beta: agents=v1 header, and provides streaming examples in Python, JavaScript, Go, and Java (openai-java 4.69.2) using the beta.agents namespace with the gpt-6-astra model and an openai_hosted environment.", "body_md": "Build a coding assistant that writes `tree.py`, runs it, and shows a directory tree. OpenAI manages the agent, its conversation, and the sandbox where it works.\n\n## Prerequisites\n\nCreate an [application API key](https://platform.openai.com/api-keys) in your OpenAI Platform project. Grant `api.agents.read` and `api.agents.write` for session operations, plus `api.responses.write` for model inference, then export it:\n\n```\nexport OPENAI_API_KEY=\"your-api-key\"\n```\n\nKeep this key outside the agent’s sandbox. See [OpenAI-hosted sandboxes](https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted#configure-the-sandbox) for sandbox configuration and limits.\n\nRequests require the `OpenAI-Beta: agents=v1` header. The OpenAI SDKs add it\nautomatically; include it explicitly when using cURL.\n\n## 1. Run a task\n\nChoose a language, install the OpenAI SDK, and run the example. The SDK examples use the `beta.agents` namespace. The request creates a session, submits a task, and streams progress.\n\nInstall or update the Python SDK:\n\n```\npip install --upgrade openai\n```\n\nSave the example as `quickstart.py`:\n\n``` python\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14from openai import OpenAI\n\nwith OpenAI() as client:\n    with client.beta.agents.sessions.create(\n        agent={\n            \"model\": \"gpt-6-astra\",\n            \"instructions\": \"Write clean code, run it, and report the actual output.\",\n        },\n        environment={\"type\": \"openai_hosted\"},\n        input=\"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.\",\n        stream=True,\n    ) as events:\n        for event in events:\n            print(event.to_json(indent=None), flush=True)\n```\n\nRun it from your terminal:\n\n```\npython quickstart.py\n```\n\nInstall the JavaScript SDK:\n\n```\nnpm install openai\n```\n\nSave the example as `quickstart.mjs`:\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16\n17\n18\n19\n20import OpenAI from \"openai\";\n\nconst client = new OpenAI();\nconst events = await client.beta.agents.sessions.create({\n  agent: {\n    model: \"gpt-6-astra\",\n    instructions: \"Write clean code, run it, and report the actual output.\",\n  },\n  environment: { type: \"openai_hosted\" },\n  input:\n    \"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.\",\n  stream: true,\n});\ntry {\n  for await (const event of events) {\n    console.log(JSON.stringify(event));\n  }\n} finally {\n  events.controller.abort();\n}\n```\n\nRun it from your terminal:\n\n```\nnode quickstart.mjs\n```\n\nIn a new directory, create a Go module and install the SDK:\n\n```\ngo mod init agents-quickstart\ngo get github.com/openai/openai-go/v3@latest\n```\n\nSave the example as `main.go`:\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16\n17\n18\n19\n20\n21\n22\n23\n24\n25\n26\n27\n28\n29\n30import (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go/v3\"\n)\n\nctx := context.Background()\nclient := openai.NewClient()\nevents := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{\n\tAgent: openai.BetaAgentSessionNewParamsAgent{\n\t\tModel:        openai.String(\"gpt-6-astra\"),\n\t\tInstructions: openai.String(\"Write clean code, run it, and report the actual output.\"),\n\t},\n\tEnvironment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}},\n\tInput: openai.BetaAgentSessionNewParamsInputUnion{\n\t\tOfString: openai.String(\"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.\"),\n\t},\n})\ndefer events.Close()\nif events.Err() != nil {\n\tpanic(events.Err())\n}\nfor events.Next() {\n\tevent := events.Current()\n\tfmt.Println(event.RawJSON())\n}\nif err := events.Err(); err != nil {\n\tpanic(err)\n}\n```\n\nRun it from your terminal:\n\n```\ngo run .\n```\n\nAdd the OpenAI SDK to your Maven project’s `pom.xml`:\n\n```\n1\n2\n3\n4\n5<dependency>\n  <groupId>com.openai</groupId>\n  <artifactId>openai-java</artifactId>\n  <version>4.69.2</version>\n</dependency>\n```\n\nSave the example as `src/main/java/AgentsApiSessionsStreamConversationExample.java`:\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16\n17\n18\n19\n20\n21\n22\n23\n24\n25\n26\n27\n28\n29\n30\n31\n32\n33import com.fasterxml.jackson.databind.json.JsonMapper;\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.core.http.StreamResponse;\nimport com.openai.models.beta.agents.AgentSessionEvent;\nimport com.openai.models.beta.agents.EnvironmentParam;\nimport com.openai.models.beta.agents.sessions.SessionCreateParams;\n\nOpenAIClient client = OpenAIOkHttpClient.fromEnv();\nvar json = new JsonMapper();\ntry (StreamResponse<AgentSessionEvent> events =\n    client\n        .beta()\n        .agents()\n        .sessions()\n        .createStreaming(\n            SessionCreateParams.builder()\n                .agent(\n                    SessionCreateParams.Agent.builder()\n                        .model(\"gpt-6-astra\")\n                        .instructions(\"Write clean code, run it, and report the actual output.\")\n                        .build())\n                .environment(EnvironmentParam.OpenAIHosted.builder().build())\n                .input(\n                    \"Create tree.py, a Python script that prints a readable tree of the files\"\n                        + \" in the current directory. Run it and show me the output.\")\n                .build())) {\n  var iterator = events.stream().iterator();\n  while (iterator.hasNext()) {\n    var event = iterator.next();\n    System.out.println(json.writeValueAsString(event));\n  }\n}\n```\n\nRun it from your terminal:\n\n```\nmvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExample\n```\n\nInstall the Ruby SDK:\n\n```\ngem install openai\n```\n\nSave the example as `quickstart.rb`:\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16\n17\n18\n19require \"openai\"\nrequire \"json\"\n\nclient = OpenAI::Client.new\nevents = client.beta.agents.sessions.create_streaming(\n  agent: {\n    model: \"gpt-6-astra\",\n    instructions: \"Write clean code, run it, and report the actual output.\"\n  },\n  environment: { type: \"openai_hosted\" },\n  input: \"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.\"\n)\nbegin\n  events.each do |event|\n    puts JSON.generate(event.to_h)\n  end\nensure\n  events.close\nend\n```\n\nRun it from your terminal:\n\n```\nruby quickstart.rb\n```\n\nUse cURL from your terminal; no SDK installation is needed:\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \\\n  -H \"OpenAI-Beta: agents=v1\" \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"agent\": {\n      \"model\": \"gpt-6-astra\",\n      \"instructions\": \"Write clean code, run it, and report the actual output.\"\n    },\n    \"environment\": { \"type\": \"openai_hosted\" },\n    \"input\": \"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.\",\n    \"stream\": true\n  }'\n```\n\n**Don’t need a sandbox?** Set `environment.type` to `none` for agents that\nanswer questions or call external tools without running commands or working\nwith local files. [Learn\nmore](https://developers.openai.com/api/docs/guides/agents-api/architecture#start-without-an-environment).\n\n## 2. Follow progress\n\nThe terminal shows streamed events. The SDK examples print JSON; cURL shows the raw event stream. On a successful run, the agent creates `tree.py`, executes it, and reports a directory tree containing that file. Other files and output depend on the sandbox.\n\nLook for `agent.session.turn.completed`, then check the agent’s reported execution result. A completed turn does not guarantee every tool succeeded. Events ending in `turn.failed`, `turn.cancelled`, or `session.failed` indicate failure or cancellation; `agent.session.idle` alone does not mean success. If the stream disconnects early, [retrieve the session and its saved items](https://developers.openai.com/api/docs/guides/agents-api/sessions#how-to-recover-a-disconnected-stream) before retrying.\n\n## 3. Continue the session\n\nSave the `session_id` from the events. Use it to [send a follow-up](https://developers.openai.com/api/docs/guides/agents-api/sessions#send-input) such as “Add a maximum-depth option to `tree.py`, run it, and show me the output.” Open the event stream before sending follow-up input so you don’t miss early events.\n\n## 4. Clean up\n\nKeep the session for more tasks, or delete it when you’re done. [Save any files you need](https://developers.openai.com/api/docs/guides/agents-api/environments/files) first.\n\nReplace the illustrative `sess_123` value in the example with the session ID you saved.\n\n```\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12# Replace the illustrative IDs and URLs below with your own resource values.\n\nfrom openai import OpenAI\n\ndef delete_session(client: OpenAI, session_id: str):\n    return client.beta.agents.sessions.delete(session_id)\n\nif __name__ == \"__main__\":\n    result = delete_session(OpenAI(), \"sess_123\")\n    print(result.to_json())\n1\n2\n3\n4\n5\n6\n7\n8\n9// Replace the illustrative IDs and URLs below with your own resource values.\nimport OpenAI from \"openai\";\n\nasync function deleteSession(client, sessionId) {\n  return client.beta.agents.sessions.delete(sessionId);\n}\n\nconst result = await deleteSession(new OpenAI(), \"sess_123\");\nconsole.log(result);\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16\n17\n18\n19\n20\n21\n22// Replace the illustrative IDs and URLs below with your own resource values.\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openai/openai-go/v3\"\n)\n\nfunc deleteSession(ctx context.Context, client *openai.Client, sessionID string) (*openai.AgentSessionDeleted, error) {\n\treturn client.Beta.Agents.Sessions.Delete(ctx, sessionID)\n}\n\nfunc main() {\n\tclient := openai.NewClient()\n\tresult, err := deleteSession(context.Background(), &client, \"sess_123\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tfmt.Println(result)\n}\n1\n2\n3\n4\n5\n6\n7\n8\n9\n10\n11\n12\n13\n14\n15\n16\n17\n18\n19\n20// Replace the illustrative IDs and URLs below with your own resource values.\nimport com.openai.client.OpenAIClient;\nimport com.openai.client.okhttp.OpenAIOkHttpClient;\nimport com.openai.models.beta.agents.AgentSessionDeleted;\nimport com.openai.models.beta.agents.sessions.SessionDeleteParams;\n\npublic final class AgentsApiSessionsDeleteSessionExample {\n  public static AgentSessionDeleted deleteSession(OpenAIClient client, String sessionId) {\n    return client\n        .beta()\n        .agents()\n        .sessions()\n        .delete(SessionDeleteParams.builder().sessionId(sessionId).build());\n  }\n\n  public static void main(String[] args) {\n    var result = deleteSession(OpenAIOkHttpClient.fromEnv(), \"sess_123\");\n    System.out.println(result);\n  }\n}\n1\n2\n3\n4\n5\n6\n7\n8# Replace the illustrative IDs and URLs below with your own resource values.\nrequire \"openai\"\n\ndef delete_session(client, session_id)\n  client.beta.agents.sessions.delete(session_id)\nend\n\nputs delete_session(OpenAI::Client.new, \"sess_123\")\n1\n2\n3curl -X DELETE \"https://api.openai.com/v1/agents/sessions/sess_123\" \\\n  -H \"OpenAI-Beta: agents=v1\" \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\"\n```\n\n## Next steps\n\n- [Explore example applications](https://developers.openai.com/api/docs/guides/agents-api/overview#try-an-example) .\n- [Configure an OpenAI-hosted sandbox](https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted) : add packages and input files, control network access, and download artifacts.\n- [Compare release notes with subagents](https://developers.openai.com/api/docs/guides/agents-api/multi-agent#example-compare-release-notes) .\n- [Work with files and artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files) .\n- [Choose an environment](https://developers.openai.com/api/docs/guides/agents-api/configuration#environment-settings) , or[connect your own sandbox](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted) .", "url": "https://wpnews.pro/news/agents-api-quickstart", "canonical_source": "https://developers.openai.com/api/docs/guides/agents-api/quickstart", "published_at": "2026-09-23 00:00:00+00:00", "updated_at": "2026-09-24 21:30:09.766995+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models", "ai-products"], "entities": ["OpenAI", "Agents API", "gpt-6-astra", "Python SDK", "JavaScript SDK", "Go SDK", "openai-java", "openai_hosted"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/agents-api-quickstart", "markdown": "https://wpnews.pro/news/agents-api-quickstart.md", "text": "https://wpnews.pro/news/agents-api-quickstart.txt", "jsonld": "https://wpnews.pro/news/agents-api-quickstart.jsonld"}}