Une session conserve la configuration de l’agent, sa conversation et le travail enregistré au fil du temps. Réutilisez la même session pour envoyer de nouveaux messages et poursuivre le travail.
Un tour est un cycle de travail au sein d’une session. Si la session est inactive, l’envoi d’un message démarre un nouveau tour. Si un tour est en cours, le message en oriente la suite.
Les tours s’exécutent de manière asynchrone. Votre application peut suivre leur progression via un flux d’événements ou recevoir les changements d’état de la session via des webhooks.
Utilisez des automatisations planifiées pour lancer le travail à une date ultérieure ou à intervalles réguliers. Une automatisation peut créer une session à chaque exécution ou poursuivre une conversation existante.
Créez une session en fournissant une configuration d’agent et une entrée initiale dans input. Définissez stream sur true pour recevoir les événements du premier tour dans la même requête.
Une fois votre clé API et votre SDK configurés, exécutez cet exemple pour créer et exécuter un script. OpenAI gère son environnement d’exécution.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import 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();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from 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_id
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
33
34
35import (
"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)
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
33
34
35
36
37
38
39import 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);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "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
end
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
}'
Enregistrez le session_id avec l’état de la conversation dans votre application. Utilisez cet identifiant pour envoyer de nouveaux messages et récupérer le travail enregistré pour cette conversation.
Pour activer le mode d’approbation automatique des actions, définissez review sur "auto_review" lors de la création d’une session éligible dans un projet où l’examen automatique est activé. Vous pouvez modifier ce paramètre lorsque la tâche principale est inactive et que l’envoi des données d’entrée est terminé. Consultez la section Examen automatique pour connaître les modes d’examen, les prérequis de l’environnement et le fonctionnement des approbations.
Consultez la configuration des agents pour connaître les paramètres d’agent réutilisables et la documentation sur l’architecture pour connaître les environnements disponibles. Les sessions configurées avec environment.type: "none" nécessitent une entrée initiale. La référence sur la création de sessions répertorie les champs de la requête.
Si la session utilise des pièces jointes de l’API Files, la vérification des fichiers peut renvoyer une erreur HTTP 429 avec le code
files_api_rate_limit_exceeded. Consultez les limites de débit de l’API Files
pour savoir comment reprendre le traitement.
L’environnement d’exécution de l’agent accepte des requêtes allant jusqu’à 4 Mio (4 194 304 octets). Veillez à ce que la taille cumulée de input et du schéma de sortie (agent.text.format.schema) reste inférieure à cette limite. Prévoyez une marge pour les métadonnées ajoutées par l’API Agents. Les fichiers importés dans l’environnement sont soumis à des limites distinctes.
Les événements signalent les sorties et les changements à mesure que l’agent travaille. Vérifiez si le tour s’est terminé normalement, a échoué ou a été annulé. Le seul fait que la session soit inactive ne suffit pas à conclure que le tour a réussi.
Recherchez l’événement agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled. Examinez aussi la sortie de l’agent. Même si le tour s’est terminé normalement, certains appels d’outils peuvent avoir échoué.
Si la session attend le résultat d’une fonction ou une connexion à un environnement, récupérez la session et examinez required_actions. Votre code doit traiter l’appel de fonction ou connecter l’environnement pour que le travail puisse se poursuivre.
Consultez la section Événements et éléments pour connaître les types d’événements et les données qu’ils contiennent.
Envoyez un autre message de type agent.session.input.message à la même session. Si l’agent travaille, le message oriente la suite du tour en cours. Si la session est inactive, le message démarre un nouveau tour dans la conversation existante.
La même limite de taille de l’entrée s’applique aux messages suivants.
Les modifications apportées à un agent enregistré s’appliquent uniquement aux nouvelles sessions. Pour modifier le modèle, l’effort de raisonnement ou l’offre pour les prochains tours de cette session, mettez à jour les paramètres de la session.
Utilisez l’identifiant de session de la conversation pour envoyer des données d’entrée. Abonnez-vous à son flux d’événements avant d’envoyer le message afin que votre application reçoive les premiers événements du tour.
Créez une clé d’idempotence pour chaque envoi logique de message. Enregistrez-la avec le message avant de l’envoyer. Utilisez la clé enregistrée lors de l’envoi.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// Reuse the same submission key when retrying this message.
async function sendMessage(client, sessionId, text, submissionKey) {
await client.beta.agents.sessions.events.create(sessionId, {
"Idempotency-Key": submissionKey,
events: [
{
type: "agent.session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text,
},
],
},
],
},
],
});
}
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
31from uuid import uuid4
# Reuse the same submission key when retrying this message.
def send_message(
client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
client.beta.agents.sessions.events.create(
session_id,
idempotency_key=submission_key,
events=[
{
"type": "agent.session.input.message",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": text,
}
],
}
],
}
],
)
submission_key = str(uuid4())
# Save this key with the message before submitting it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// Reuse the same submission key when retrying this message.
func sendMessage(ctx context.Context, client *openai.Client, sessionID, text, submissionKey string) error {
return client.Beta.Agents.Sessions.Events.New(ctx,
sessionID,
openai.BetaAgentSessionEventNewParams{
IdempotencyKey: openai.String(submissionKey),
Events: []openai.AgentSessionInputParamUnion{
{
OfParamAgentSessionInputMessage: &openai.AgentSessionInputParamAgentSessionInputMessage{
Input: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: text},
},
},
},
},
},
},
},
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Reuse the same submission key when retrying this message.
public static void sendMessage(
OpenAIClient client, String sessionId, String text, String submissionKey) {
client
.beta()
.agents()
.sessions()
.events()
.create(
EventCreateParams.builder()
.sessionId(sessionId)
.idempotencyKey(submissionKey)
.addEvent(
AgentSessionInputParam.AgentSessionInputMessage.builder()
.addInput(
AgentSessionInputMessageParam.builder()
.addInputTextContent(text)
.build())
.build())
.build());
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Reuse the same submission key when retrying this message.
def send_message(client, session_id, text, submission_key)
client.beta.agents.sessions.events.create(
session_id,
idempotency_key: submission_key,
events: [
{
type: "agent.session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text: text
}
]
}
]
}
]
)
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl \
"https://api.openai.com/v1/agents/sessions/$session_id/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Idempotency-Key: $submission_key" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "agent.session.input.message",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "List the files in the current directory."
}
]
}
]
}
]
}'
Transmettez la clé dans l’en-tête Idempotency-Key et réutilisez-la pour les nouvelles tentatives automatiques. Si votre application retente l’envoi après l’expiration du délai d’attente ou la perte de la réponse, réutilisez la même clé, le même identifiant de session et le même message. Générez une clé différente pour chaque envoi distinct, même si le texte du message est identique.
Pour un exemple qui combine l’envoi d’un message et la réception des événements en continu, consultez la section Événements et éléments.
Les événements permettent de suivre la progression en direct. Les éléments correspondent aux messages et aux appels d’outils enregistrés, y compris les réponses complètes. Récupérez ces éléments pour afficher le travail précédent ou examiner les résultats après la fin d’un tour.
1
2
3
4
5
6
7// Pass your saved session ID to this helper.
async function listItems(client, sessionId) {
return client.beta.agents.sessions.items.list(sessionId, {
order: "asc",
limit: 100,
});
}
1
2
3# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)
1
2
3
4
5
6
7
8
9// Pass your saved session ID to this helper.
func listItems(ctx context.Context, client *openai.Client, sessionID string) (*pagination.CursorPage[openai.AgentSessionItemUnion], error) {
return client.Beta.Agents.Sessions.Items.List(ctx,
sessionID,
openai.BetaAgentSessionItemListParams{
Order: "asc",
Limit: openai.Int(100),
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14// Pass your saved session ID to this helper.
public static ItemListPage listItems(OpenAIClient client, String sessionId) {
return client
.beta()
.agents()
.sessions()
.items()
.list(
ItemListParams.builder()
.sessionId(sessionId)
.order(ItemListParams.Order.of("asc"))
.limit(100L)
.build());
}
1
2
3
4
5
6
7
8# Pass your saved session ID to this helper.
def list_items(client, session_id)
client.beta.agents.sessions.items.list(
session_id,
order: "asc",
limit: 100
)
end
1
2
3
4curl \
"https://api.openai.com/v1/agents/sessions/$session_id/items?order=asc&limit=100" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"
Consultez la section Gestion des sessions pour examiner l’état d’une session et l’issue de ses tours. Pour récupérer les fichiers, suivez les instructions de la section Fichiers et artefacts.
Les flux ne retransmettent pas les événements manqués. Après une déconnexion, récupérez la session et ses éléments enregistrés pour retrouver le travail effectué. Consultez la section Rétablir un flux après une déconnexion pour connaître la procédure de reconnexion.
Annulez le tour en cours lorsque vous souhaitez que l’agent s’arrête. La session et le travail effectué précédemment restent accessibles.
1
2
3
4
5
6// Pass your saved session ID to this helper.
async function cancelTurn(client, sessionId) {
await client.beta.agents.sessions.events.create(sessionId, {
events: [{ type: "agent.session.input.cancel" }],
});
}
1
2
3
4
5# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
client.beta.agents.sessions.events.create(
session_id, events=[{"type": "agent.session.input.cancel"}]
)
1
2
3
4
5
6
7
8
9
10// Pass your saved session ID to this helper.
func cancelTurn(ctx context.Context, client *openai.Client, sessionID string) error {
return client.Beta.Agents.Sessions.Events.New(ctx,
sessionID,
openai.BetaAgentSessionEventNewParams{
Events: []openai.AgentSessionInputParamUnion{
{OfParamAgentSessionInputCancel: &openai.AgentSessionInputParamAgentSessionInputCancel{}},
},
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13// Pass your saved session ID to this helper.
public static void cancelTurn(OpenAIClient client, String sessionId) {
client
.beta()
.agents()
.sessions()
.events()
.create(
EventCreateParams.builder()
.sessionId(sessionId)
.addEventAgentSessionInputCancel()
.build());
}
1
2
3
4
5
6
7# Pass your saved session ID to this helper.
def cancel_turn(client, session_id)
client.beta.agents.sessions.events.create(
session_id,
events: [{ type: "agent.session.input.cancel" }]
)
end
1
2
3
4
5curl "https://api.openai.com/v1/agents/sessions/$session_id/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.cancel"}]}'
