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 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 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:
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.
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 before retrying.
3. Continue the session #
Save the session_id from the events. Use it to send a follow-up 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 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 .
- Configure an OpenAI-hosted sandbox : add packages and input files, control network access, and download artifacts.
- Compare release notes with subagents .
- Work with files and artifacts .
- Choose an environment , orconnect your own sandbox .