Agents API quickstart

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.

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. Prerequisites Create 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: export OPENAI API KEY="your-api-key" Keep 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. Requests require the OpenAI-Beta: agents=v1 header. The OpenAI SDKs add it automatically; include it explicitly when using cURL. 1. Run a task Choose 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. Install or update the Python SDK: pip install --upgrade openai Save the example as quickstart.py : python 1 2 3 4 5 6 7 8 9 10 11 12 13 14from openai import OpenAI with OpenAI as client: with client.beta.agents.sessions.create agent={ "model": "gpt-6-astra", "instructions": "Write clean code, run it, and report the actual output.", }, environment={"type": "openai hosted"}, 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.", stream=True, as events: for event in events: print event.to json indent=None , flush=True Run it from your terminal: python quickstart.py Install the JavaScript SDK: npm install openai Save the example as quickstart.mjs : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20import OpenAI from "openai"; const client = new OpenAI ; const events = await client.beta.agents.sessions.create { agent: { model: "gpt-6-astra", instructions: "Write clean code, run it, and report the actual output.", }, environment: { type: "openai hosted" }, 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.", stream: true, } ; try { for await const event of events { console.log JSON.stringify event ; } } finally { events.controller.abort ; } Run it from your terminal: node quickstart.mjs In a new directory, create a Go module and install the SDK: go mod init agents-quickstart go get github.com/openai/openai-go/v3@latest Save the example as main.go : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30import "context" "fmt" "github.com/openai/openai-go/v3" ctx := context.Background client := openai.NewClient events := client.Beta.Agents.Sessions.NewStreaming ctx, openai.BetaAgentSessionNewParams{ Agent: openai.BetaAgentSessionNewParamsAgent{ Model: openai.String "gpt-6-astra" , Instructions: openai.String "Write clean code, run it, and report the actual output." , }, Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}}, Input: openai.BetaAgentSessionNewParamsInputUnion{ OfString: 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." , }, } defer events.Close if events.Err = nil { panic events.Err } for events.Next { event := events.Current fmt.Println event.RawJSON } if err := events.Err ; err = nil { panic err } Run it from your terminal: go run . Add the OpenAI SDK to your Maven project’s pom.xml : 1 2 3 4 5<dependency <groupId com.openai</groupId <artifactId openai-java</artifactId <version 4.69.2</version </dependency Save the example as src/main/java/AgentsApiSessionsStreamConversationExample.java : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33import com.fasterxml.jackson.databind.json.JsonMapper; import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.core.http.StreamResponse; import com.openai.models.beta.agents.AgentSessionEvent; import com.openai.models.beta.agents.EnvironmentParam; import com.openai.models.beta.agents.sessions.SessionCreateParams; OpenAIClient client = OpenAIOkHttpClient.fromEnv ; var json = new JsonMapper ; try StreamResponse<AgentSessionEvent events = client .beta .agents .sessions .createStreaming SessionCreateParams.builder .agent SessionCreateParams.Agent.builder .model "gpt-6-astra" .instructions "Write clean code, run it, and report the actual output." .build .environment EnvironmentParam.OpenAIHosted.builder .build .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." .build { var iterator = events.stream .iterator ; while iterator.hasNext { var event = iterator.next ; System.out.println json.writeValueAsString event ; } } Run it from your terminal: mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExample Install the Ruby SDK: gem install openai Save the example as quickstart.rb : 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19require "openai" require "json" client = OpenAI::Client.new events = client.beta.agents.sessions.create streaming agent: { model: "gpt-6-astra", instructions: "Write clean code, run it, and report the actual output." }, environment: { type: "openai hosted" }, 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." begin events.each do |event| puts JSON.generate event.to h end ensure events.close end Run it from your terminal: ruby quickstart.rb Use cURL from your terminal; no SDK installation is needed: 1 2 3 4 5 6 7 8 9 10 11 12 13curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \ -H "OpenAI-Beta: agents=v1" \ -H "Authorization: Bearer $OPENAI API KEY" \ -H "Content-Type: application/json" \ -d '{ "agent": { "model": "gpt-6-astra", "instructions": "Write clean code, run it, and report the actual output." }, "environment": { "type": "openai hosted" }, "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.", "stream": true }' Don’t need a sandbox? Set environment.type to none for agents that answer questions or call external tools without running commands or working with local files. Learn more https://developers.openai.com/api/docs/guides/agents-api/architecture start-without-an-environment . 2. Follow progress The 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. Look 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. 3. Continue the session Save 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. 4. Clean up Keep 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. Replace the illustrative sess 123 value in the example with the session ID you saved. 1 2 3 4 5 6 7 8 9 10 11 12 Replace the illustrative IDs and URLs below with your own resource values. from openai import OpenAI def delete session client: OpenAI, session id: str : return client.beta.agents.sessions.delete session id if name == " main ": result = delete session OpenAI , "sess 123" print result.to json 1 2 3 4 5 6 7 8 9// Replace the illustrative IDs and URLs below with your own resource values. import OpenAI from "openai"; async function deleteSession client, sessionId { return client.beta.agents.sessions.delete sessionId ; } const result = await deleteSession new OpenAI , "sess 123" ; console.log result ; 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22// Replace the illustrative IDs and URLs below with your own resource values. package main import "context" "fmt" "github.com/openai/openai-go/v3" func deleteSession ctx context.Context, client openai.Client, sessionID string openai.AgentSessionDeleted, error { return client.Beta.Agents.Sessions.Delete ctx, sessionID } func main { client := openai.NewClient result, err := deleteSession context.Background , &client, "sess 123" if err = nil { panic err } fmt.Println result } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20// Replace the illustrative IDs and URLs below with your own resource values. import com.openai.client.OpenAIClient; import com.openai.client.okhttp.OpenAIOkHttpClient; import com.openai.models.beta.agents.AgentSessionDeleted; import com.openai.models.beta.agents.sessions.SessionDeleteParams; public final class AgentsApiSessionsDeleteSessionExample { public static AgentSessionDeleted deleteSession OpenAIClient client, String sessionId { return client .beta .agents .sessions .delete SessionDeleteParams.builder .sessionId sessionId .build ; } public static void main String args { var result = deleteSession OpenAIOkHttpClient.fromEnv , "sess 123" ; System.out.println result ; } } 1 2 3 4 5 6 7 8 Replace the illustrative IDs and URLs below with your own resource values. require "openai" def delete session client, session id client.beta.agents.sessions.delete session id end puts delete session OpenAI::Client.new, "sess 123" 1 2 3curl -X DELETE "https://api.openai.com/v1/agents/sessions/sess 123" \ -H "OpenAI-Beta: agents=v1" \ -H "Authorization: Bearer $OPENAI API KEY" Next steps - Explore example applications https://developers.openai.com/api/docs/guides/agents-api/overview try-an-example . - 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. - Compare release notes with subagents https://developers.openai.com/api/docs/guides/agents-api/multi-agent example-compare-release-notes . - Work with files and artifacts https://developers.openai.com/api/docs/guides/agents-api/environments/files . - 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 .