Configuration des agents

La configuration d’un agent définit son comportement. Vous pouvez la fournir lors de la création d’une session ou l’enregistrer pour la réutiliser. La session contient la conversation et le travail effectué, tandis que l’agent enregistré conserve les paramètres réutilisables.

Définissez le comportement de l’agent

Commencez par le modèle et les instructions, puis ajoutez les outils et les contrôles nécessaires à votre tâche :

Modèle : Le modèle qui effectue le travail.
Instructions : Ce que l’agent doit faire et comment il doit se comporter.
Outils : Les actions que l’agent peut effectuer, comme rechercher 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 lors de la création d’une session. Cet exemple fournit un modèle, des instructions et le premier message utilisateur :

Configurez 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 les valeurs acceptées. Consultez Fonctions et Connexions MCP pour configurer les outils, et Multi-agents pour la délégation.

Réutilisez 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éutilisez 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 a sa propre conversation et son propre travail. Consultez la référence de l’API Agents pour lister, récupérer, mettre à jour ou supprimer les agents enregistrés. Les identifiants d’authentification restent dans les coffres-forts, séparés de la configuration enregistrée.

Mettez à jour un agent enregistré

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

Lors de la mise à jour d’un agent enregistré :

Les champs omis conservent leurs valeurs enregistrées. Si vous modifiez uniquement model, les valeurs de reasoning, service_tier et text sont conservées.
Les objets fournis remplacent la totalité du champ. Si vous fournissez reasoning avec uniquement effort, la valeur enregistrée de summary est également effacée.
La valeur null réinitialise les champs qui l’acceptent. 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 tous les paramètres que le nouveau modèle ne prend pas en charge.

Remplacez les paramètres pour une session

Incluez à la fois agent_id et agent lors de la création d’une session pour personnaliser la configuration d’un agent enregistré. À sa création, la session copie depuis l’agent enregistré les paramètres omis, y compris le modèle.

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

Remplacez la configuration 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

Les remplacements s’appliquent uniquement à cette session. Ils ne modifient ni l’agent enregistré ni les autres sessions. Les objets et les tableaux fournis remplacent la totalité du champ au lieu de fusionner avec la valeur enregistrée. Par exemple, fournir tools remplace la liste des outils enregistrée.

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

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

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

Les modifications s’appliquent aux nouveaux tours déclenchés par des 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 actif conserve ses paramètres, y compris lorsque vous envoyez un message de réorientation. La session conserve son historique de conversation. Le modèle sélectionné doit prendre en charge les paramètres résultants, sinon la mise à jour échoue.

Les champs fournis dans les objets agent et reasoning sont fusionnés avec les paramètres actuels. Les champs omis restent inchangés, y compris le résumé du raisonnement. Si vous modifiez uniquement model, l’effort de raisonnement et l’offre de la session sont conservés.
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 rester 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’intégralité du dictionnaire. Omettez ce champ pour conserver les métadonnées, ou passez 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.

Vous ne pouvez pas mettre à jour reasoning.summary, text, tools, instructions ou multi_agent via ce point de terminaison. Créez une nouvelle session pour modifier ces paramètres.

Paramètres de l’environnement

Définissez environment en plus de agent lors de 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. La page Architecture explique quand utiliser chaque option et qui gère l’environnement.

Pour un environnement hébergé par OpenAI, 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 de création de session pour connaître les champs de l’environnement et la page Plugins pour les skills, les plugins et les modèles. Consultez Artefacts de session pour les fichiers que vous souhaitez conserver après l’exécution.

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