Entwickle einen Programmierassistenten, der tree.py schreibt, ausführt und einen Verzeichnisbaum anzeigt. OpenAI verwaltet den Agenten, seine Unterhaltung und die Sandbox, in der er arbeitet.
Voraussetzungen
Erstelle einen API-Schlüssel für Anwendungen in deinem Projekt auf der OpenAI Platform. Erteile ihm die Berechtigungen api.agents.read und api.agents.write für Sitzungsoperationen sowie api.responses.write für Modellinferenz. Exportiere ihn anschließend:
export OPENAI_API_KEY="your-api-key"
Bewahre diesen Schlüssel außerhalb der Sandbox des Agenten auf. Informationen zur Konfiguration und zu den Grenzen der Sandbox findest du unter Von OpenAI gehostete Sandboxen.
Anfragen benötigen den Header OpenAI-Beta: agents=v1. Die OpenAI SDKs fügen ihn
automatisch hinzu. Bei cURL musst du ihn ausdrücklich angeben.
1. Eine Aufgabe ausführen
Wähle eine Sprache aus, 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 überträgt den Fortschritt als Stream.
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,
) as events:
for event in events:
print(event.to_json(indent=None), flush=True)Führe es in deinem Terminal aus:
python quickstart.pyInstalliere das JavaScript-SDK:
npm install openaiSpeichere das Beispiel als quickstart.mjs:
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,
});
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
} finally {
events.controller.abort();
}Führe es in deinem Terminal aus:
node quickstart.mjsErstelle 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()
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)
}Führe es in deinem Terminal aus:
go run .Füge das OpenAI SDK zur Datei pom.xml deines Maven-Projekts hinzu:
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>4.58.0</version>
</dependency>Speichere das Beispiel als src/main/java/AgentsApiSessionsStreamConversationExample.java:
import 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));
}
}Führe es in deinem 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.each do |event|
puts JSON.generate(event.to_h)
end
ensure
events.close
endFühre es in deinem Terminal aus:
ruby quickstart.rbVerwende cURL in deinem Terminal. Dafür musst du kein SDK 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 die Agenten
Fragen beantworten oder externe Werkzeuge aufrufen, ohne Befehle auszuführen oder
mit lokalen Dateien zu arbeiten. Mehr
erfahren.
2. Den Fortschritt verfolgen
Das Terminal zeigt die gestreamten Ereignisse an. Die SDK-Beispiele geben JSON aus; cURL zeigt den unverarbeiteten Ereignisstream. Bei erfolgreicher Ausführung erstellt der Agent tree.py, führt die Datei aus und gibt einen Verzeichnisbaum aus, der diese Datei enthält. Weitere Dateien und Ausgaben hängen von der Sandbox ab.
Achte auf agent.session.turn.completed und prüfe anschließend das vom Agenten gemeldete Ausführungsergebnis. Ein abgeschlossener Gesprächsschritt garantiert nicht, dass jedes Tool erfolgreich ausgeführt wurde. Ereignisse, die auf turn.failed, turn.cancelled oder session.failed enden, zeigen einen Fehler oder Abbruch an. agent.session.idle allein bedeutet keinen Erfolg. Wenn der Stream vorzeitig abbricht, rufe die Sitzung und ihre gespeicherten Elemente ab, bevor du es erneut versuchst.
3. Die Sitzung fortsetzen
Speichere die session_id aus den Ereignissen. Verwende sie, um eine Folgeanfrage zu senden, zum Beispiel: “Add a maximum-depth option to tree.py, run it, and show me the output.” Öffne den Ereignisstream, bevor du weitere Eingaben sendest, damit du keine frühen Ereignisse verpasst.
4. Aufräumen
Behalte die Sitzung für weitere Aufgaben oder lösche sie, wenn du fertig bist. Speichere zuerst alle Dateien, die du noch brauchst.
Ersetze im Beispiel den Platzhalterwert 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, sessionId) {
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
- Entdecke Beispielanwendungen.
- 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 aus oder binde deine eigene Sandbox an.