Plugins

Um plugin pode reunir habilidades, configurações de MCP ou ambas. Carregue os arquivos do plugin no seu próprio ambiente ou envie um arquivo ZIP para um ambiente hospedado pela OpenAI.

Empacote o plugin

Este plugin combina uma habilidade de busca na documentação com o servidor MCP da documentação da OpenAI. Ele precisa de acesso à rede, mas dispensa credenciais e dependências de servidor local.

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

Declare o diretório de habilidades e a configuração de MCP em .codex-plugin/plugin.json.

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

Os caminhos são relativos à raiz do plugin. Eles devem começar com ./, apontar para dentro do plugin e não conter componentes ... Consulte Empacote seu plugin para ver o formato completo do manifesto.

Adicione o servidor a .mcp.json. Esse arquivo usa o formato de plugin, que é diferente do formato de agent.tools.

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

Adicione as instruções 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.

Registre plugins em uma sandbox auto-hospedada

Copie o plugin para /workspace/plugins/docs-helper e adicione esse caminho absoluto a environment.capability_directories. Selecione o diretório raiz do plugin, que contém .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

Conecte o executor antes que o agente use o plugin. Permita que o ambiente acesse https://developers.openai.com/mcp.

Para registrar vários plugins, liste o diretório raiz de cada um. Se você listar um diretório pai, o agente poderá descobrir habilidades nos subdiretórios, mas isso não carregará a configuração de MCP de todos os plugins nesses subdiretórios.

Envie plugins para uma sandbox hospedada pela OpenAI

Forneça um arquivo ZIP por plugin em environment.plugins. Cada ZIP deve conter uma única pasta de plugin com .codex-plugin/plugin.json dentro dela. O nome e a descrição na solicitação devem corresponder aos do manifesto.

Esta função empacota a pasta e cria uma sessão. Passe o cliente da API e o caminho para docs-helper. A OpenAI extrai e registra o plugin automaticamente.

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

Reutilize a configuração de plugins de um ambiente hospedado

Crie um modelo de ambiente com a lista de plugins. Nas próximas sessões, defina environment.environment_template_id como o ID do modelo salvo.

Omita environment.plugins para herdar a lista de plugins do modelo. Se você fornecer uma lista, ela substituirá a do modelo. Cada sessão tem seu próprio ambiente, compartilhado pelo agente raiz e seus subagentes.

Autentique servidores MCP

O exemplo dispensa autenticação. Para outros servidores MCP de plugins, siga as orientações conforme o tipo de conexão.

• HTTP: bearer_token_env_var lê uma variável de ambiente e envia seu valor como token do tipo Bearer. Os demais valores de http_headers são literais. Não há suporte a env_http_headers.
• Stdio: env_vars lista as variáveis de ambiente a serem passadas ao processo do servidor. Instale o executável e suas dependências no ambiente. Se cwd for um caminho relativo, ele será resolvido a partir da raiz do plugin.

Mantenha os segredos fora dos arquivos do plugin e dos pacotes compactados. As conexões MCP do plugin partem do ambiente da sessão. Consulte Autenticação de MCP para entender os limites de uso das credenciais.

Para servidores MCP hospedados que usam stdio, omita a política de rede ou defina seu valor como enabled. As políticas de rede disabled e restricted não são compatíveis com essas conexões.

Teste um plugin

Envie uma mensagem comum na sessão pedindo ao agente que use a habilidade.

Use docs-search para explicar como receber a saída da Responses API por streaming. Inclua links para a documentação.

Verifique se o turno foi concluído e se os itens salvos desse turno incluem uma chamada bem-sucedida a openai_docs. A resposta deve seguir as instruções da habilidade e citar a documentação. Se o plugin contiver apenas habilidades, compare o resultado com as instruções. Nesse caso, a chamada MCP é opcional.

Crie uma nova sessão depois de alterar os arquivos do plugin ou um modelo de ambiente. As sessões existentes não recarregam as ferramentas. Em caso de erro de conexão, consulte Solução de problemas de MCP. Ao terminar, exclua as sessões de teste e desligue os recursos de computação auto-hospedados.