Créez un assistant de programmation qui écrit le script tree.py, l’exécute et affiche l’arborescence d’un répertoire. OpenAI gère l’agent, sa conversation et le bac à sable dans lequel il travaille.
Prérequis
Créez une clé API d’application dans votre projet sur la plateforme OpenAI. Accordez à cette clé les autorisations api.agents.read et api.agents.write pour les opérations sur les sessions, ainsi que api.responses.write pour l’inférence du modèle. Exportez ensuite la clé :
export OPENAI_API_KEY="your-api-key"Conservez cette clé en dehors du bac à sable de l’agent. Pour connaître les options de configuration et les limites du bac à sable, consultez la page Bacs à sable hébergés par OpenAI.
Les requêtes doivent inclure l’en-tête OpenAI-Beta: agents=v1. Les SDK OpenAI l’ajoutent
automatiquement. Avec cURL, ajoutez-le explicitement.
1. Exécutez une tâche
Choisissez un langage, installez le SDK OpenAI et exécutez l’exemple. Les exemples qui utilisent un SDK s’appuient sur l’espace de noms beta.agents. La requête crée une session, soumet une tâche et transmet les événements de progression en continu.
Installez ou mettez à jour le SDK Python :
pip install --upgrade openaiEnregistrez l’exemple dans 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_idExécutez-le depuis votre terminal :
python quickstart.pyInstallez le SDK JavaScript :
npm install openaiEnregistrez l’exemple dans 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,
});
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();
}Exécutez-le depuis votre terminal :
node quickstart.mjsDans un nouveau répertoire, créez un module Go et installez le SDK :
go mod init agents-quickstart
go get github.com/openai/openai-go/v3@latestEnregistrez l’exemple dans 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)Exécutez-le depuis votre terminal :
go run .Ajoutez le SDK OpenAI au fichier pom.xml de votre projet Maven :
<dependency>
<groupId>com.openai</groupId>
<artifactId>openai-java</artifactId>
<version>4.103.0</version>
</dependency>Enregistrez l’exemple dans 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);
}Exécutez-le depuis votre terminal :
mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExampleInstallez le SDK Ruby :
gem install openaiEnregistrez l’exemple dans 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
endExécutez-le depuis votre terminal :
ruby quickstart.rbUtilisez cURL depuis votre terminal, sans avoir à installer de SDK :
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
}'Vous n’avez pas besoin de bac à sable ? Définissez environment.type sur none pour les agents qui
répondent à des questions ou appellent des outils externes sans exécuter de commandes ni manipuler
de fichiers locaux. En savoir plus.
2. Suivez la progression
Le terminal affiche les événements à mesure qu’ils arrivent. Les exemples qui utilisent un SDK les affichent au format JSON. cURL affiche le flux d’événements brut. Si l’exécution réussit, l’agent crée le fichier tree.py, l’exécute et affiche une arborescence qui contient ce fichier. Les autres fichiers et le reste de la sortie dépendent du bac à sable.
Repérez l’événement agent.session.turn.completed, puis vérifiez le résultat d’exécution indiqué par l’agent. La fin d’un tour ne garantit pas que tous les appels d’outils ont réussi. Les événements dont le nom se termine par turn.failed, turn.cancelled ou session.failed signalent un échec ou une annulation. L’événement agent.session.idle ne suffit pas à confirmer la réussite de la tâche. Si le flux s’interrompt prématurément, récupérez la session et ses éléments enregistrés avant de réessayer.
3. Poursuivez la session
Enregistrez la valeur de session_id figurant dans les événements. Utilisez-la pour envoyer une nouvelle instruction, par exemple « Ajoutez une option permettant de limiter la profondeur de l’arborescence dans tree.py, puis exécutez le script et montrez-moi le résultat. » Ouvrez le flux d’événements avant d’envoyer cette instruction pour recevoir les événements dès le début.
4. Supprimez la session de test
Conservez la session pour d’autres tâches ou supprimez-la lorsque vous avez terminé. Avant de la supprimer, enregistrez les fichiers dont vous avez besoin.
Remplacez la valeur sess_123 de l’exemple par l’identifiant de session que vous avez enregistré.
# 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"Étapes suivantes
- Découvrez des exemples d’applications.
- Configurez un bac à sable hébergé par OpenAI pour ajouter des paquets et des fichiers d’entrée, contrôler l’accès au réseau et télécharger des artefacts.
- Comparez des notes de version à l’aide de sous-agents.
- Manipulez des fichiers et des artefacts.
- Choisissez un environnement ou connectez votre propre bac à sable.