Complementos

Un complemento puede incluir habilidades, configuración de MCP o ambas cosas. Carga sus archivos en tu propio entorno o sube un archivo ZIP a un entorno alojado por OpenAI.

Empaquetar el complemento

Este complemento combina una habilidad para buscar en la documentación con el servidor MCP de la documentación de OpenAI. Necesita acceso a la red, pero no requiere credenciales ni dependencias de un servidor local.

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

Declara el directorio de habilidades y la configuración de MCP en .codex-plugin/plugin.json:

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

Las rutas se resuelven a partir del directorio raíz del complemento. Deben comenzar con ./, permanecer dentro del complemento y no contener segmentos ... Consulta Empaquetar tu complemento para conocer el formato completo del archivo de manifiesto.

Agrega el servidor a .mcp.json. Este archivo usa el formato de los complementos, que difiere del de agent.tools:

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

Agrega las instrucciones a 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.

Registrar complementos en un sandbox autoalojado

Copia el complemento en /workspace/plugins/docs-helper y agrega esa ruta absoluta a environment.capability_directories. Selecciona el directorio raíz del complemento, que contiene .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

Conecta el ejecutor antes de que el agente use el complemento. Permite que el entorno acceda a https://developers.openai.com/mcp.

Si usas varios complementos, incluye el directorio raíz de cada uno. Un directorio superior permite detectar habilidades en subdirectorios, pero no carga la configuración de MCP de todos los complementos que contiene.

Subir complementos a un sandbox alojado por OpenAI

Proporciona un archivo ZIP por complemento en environment.plugins. Cada ZIP debe contener una sola carpeta de complemento que incluya .codex-plugin/plugin.json. El nombre y la descripción de la solicitud deben coincidir con los del archivo de manifiesto.

Esta función auxiliar empaqueta tu carpeta y crea una sesión. Pásale tu cliente de API y la ruta a docs-helper. OpenAI descomprime y registra el complemento automáticamente.

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(),
                        },
                    }
                ],
            },
        )

Reutilizar la configuración de complementos en un entorno alojado

Crea una plantilla de entorno con la lista de complementos. En las sesiones posteriores, asigna a environment.environment_template_id el ID de la plantilla guardada.

Omite environment.plugins para heredar la lista de complementos de la plantilla. Si proporcionas una lista, esta reemplaza la de la plantilla. Cada sesión tiene su propio entorno, que comparten el agente raíz y sus subagentes.

Autenticar servidores MCP

El ejemplo no requiere autenticación. Para otros servidores MCP de complementos, ten en cuenta lo siguiente:

• HTTP: bearer_token_env_var lee una variable de entorno y envía su valor como token de portador. Los demás valores de http_headers se usan literalmente. No se admite env_http_headers.
• Stdio: env_vars enumera las variables de entorno que se pasan al proceso del servidor. Instala el ejecutable y sus dependencias en el entorno. Si cwd es una ruta relativa, se resuelve a partir del directorio raíz del complemento.

Evita incluir secretos en los archivos del complemento o en los archivos comprimidos. Las conexiones MCP del complemento se establecen desde el entorno de la sesión. Consulta Autenticación de MCP para conocer el alcance de las credenciales.

Para los servidores MCP alojados que usan stdio, omite la política de red o asígnale el valor enabled. Estas conexiones no admiten las políticas de red disabled y restricted.

Probar un complemento

Envía un mensaje normal en la sesión y pide que se use la habilidad:

Usa docs-search para explicar cómo recibir la salida de la API Responses a medida que se genera. Incluye enlaces a la documentación.

Comprueba que el turno haya finalizado y que sus elementos guardados incluyan una llamada exitosa a openai_docs. La respuesta debe seguir las instrucciones de la habilidad y citar la documentación. Si el complemento solo incluye habilidades, comprueba que el resultado siga las instrucciones. En ese caso, no se requiere una llamada MCP.

Crea una sesión nueva después de modificar los archivos del complemento o una plantilla. Las sesiones existentes no vuelven a cargar las herramientas. Si hay errores de conexión, consulta Solución de problemas de MCP. Al terminar, elimina las sesiones de prueba y detén los recursos de cómputo autoalojados.