Entwickle einen Programmierassistenten, der tree.py schreibt, das Skript ausführt und einen Verzeichnisbaum anzeigt. OpenAI verwaltet den Agenten, den Gesprächsverlauf und die Sandbox, in der der Agent arbeitet.
Voraussetzungen
Erstelle in deinem Projekt auf der OpenAI Platform einen API-Schlüssel für deine Anwendung. Weise dem Schlüssel die Berechtigungen api.agents.read und api.agents.write für Sitzungsoperationen sowie api.responses.write für die Modellinferenz zu. Exportiere ihn anschließend als Umgebungsvariable.
export OPENAI_API_KEY="your-api-key"
Bewahre den Schlüssel außerhalb der Sandbox des Agenten auf. Angaben zur Konfiguration und zu den Einschränkungen findest du im Leitfaden zu von OpenAI gehosteten Sandboxen.
Anfragen benötigen den Header OpenAI-Beta: agents=v1. Die OpenAI-SDKs fügen ihn automatisch hinzu. Wenn du cURL verwendest, gib ihn ausdrücklich an.
1. Aufgabe ausführen
Wähle eine Programmiersprache, installiere das OpenAI-SDK und führe das Beispiel aus. Die SDK-Beispiele verwenden den Namensraum beta.agents. Die Anfrage erstellt eine Sitzung, übermittelt eine Aufgabe und liefert fortlaufend Ereignisse zum Fortschritt.
Installiere oder aktualisiere das Python-SDK.
pip install --upgrade openaiSpeichere das Beispiel als quickstart.py.
from 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,
).with_result_collection() as stream:
for event in stream:
print(event.to_json(indent=None), flush=True)
result = stream.get_final_result()
print(result.output_text)
session_id = result.session_idFühre das Beispiel im Terminal aus.
python quickstart.pyVerwende Node.js ab Version 22.6 und installiere das TypeScript-SDK.
npm install openaiSpeichere das Beispiel als quickstart.mts.
import 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,
});
events.withResultCollection();
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
const result = await events.finalResult();
console.log(result.output_text);
console.log("Session:", result.session_id);
} finally {
events.controller.abort();
}Führe das Beispiel im Terminal aus.
node --experimental-strip-types quickstart.mtsErstelle in einem neuen Verzeichnis ein Go-Modul und installiere das SDK.
go mod init agents-quickstart
go get github.com/openai/openai-go/v3@latestSpeichere das Beispiel als main.go.
import (
"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()
openai.BetaAgentSessionWithResultCollection(events)
if events.Err() != nil {
panic(events.Err())
}
for events.Next() {
event := events.Current()
fmt.Println(event.RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(events)
if err != nil {
panic(err)
}
fmt.Println(result.OutputText())
sessionID := result.SessionID()
fmt.Println("Session:", sessionID)Führe das Beispiel im Terminal aus.
go run .Füge das OpenAI-SDK in der pom.xml deines Maven-Projekts als Abhängigkeit hinzu.
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>4.105.0</version>
</dependency>Speichere das Beispiel als src/main/java/AgentsApiSessionsStreamConversationExample.java.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.ObjectMappers;
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;
import com.openai.services.beta.agents.AgentTurnResults;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = ObjectMappers.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())) {
AgentTurnResults.withResultCollection(events);
var iterator = events.stream().iterator();
while (iterator.hasNext()) {
var event = iterator.next();
System.out.println(json.writeValueAsString(event));
}
var result = AgentTurnResults.getFinalResult(events);
System.out.println(result.outputText());
String sessionId = result.sessionId();
System.out.println(sessionId);
}Führe das Beispiel im Terminal aus.
mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExampleInstalliere das Ruby-SDK.
gem install openaiSpeichere das Beispiel als quickstart.rb.
require "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.with_result_collection
events.each do |event|
puts JSON.generate(event.to_h)
end
result = events.get_final_result
puts result.output_text
session_id = result.session_id
puts "Session: #{session_id}"
ensure
events.close
endFühre das Beispiel im Terminal aus.
ruby quickstart.rbFühre cURL im Terminal aus. Dafür brauchst du kein SDK zu installieren.
curl --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
}'Du brauchst keine Sandbox? Setze environment.type auf none, wenn dein Agent Fragen beantwortet oder externe Tools aufruft, ohne Befehle auszuführen oder mit lokalen Dateien zu arbeiten. Mehr erfahren.
2. Fortschritt verfolgen
Im Terminal siehst du die Ereignisse, sobald sie eintreffen. Die SDK-Beispiele geben sie als JSON aus. cURL zeigt den unverarbeiteten Ereignisstream an. Bei erfolgreicher Ausführung erstellt der Agent tree.py, führt das Skript aus und gibt einen Verzeichnisbaum aus, der diese Datei enthält. Welche weiteren Dateien und Ausgaben du siehst, hängt von der Sandbox ab.
Achte auf agent.session.turn.completed und prüfe anschließend, welches Ergebnis der Agent für die Ausführung meldet. Auch bei einem abgeschlossenen Durchlauf können einzelne Toolaufrufe fehlgeschlagen sein. Ereignisse, deren Namen auf turn.failed, turn.cancelled oder session.failed enden, weisen auf einen Fehler oder Abbruch hin. Das Ereignis agent.session.idle allein bestätigt keinen Erfolg. Wenn die Verbindung zum Stream vorzeitig abbricht, rufe die Sitzung und die darin gespeicherten Elemente ab, bevor du es erneut versuchst.
3. Sitzung fortsetzen
Speichere die session_id aus den Ereignissen. Damit kannst du eine weitere Nachricht senden, zum Beispiel „Ergänze tree.py um eine Option für die maximale Verzeichnistiefe, führe das Skript aus und zeige mir die Ausgabe.“ Öffne den Ereignisstream, bevor du die nächste Nachricht sendest, damit du die ersten Ereignisse nicht verpasst.
4. Aufräumen
Behalte die Sitzung für weitere Aufgaben oder lösche sie, wenn du fertig bist. Sichere vorher alle Dateien, die du noch brauchst.
Ersetze den Beispielwert sess_123 durch die Sitzungs-ID, die du gespeichert hast.
# 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())// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
async function deleteSession(client: OpenAI, sessionId: string) {
return client.beta.agents.sessions.delete(sessionId);
}
const result = await deleteSession(new OpenAI(), "sess_123");
console.log(result);// 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)
}// 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);
}
}# 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")curl -X DELETE "https://api.openai.com/v1/agents/sessions/sess_123" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"Nächste Schritte
- Sieh dir Beispielanwendungen an.
- Konfiguriere eine von OpenAI gehostete Sandbox. Füge Pakete und Eingabedateien hinzu, steuere den Netzwerkzugriff und lade Artefakte herunter.
- Vergleiche Versionshinweise mithilfe von Subagenten.
- Arbeite mit Dateien und Artefakten.
- Wähle eine Umgebung oder binde deine eigene Sandbox an.