Plugins

Un plugin peut contenir des skills, une configuration MCP ou les deux. Chargez ses fichiers dans votre propre environnement ou importez une archive ZIP dans un environnement hébergé par OpenAI.

Préparez le plugin

Ce plugin associe un skill de recherche documentaire au serveur MCP de la documentation OpenAI. Il nécessite un accès réseau et fonctionne sans identifiants ni dépendances serveur locales.

docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md

Déclarez le répertoire des skills et la configuration MCP dans .codex-plugin/plugin.json :

1234567{
  "name": "docs-helper",
  "version": "1.0.0",
  "description": "Find answers in OpenAI developer documentation.",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

Les chemins sont relatifs à la racine du plugin. Ils doivent commencer par ./, rester dans le répertoire du plugin et ne contenir aucun segment ... Consultez la section Préparez votre plugin pour connaître le format complet du manifeste.

Ajoutez le serveur à .mcp.json. Ce fichier utilise le format des plugins, qui diffère de celui de agent.tools :

12345678{
  "mcpServers": {
    "openai_docs": {
      "type": "http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}

Ajoutez les instructions à skills/docs-search/SKILL.md :

---
name: docs-search
description: Find answers in OpenAI developer documentation.
---

Use the openai_docs MCP server to find relevant documentation.
Answer the question and link to the sources you used.

Enregistrez des plugins dans un bac à sable auto-hébergé

Copiez le plugin dans /workspace/plugins/docs-helper et ajoutez ce chemin absolu à environment.capability_directories. Sélectionnez le répertoire racine du plugin, qui contient .codex-plugin/plugin.json.

1
2
3
4
5
6
7
8
9
10
11
12
13
14import OpenAI from "openai";
const client = new OpenAI();

const result = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/plugins/docs-helper"],
  },
});
console.log(result.id);

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

client = OpenAI()

result = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/plugins/docs-helper"],
    },
)
print(result.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()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{
				WorkspaceDirectory:    "/workspace",
				CapabilityDirectories: []string{"/workspace/plugins/docs-helper"},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result.ID)

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

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/plugins/docs-helper"))
                        .build())
                .build());
System.out.println(result.id());

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

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/plugins/docs-helper"]
  }
)
puts result.id

Connectez l’exécuteur avant que l’agent utilise le plugin. Autorisez l’environnement à accéder à https://developers.openai.com/mcp.

Si vous utilisez plusieurs plugins, indiquez le répertoire racine de chacun. Un répertoire parent permet de détecter les skills dans ses sous-répertoires, mais ne charge pas automatiquement la configuration MCP de tous les plugins qu’il contient.

Importez des plugins dans un bac à sable hébergé par OpenAI

Fournissez une archive ZIP par plugin dans environment.plugins. Chaque archive doit contenir un seul dossier de plugin, dans lequel doit se trouver .codex-plugin/plugin.json. Le nom et la description indiqués dans la requête doivent correspondre à ceux du manifeste.

Cette fonction utilitaire crée une archive à partir de votre dossier, puis crée une session. Passez-lui votre client API et le chemin vers docs-helper. OpenAI extrait et enregistre automatiquement le plugin.

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
37import base64
import json
import shutil
from pathlib import Path
from tempfile import TemporaryDirectory


def upload_plugin(client, plugin_directory):
    plugin_directory = Path(plugin_directory).resolve()
    manifest = json.loads((plugin_directory / ".codex-plugin/plugin.json").read_text())
    with TemporaryDirectory() as temporary:
        archive = shutil.make_archive(
            str(Path(temporary) / "plugin"),
            "zip",
            root_dir=plugin_directory.parent,
            base_dir=plugin_directory.name,
        )
        return client.beta.agents.sessions.create(
            agent={"model": "gpt-6-astra"},
            environment={
                "type": "openai_hosted",
                "plugins": [
                    {
                        "type": "inline",
                        "name": manifest["name"],
                        "description": manifest["description"],
                        "source": {
                            "type": "base64",
                            "media_type": "application/zip",
                            "data": base64.b64encode(
                                Path(archive).read_bytes()
                            ).decode(),
                        },
                    }
                ],
            },
        )

Réutilisez une configuration de plugins hébergés

Créez un modèle d’environnement avec la liste des plugins. Pour les sessions suivantes, attribuez à environment.environment_template_id l’identifiant du modèle enregistré.

Omettez environment.plugins pour hériter de la liste des plugins du modèle. Si vous fournissez une liste, elle remplace celle du modèle pour la session. Chaque session dispose de son propre environnement, que l’agent racine partage avec ses sous-agents.

Configurez l’authentification des serveurs MCP

Cet exemple ne nécessite aucune authentification. Pour les serveurs MCP d’autres plugins, utilisez les paramètres correspondant au transport :

• HTTP : bearer_token_env_var lit une variable d’environnement et envoie sa valeur sous forme de jeton Bearer. Les autres valeurs de http_headers sont transmises telles quelles. Le format ne prend pas en charge env_http_headers.
• Stdio : env_vars indique les variables d’environnement à transmettre au processus du serveur. Installez l’exécutable et ses dépendances dans l’environnement. Si cwd est un chemin relatif, il est résolu à partir de la racine du plugin.

N’incluez aucun secret dans les fichiers ou les archives du plugin. Le plugin établit ses connexions MCP depuis l’environnement de la session. Consultez la section Authentification MCP pour savoir où les identifiants peuvent être utilisés.

Pour les serveurs MCP hébergés qui utilisent stdio, omettez la politique réseau ou définissez-la sur enabled. Ces connexions ne prennent pas en charge les politiques réseau disabled et restricted.

Testez un plugin

Envoyez un message ordinaire dans la session pour demander à l’agent d’utiliser le skill :

Utilisez docs-search pour expliquer comment recevoir en continu les données renvoyées par l’API Responses. Incluez des liens vers la documentation.

Vérifiez que le tour est terminé et que ses éléments enregistrés contiennent un appel réussi à openai_docs. La réponse doit suivre les instructions du skill et citer la documentation. Si le plugin contient uniquement des skills, vérifiez que sa réponse respecte les instructions. Aucun appel MCP n’est nécessaire dans ce cas.

Créez une nouvelle session après toute modification des fichiers du plugin ou d’un modèle. Les sessions existantes ne rechargent pas les outils. En cas d’erreur de connexion, consultez la section Dépannage des connexions MCP. Supprimez les sessions de test et arrêtez les ressources de calcul auto-hébergées une fois les tests terminés.