API Agents

L’API Agents donne à votre application accès au harnais Codex via une API gérée par OpenAI.

OpenAI gère les sessions, l’orchestration, le compactage du contexte et la reprise, tandis que votre application fournit les outils et choisit son environnement d’exécution.

Les agents peuvent travailler dans un bac à sable pour exécuter du code, modifier des fichiers, se connecter à des serveurs MCP et produire des artefacts.

Tarifs

L’utilisation du modèle est facturée aux tarifs de l’API du modèle sélectionné. Les outils OpenAI sont facturés à leurs tarifs standard, et les bacs à sable hébergés par OpenAI aux tarifs standard des conteneurs.

Essayez un exemple

Essayez ces exemples complets :

Créez et exécutez un script d’arborescence de répertoires dans un bac à sable hébergé par OpenAI.
Comparez des notes de version avec des sous-agents et rassemblez leurs conclusions dans une seule réponse.

Explorez des applications complètes :

Agent de réponse aux incidents : examinez les alertes et demandez une approbation pour les actions de rétablissement.
Bot Slack : analysez les demandes à l’aide des outils de travail connectés.
Analyste de données : répondez aux questions sur l’entrepôt de données à l’aide de requêtes SQL en lecture seule.
Utilisez l’outil d’investigation des issues GitHub pour reproduire les bugs signalés et partager les résultats sur GitHub.
Utilisez l’outil de révision de documents pour réviser des documents à l’aide de Skills dédiées aux politiques et d’agents spécialisés.

Concepts fondamentaux

L’API Agents repose sur quatre concepts principaux :

Agent : Le modèle, les instructions, les outils et les serveurs MCP à la disposition de l’agent.
Environnement : Un bac à sable ou un ordinateur facultatif dans lequel l’agent accède aux fichiers, charge des skills et exécute des commandes.
Session : Une instance persistante d’un agent qui exécute des tâches et répond aux entrées.
Événements et éléments : Les entrées envoyées à un agent et les sorties produites au cours d’une session.

Une session de bout en bout

Commencez avec un bac à sable hébergé par OpenAI en suivant le guide de démarrage rapide :

Créez une session. Configurez l’agent ; OpenAI provisionne son environnement.
Confiez-lui une tâche. Une entrée utilisateur lance un tour de travail dès que l’environnement est prêt.
Suivez la progression. Recevez les sorties en streaming ou utilisez des webhooks pour savoir quand l’agent a terminé ou attend une entrée.
Poursuivez ou orientez le travail. Envoyez une autre tâche à la même session ou guidez l’agent pendant le tour en cours.

Avec une session hébergée par OpenAI, votre application envoie des entrées et reçoit des événements, tandis qu’OpenAI exécute l’agent, provisionne son bac à sable et le gère. Consultez les options d’environnement pour connaître la configuration et les limites.

Votre application démarre des sessions et reçoit des événements et des sorties de l’API Agents. OpenAI exécute le harnais Codex géré, provisionne son bac à sable et le gère.

Fonctionnalités du harnais géré

Le harnais Codex géré prend en charge :

L’exécution de commandes et de code dans un bac à sable.
L’application des skills et des instructions pertinentes.
L’accès à des données externes via des outils ou MCP.
L’orientation de l’agent pendant son travail.
La synthèse du travail précédent pour gérer sa fenêtre de contexte.
La décomposition du travail en sous-tâches et leur délégation à des sous-agents.
La reprise d’une session là où elle s’était arrêtée.

Consultez les prérequis du guide de démarrage rapide pour connaître les autorisations des clés API et la configuration du SDK. Configurez ces fonctionnalités lors de la création d’une session :

Configurez les fonctionnalités du harnais géré

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
28
29
30
31
32
33
34
35
36
37
38
39
40
41import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp",
        },
      },
      { type: "web_search" },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 4 },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
        },
      ],
    },
  ],
});
console.log(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
35
36
37
38
39
40from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {
                    "type": "http",
                    "server_url": "https://developers.openai.com/mcp",
                },
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
                }
            ],
        }
    ],
)
print(session.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"
	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra"),
	Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
	Tools: []openai.AgentToolParamUnion{openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
		openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs",
			Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},
		openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}}},
	MultiAgent: openai.MultiAgentConfigParam{Enabled: true,
		MaxConcurrentSubagents: openai.Int(4)}},
	Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace",
		CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},
	Input: openai.BetaAgentSessionNewParamsInputUnion{OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{openai.AgentSessionInputMessageParam{Content: []openai.InputContentParamUnion{openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}}}}}}})
if err != nil {
	panic(err)
}
fmt.Println(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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "Use the OpenAI documentation MCP and web search to answer"
                                + " technical questions accurately. Delegate independent"
                                + " research tasks to subagents when useful.")
                        .addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
                        .addTool(
                            AgentToolParam.Mcp.builder()
                                .serverLabel("openai_docs")
                                .transport(
                                    McpTransportParam.Http.builder()
                                        .serverUrl("https://developers.openai.com/mcp")
                                        .build())
                                .build())
                        .addTool(AgentToolParam.WebSearch.builder().build())
                        .multiAgent(
                            MultiAgentConfigParam.builder()
                                .enabled(true)
                                .maxConcurrentSubagents(4L)
                                .build())
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/capabilities/skills"))
                        .build())
                .input(
                    "Research how to connect an MCP server to an OpenAI agent, check for recent"
                        + " updates, and summarize the recommended setup.")
                .build());
System.out.println(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
35
36
37
38
39
40
41
42
43require "openai"

client = OpenAI::Client.new

session = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp"
        }
      },
      { type: "web_search" }
    ],
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 4
    }
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"]
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
        }
      ]
    }
  ]
)
puts 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
35
36
37
38
39
40
41
42
43
44
45
46curl -sS -X POST "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": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
      "tools": [
        {
          "type": "programmatic_tool_calling"
        },
        {
          "type": "mcp",
          "server_label": "openai_docs",
          "transport": {
            "type": "http",
            "server_url": "https://developers.openai.com/mcp"
          }
        },
        {
          "type": "web_search"
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 4
      }
    },
    "environment": {
      "type": "self_hosted",
      "workspace_directory": "/workspace",
      "capability_directories": ["/workspace/capabilities/skills"]
    },
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
          }
        ]
      }
    ]
  }'

Pour comparer les environnements d’exécution, consultez la vue d’ensemble des agents.

L’API Agents conserve l’état des sessions pour vous permettre de poursuivre le travail d’un tour à l’autre sans reconstituer le contexte de la conversation. Vous pouvez supprimer les sessions et les artefacts publiés lorsque vous n’en avez plus besoin. L’API Agents ne prend actuellement en charge la résidence des données qu’aux États-Unis et ne prend pas en charge la politique de non-conservation des données (ZDR). Le choix d’un bac à sable autohébergé ne rend pas l’API Agents éligible à la ZDR. Consultez la page Contrôle des données sur la plateforme OpenAI pour en savoir plus sur la résidence et la conservation des données.

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

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