Configuration des agents

La configuration d’un agent détermine son comportement. Vous pouvez la fournir à la création d’une session ou l’enregistrer pour la réutiliser. La session conserve la conversation et le travail effectué. L’agent enregistré conserve les paramètres réutilisables.

Définir le comportement de l’agent

Choisissez d’abord le modèle et rédigez les instructions, puis ajoutez les outils et les paramètres de contrôle nécessaires à votre tâche :

Modèle : le modèle qui exécute la tâche.
Instructions : ce que l’agent doit faire et comment il doit se comporter.
Outils : les actions que l’agent peut effectuer, comme lancer une recherche sur le Web ou appeler vos fonctions.
Raisonnement et sortie : l’effort de raisonnement du modèle ainsi que le format et le niveau de détail de ses réponses.

Transmettez ces paramètres dans agent à la création d’une session. Cet exemple fournit un modèle, des instructions et le premier message de l’utilisateur :

Configurer un agent pour une session

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions: "Answer the user clearly and concisely.",
  },
  environment: {
    type: "none",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What can you help with?",
        },
      ],
    },
  ],
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Answer the user clearly and concisely.",
    },
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "What can you help with?"}],
        }
    ],
)
print(session.to_json())

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
32import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{
			Model:        openai.String("gpt-6-astra"),
			Instructions: openai.String("Answer the user clearly and concisely."),
		},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{
							OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},
						},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions("Answer the user clearly and concisely.")
                        .build())
                .environmentNone()
                .input("What can you help with?")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "Answer the user clearly and concisely."
  },
  environment: { type: "none" },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What can you help with?"
        }
      ]
    }
  ]
)
puts result

Consultez la référence de l’API Agents pour connaître les champs de configuration et leurs valeurs. Pour la mise en place, consultez les guides Fonctions, Utilisation de l’ordinateur, Connexions MCP ou Délégation entre agents.

Taille de la configuration

Veillez à ce que la taille cumulée des instructions et de la configuration des outils reste inférieure à 4 Mio (4 194 304 octets), en laissant une petite marge pour les métadonnées de l’API Agents. Si la session ne démarre pas parce que la configuration est trop volumineuse, créez une session avec des instructions plus courtes et une configuration des outils plus compacte.

Les fichiers que vous importez dans l’environnement sont soumis à des limites distinctes.

Réutiliser un agent dans plusieurs sessions

Enregistrez un agent pour réutiliser sa configuration dans plusieurs sessions. Créez-le une seule fois, puis transmettez son identifiant dans agent_id au démarrage de chaque session :

Réutiliser un agent

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";

const client = new OpenAI();
const agent = await client.beta.agents.create({
  model: "gpt-6-astra",
  instructions: "Answer technical questions accurately.",
  reasoning: {
    summary: "auto",
  },
});
const session = await client.beta.agents.sessions.create({
  agent_id: agent.id,
  environment: { type: "none" },
  input: "Explain how an agent connects to an MCP server.",
});
console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from openai import OpenAI

client = OpenAI()
agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
    timeout=360,
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())

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
28import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
agent, err := client.Beta.Agents.New(ctx,
	openai.BetaAgentNewParams{
		Model:        "gpt-6-astra",
		Instructions: openai.String("Answer technical questions accurately."),
		Reasoning:    openai.AgentReasoningParam{Summary: "auto"},
	})
if err != nil {
	panic(err)
}
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		AgentID:     openai.String(agent.ID),
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input:       openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

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
32import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentCreateParams;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var agent =
    client
        .beta()
        .agents()
        .create(
            AgentCreateParams.builder()
                .model("gpt-6-astra")
                .instructions("Answer technical questions accurately.")
                .reasoning(
                    AgentReasoningParam.builder()
                        .summary(AgentReasoningParam.Summary.of("auto"))
                        .build())
                .build());
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId(agent.id())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"

client = OpenAI::Client.new
agent = client.beta.agents.create(
  model: "gpt-6-astra",
  instructions: "Answer technical questions accurately.",
  reasoning: { summary: "auto" }
)
result = client.beta.agents.sessions.create(
  agent_id: agent.id,
  environment: { type: "none" },
  input: "Explain how an agent connects to an MCP server."
)
puts result

Chaque session conserve sa propre conversation et le travail qui y est effectué. Consultez la référence de l’API Agents pour savoir comment lister, récupérer, mettre à jour ou supprimer les agents enregistrés. Les informations d’authentification restent dans des coffres-forts, séparément de la configuration enregistrée.

Mettre à jour un agent enregistré

Les mises à jour d’un agent enregistré s’appliquent uniquement aux nouvelles sessions. À sa création, chaque session copie la configuration enregistrée et conserve ces paramètres pour les tours de conversation suivants. Pour modifier une session existante, mettez à jour ses paramètres.

Lorsque vous mettez à jour un agent enregistré :

Les champs omis conservent leur valeur enregistrée. Si vous modifiez uniquement model, les valeurs de reasoning, service_tier et text sont conservées.
Tout objet fourni remplace la totalité du champ correspondant. Si vous fournissez reasoning avec uniquement effort, la valeur enregistrée de summary est également effacée.
null réinitialise les champs qui acceptent cette valeur. Par exemple, reasoning: null rétablit l’effort de raisonnement par défaut du modèle.

Dans la même requête, modifiez ou réinitialisez tout paramètre que le nouveau modèle ne prend pas en charge.

Remplacer des paramètres pour une seule session

Fournissez à la fois agent_id et agent à la création d’une session pour personnaliser la configuration d’un agent enregistré. Pour les paramètres omis, y compris le modèle, la session reprend les valeurs de l’agent enregistré au moment de sa création.

Remplacez la valeur d’exemple agent_123 par l’identifiant de l’agent enregistré avant d’exécuter cet exemple :

Remplacer les paramètres d’un agent pour une session

Python

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// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const agentId = "agent_123";
const session = await client.beta.agents.sessions.create({
  agent_id: agentId,
  agent: {
    instructions: "Answer this question in one concise paragraph.",
  },
  environment: {
    type: "none",
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Explain how an agent connects to an MCP server.",
        },
      ],
    },
  ],
});

console.log(session);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI

client = OpenAI()

agent_id = "agent_123"
session = client.beta.agents.sessions.create(
    agent_id=agent_id,
    agent={"instructions": "Answer this question in one concise paragraph."},
    environment={"type": "none"},
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Explain how an agent connects to an MCP server.",
                }
            ],
        }
    ],
)
print(session.to_json())

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// Replace the illustrative IDs and URLs below with your own resource values.
import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		AgentID:     openai.String("agent_123"),
		Agent:       openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},
		Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
		Input: openai.BetaAgentSessionNewParamsInputUnion{
			OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
				{
					Content: []openai.InputContentParamUnion{
						{
							OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},
						},
					},
				},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result)

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.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agentId("agent_123")
                .agent(
                    SessionCreateParams.Agent.builder()
                        .instructions("Answer this question in one concise paragraph.")
                        .build())
                .environmentNone()
                .input("Explain how an agent connects to an MCP server.")
                .build());
System.out.println(result);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent_id: "agent_123",
  agent: { instructions: "Answer this question in one concise paragraph." },
  environment: { type: "none" },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Explain how an agent connects to an MCP server."
        }
      ]
    }
  ]
)
puts result

Ces modifications s’appliquent uniquement à cette session. Elles ne modifient ni l’agent enregistré ni les autres sessions. Tout objet ou tableau fourni remplace la totalité du champ, sans fusion avec la valeur enregistrée. Par exemple, si vous fournissez tools, la liste d’outils fournie remplace la liste enregistrée.

Consultez la référence sur la création de sessions pour connaître les champs de la requête.

Mettre à jour les paramètres d’une session existante

Envoyez une requête POST /v1/agents/sessions/{session_id} avec un objet agent pour modifier tools, model, reasoning.effort ou service_tier pour une seule session. Les contrats de l’API prennent en charge ces paramètres aussi bien en version bêta qu’en disponibilité générale (GA). Vous pouvez mettre à jour metadata dans la même requête.

Les changements de modèle, d’effort de raisonnement et d’offre s’appliquent aux tours de conversation déclenchés par les messages envoyés après la fin de la mise à jour. Les messages déjà en cours de traitement peuvent utiliser les paramètres précédents. Un tour en cours conserve les valeurs de ces trois paramètres, même si vous envoyez un message pour réorienter l’agent. La session conserve l’historique de la conversation. Si le modèle sélectionné ne prend pas en charge la configuration obtenue, la mise à jour échoue.

Dans les objets agent et reasoning, les champs fournis sont fusionnés avec les paramètres actuels. Les champs omis conservent leur valeur, y compris le résumé du raisonnement. Si vous modifiez uniquement model, la session conserve son effort de raisonnement et son offre.
tools remplace toute la liste des outils. Les modifications apportées aux fonctions et aux serveurs MCP prennent effet dès le prochain appel au modèle. Celles qui concernent les outils intégrés prennent effet au plus tard au tour de conversation suivant. Omettez tools pour conserver les outils actuels, ou transmettez null ou [] pour vider la liste.
reasoning.effort: null rétablit l’effort de raisonnement par défaut du modèle sélectionné.
service_tier: null rétablit la sélection automatique de l’offre.
Un modèle doit toujours être défini. Vous ne pouvez donc pas fournir model: null. Les objets agent et reasoning n’acceptent pas non plus la valeur null.
metadata remplace l’ensemble des paires clé-valeur. Omettez ce champ pour conserver les métadonnées, ou transmettez null ou {} pour les effacer.

Par exemple, cette requête modifie l’effort de raisonnement et laisse l’API sélectionner automatiquement l’offre :

123456{
  "agent": {
    "reasoning": { "effort": "low" },
    "service_tier": null
  }
}

La mise à jour d’une session ne modifie ni l’agent enregistré ni les autres sessions. Les mises à jour ultérieures de l’agent enregistré ne modifient pas la session.

Ce point de terminaison ne permet pas de mettre à jour reasoning.summary, text, instructions ou multi_agent. Créez une session pour modifier ces paramètres. Consultez la référence sur la mise à jour des sessions pour connaître les champs de la requête.

Révision automatique des actions

Définissez le champ de session review sur "auto_review" pour que l’API examine automatiquement les demandes d’approbation prises en charge. Placez ce champ au même niveau que agent ou agent_id, en dehors de la configuration de l’agent. Si vous omettez review à la création d’une session, sa valeur par défaut est "none".

Le mode d’approbation automatique modifie également les autorisations d’exécution. Vérifiez les prérequis de l’environnement avant de l’activer.

Vous pouvez mettre à jour review lorsque la tâche principale est inactive et qu’aucun envoi de données d’entrée n’est encore en cours. Le nouveau paramètre s’applique aux exécutions et aux reprises ultérieures. Si vous demandez à changer de mode avant que ces deux conditions soient réunies, l’API renvoie 409 Conflict et n’applique aucune modification. Utilisez un projet dans lequel le mode d’approbation automatique est activé et une session qui le prend en charge. Consultez le guide Révision automatique pour savoir comment configurer ce mode et traiter les demandes d’approbation.

Paramètres de l’environnement

Définissez environment au même niveau que agent à la création d’une session. Ce paramètre détermine où l’agent exécute les commandes et manipule les fichiers.

Choisissez none, openai_hosted ou self_hosted. Le guide Architecture explique quand utiliser chaque option et qui gère l’environnement dans chaque cas.

Pour un environnement hébergé par OpenAI, choisissez une taille de conteneur et configurez les paquets, les fichiers initiaux et l’accès réseau nécessaires à la tâche. Vous pouvez réutiliser un modèle d’environnement dans plusieurs sessions. Pour un environnement auto-hébergé, préparez vos ressources de calcul et connectez un exécuteur.

Consultez la référence sur la création de sessions pour connaître les champs de configuration de l’environnement, et le guide Plugins pour les skills, les plugins et les modèles. Pour conserver des fichiers après l’exécution, consultez le guide Artefacts de session.

Suggestions

Premiers pas

Notions fondamentales

SDK et CLI

Fournisseurs de services cloud

Ressources

Anciennes API

Choisissez un modèle

Texte et code

Rédaction de prompts

Raisonnement

Images

Temps réel et audio

Modèles spécialisés

API Agents

Agents SDK

ChatKit

Recherche et récupération d’informations

Connectez des outils et des sources de données

Créez des workflows qui font appel à des outils

Ordinateur et code

Médias

GPT-Live

Realtime API

Créer des applications vocales

Connexions

Traitement audio

Mise en production

Performances et qualité

Évaluation

Coût et débit

Sécurité et gouvernance

Infrastructure et accès

Opérations

Concepts clés

Planification

Développement

Tests et publication

Spécifications de conversion

Guides

Ressources

Identité

Utilisation du forfait ChatGPT

Guides

Envoi de fichiers

API

Mesure des performances

API pour les annonceurs

Référence de l’API

Premiers pas

Premiers pas

Notions de base

Explorer

Disponible sur

Versions

Workflows

Capacités

Sites

dots

Espace ChatGPT

Référence

Personnalisation

Fichier de configuration