Complementos

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

Empaquetar el complemento

Este complemento combina una habilidad de búsqueda en la documentación con el MCP de 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 la habilidad 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 desde la raíz del complemento. Deben comenzar con ./, permanecer dentro del complemento y no contener componentes ... 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 alojado en tu propia infraestructura

Copia el complemento en /workspace/plugins/docs-helper y agrega esa ruta absoluta a environment.capability_directories. Selecciona la 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.

Para usar varios complementos, incluye la raíz de cada uno en la lista. Un directorio padre permite descubrir habilidades anidadas, pero no carga la configuración de MCP de cada complemento hijo.

Subir complementos a un sandbox alojado por OpenAI

Proporciona un ZIP por complemento en environment.plugins. Cada ZIP debe contener una carpeta de complemento con .codex-plugin/plugin.json dentro. 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 extrae 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 una configuración de complementos alojados

Crea una plantilla de entorno con la lista de complementos. Para las sesiones posteriores, establece environment.environment_template_id en 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 obtiene su propio entorno, que comparten el agente raíz y sus subagentes.

Autenticar servidores MCP

El ejemplo no necesita autenticación. Para otros servidores MCP de complementos:

• 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 son literales; env_http_headers no es compatible.
• Stdio: env_vars enumera las variables de entorno que se pasan al proceso del servidor. Instala el ejecutable y sus dependencias en el entorno. Un valor relativo de cwd se resuelve desde la raíz del complemento.

Mantén los secretos fuera de los archivos y los paquetes comprimidos del complemento. Las conexiones MCP de los complementos se ejecutan desde el entorno de la sesión. Consulta Autenticación de MCP para conocer los límites de uso de las credenciales.

Para los MCP alojados que usan stdio, omite la política de red o establécela en enabled. Las políticas de red disabled y restricted no son compatibles con estas conexiones.

Probar un complemento

Envía un mensaje normal en la sesión que solicite usar la habilidad:

Use docs-search to explain how to stream Responses API output. Include links to the documentation.

Verifica 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 contiene habilidades, verifica que su salida cumpla con las instrucciones; no se requiere una llamada a MCP.

Crea una sesión nueva después de cambiar 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. Elimina las sesiones de prueba y detén los recursos de cómputo alojados en tu propia infraestructura cuando termines.