Démarrage rapide de l’API Agents

Créez un assistant de programmation qui écrit tree.py, l’exécute et affiche une arborescence de répertoires. 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 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, puis exportez la clé :

export OPENAI_API_KEY="your-api-key"

Conservez cette clé en dehors du bac à sable de l’agent. Consultez la page Bacs à sable hébergés par OpenAI pour connaître les options de configuration et les limites des bacs à sable.

Les requêtes nécessitent l’en-tête OpenAI-Beta: agents=v1. Les SDK OpenAI l’ajoutent automatiquement ; incluez-le explicitement lorsque vous utilisez cURL.

1. Exécutez une tâche

Choisissez un langage, installez le SDK OpenAI et exécutez l’exemple. Les exemples utilisant les SDK emploient l’espace de noms beta.agents. La requête crée une session, soumet une tâche et transmet sa progression en continu.

Installez ou mettez à jour le SDK Python :

pip install --upgrade openai

Enregistrez l’exemple dans le fichier quickstart.py :

Créez et exécutez tree.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)

Exécutez-le depuis votre terminal :

python quickstart.py

Installez le SDK JavaScript :

npm install openai

Enregistrez l’exemple dans le fichier quickstart.mjs :

Créez et exécutez tree.py

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();
}

Exécutez-le depuis votre terminal :

node quickstart.mjs

Dans 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@latest

Enregistrez l’exemple dans le fichier main.go :

Créez et exécutez tree.py

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)
}

Exécutez-le depuis votre terminal :

go run .

Ajoutez le SDK OpenAI au fichier pom.xml de votre projet Maven :

1
2
3
4
5<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.58.0</version>
</dependency>

Enregistrez l’exemple dans le fichier src/main/java/AgentsApiSessionsStreamConversationExample.java :

Créez et exécutez tree.py

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));
  }
}

Exécutez-le depuis votre terminal :

mvn compile exec:java -Dexec.mainClass=AgentsApiSessionsStreamConversationExample

Installez le SDK Ruby :

gem install openai

Enregistrez l’exemple dans le fichier quickstart.rb :

Créez et exécutez tree.py

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

Exécutez-le depuis votre terminal :

ruby quickstart.rb

Utilisez cURL depuis votre terminal ; aucune installation de SDK n’est nécessaire :

Créez et exécutez tree.py

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
  }'

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 transmis en continu. Les exemples utilisant les SDK affichent du JSON ; cURL affiche le flux d’événements brut. Si l’exécution réussit, l’agent crée tree.py, l’exécute et présente une arborescence de répertoires contenant ce fichier. Les autres fichiers et les sorties dépendent du bac à sable.

Repérez agent.session.turn.completed, puis vérifiez le résultat d’exécution rapporté par l’agent. Un tour terminé ne garantit pas que tous les outils ont réussi. Les événements dont le nom se termine par turn.failed, turn.cancelled ou session.failed indiquent un échec ou une annulation ; agent.session.idle seul ne signifie pas que l’exécution a réussi. Si le flux est interrompu prématurément, récupérez la session et ses éléments enregistrés avant de réessayer.

3. Poursuivez la session

Enregistrez le session_id présent dans les événements. Utilisez-le pour envoyer un message de suivi, par exemple : “Add a maximum-depth option to tree.py, run it, and show me the output.” Ouvrez le flux d’événements avant d’envoyer ce nouveau message pour ne pas manquer les premiers événements.

4. Nettoyez les ressources

Conservez la session pour d’autres tâches, ou supprimez-la lorsque vous avez terminé. Enregistrez d’abord les fichiers dont vous avez besoin.

Remplacez la valeur sess_123 utilisée à titre d’exemple par l’identifiant de session que vous avez enregistré.

Supprimez la session

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())

Supprimez la session

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);

Supprimez la session

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)
}

Supprimez la session

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);
  }
}

Supprimez la session

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")

Étapes suivantes

Explorez des exemples d’applications.
Configurez un bac à sable hébergé par OpenAI : ajoutez des packages et des fichiers d’entrée, contrôlez l’accès au réseau et téléchargez des artefacts.
Comparez des notes de version à l’aide de sous-agents.
Travaillez avec des fichiers et des artefacts.
Choisissez un environnement ou connectez votre propre bac à sable.

Suggestions

Bien démarrer

Concepts fondamentaux

SDK et CLI

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Conception de prompts

Raisonnement

Images et vidéo

Realtime et audio

Modèles spécialisés

API Agents

SDK Agents

ChatKit

Recherche et récupération

Connectez des outils et des données

Créez des flux de travail avec des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Développez avec la voix

Connexions

Traitement audio

Passez en production

Performances et qualité

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts fondamentaux

Plan

Build

Test and publish

Conversion specs

Guides

Ressources

Bien démarrer

Guides

File Upload

API

Measurement

Advertiser API

Référence de l’API

Bien démarrer

Fondamentaux

Explorer

Disponible sur

Versions

Flux de travail

Capacités

Référence

Personnalisation

Fichier de configuration

Configuration des agents

Étendez les capacités de ChatGPT et de Codex

Linux

Windows

Flux de travail de développement

Étendre et automatiser

Environnements

Développer avec Codex

Intégrations tierces

Référence

Autorisations

Codex Security

Cybersécurité

Bien démarrer

ChatGPT Work

Identité et authentification

Accès à l’espace de travail, stratégies et modèles

Contrôles des plugins et des connecteurs

Utilisation, gouvernance et conformité

Déploiement et fournisseurs de modèles

Communauté

Blog

Communauté

Blog