Plug-ins

Um plug-in reúne habilidades, configurações de MCP ou ambos em um pacote. Carregue seus arquivos no seu próprio ambiente ou envie um ZIP para um ambiente hospedado pela OpenAI.

Empacote o plug-in

Este plug-in combina uma habilidade de pesquisa na documentação com o MCP da documentação da OpenAI. Ele precisa de acesso à rede, mas não exige credenciais nem dependências de servidor local.

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

Declare o diretório da habilidade 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 resolvidos a partir da raiz do plug-in. Eles devem começar com ./, permanecer dentro do plug-in e não conter componentes ... Consulte Empacote seu plug-in para ver o formato completo do manifesto.

Adicione o servidor a .mcp.json. Esse arquivo usa o formato de plug-in, 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 plug-ins em um sandbox auto-hospedado

Copie o plug-in para /workspace/plugins/docs-helper e adicione esse caminho absoluto a environment.capability_directories. Selecione a raiz do plug-in, 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 plug-in. Permita que o ambiente acesse https://developers.openai.com/mcp.

Para usar vários plug-ins, liste a raiz de cada um. Um diretório pai pode descobrir habilidades em subdiretórios, mas não carrega a configuração de MCP de cada plug-in filho.

Envie plug-ins para um sandbox hospedado pela OpenAI

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

Esta função auxiliar empacota sua pasta e cria uma sessão. Passe seu cliente de API e o caminho para docs-helper. A OpenAI extrai e registra o plug-in 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 uma configuração de plug-in hospedado

Crie um modelo de ambiente com a lista de plug-ins. Nas sessões seguintes, defina environment.environment_template_id como o ID do modelo salvo.

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

Autentique servidores MCP

O exemplo não exige autenticação. Para outros servidores MCP de plug-ins:

• HTTP: bearer_token_env_var lê uma variável de ambiente e envia seu valor como um token bearer. Os demais valores de http_headers são literais; env_http_headers não é compatível.
• 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. Um caminho relativo em cwd é resolvido a partir da raiz do plug-in.

Mantenha segredos fora dos arquivos e pacotes de plug-ins. As conexões MCP dos plug-ins são executadas a partir do ambiente da sessão. Consulte Autenticação MCP para conhecer os limites de uso das credenciais.

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

Teste um plug-in

Envie uma mensagem normal na sessão solicitando o uso da habilidade:

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

Verifique se o turno foi concluído e se os itens salvos incluem uma chamada bem-sucedida a openai_docs. A resposta deve seguir as instruções da habilidade e citar a documentação. Para um plug-in que contém apenas habilidades, verifique se a saída segue as instruções; não é necessária uma chamada MCP.

Crie uma nova sessão após alterar os arquivos do plug-in ou um modelo. As sessões existentes não recarregam as ferramentas. Para erros de conexão, consulte Solução de problemas de MCP. Exclua as sessões de teste e pare os recursos de computação auto-hospedados ao terminar.