SDK do Codex

Se você usa o Codex pela CLI do Codex, pela extensão para IDE ou pelo Codex Cloud, também pode controlá-lo por meio de código.

Use o SDK quando precisar:

• Controlar o Codex como parte do seu pipeline de CI/CD
• Criar seu próprio agente capaz de interagir com o Codex para executar tarefas complexas de engenharia
• Incorporar o Codex às suas ferramentas internas e aos seus fluxos de trabalho
• Integrar o Codex ao seu aplicativo

Use o SDK do Codex para automatizar tarefas de programação, inclusive em pipelines de CI. Use o App Server do Codex para criar clientes personalizados que gerenciem a autenticação, o histórico de conversas e as aprovações e processem os eventos do agente à medida que chegam.

O comando codex mcp-server e o binário independente codex-mcp-server foram removidos. Use o App Server do Codex nas integrações existentes.

Se você tem acesso à versão beta e precisa analisar repositórios ou alterações para obter resultados de segurança estruturados e informações sobre a cobertura da análise, use o SDK do Codex Security para TypeScript.

Biblioteca para TypeScript

Com a biblioteca para TypeScript, seu aplicativo pode iniciar, continuar e retomar conversas locais do Codex.

Use a biblioteca no servidor. Ela requer o Node.js 18 ou posterior.

Instalação

Para começar, instale o SDK do Codex com npm:

npm install @openai/codex-sdk

Uso

Inicie uma conversa com o Codex e execute seu prompt nela.

1
2
3
4
5
6
7
8
9import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);

Chame run() novamente para continuar na mesma conversa ou informe o ID de uma conversa anterior para retomá-la.

1
2
3
4
5
6
7
8
9
10
11
12
13
14// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

const threadId = thread.id!;
const thread2 = codex.resumeThread(threadId, {
  sandboxMode: "workspace-write",
});
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

Para identificar as conversas criadas pela sua integração, defina threadSource ao criar cada conversa. Por exemplo, codex.startThread({ threadSource: "ci" }) identifica a origem da conversa como ci. Quando você retoma uma conversa, ela mantém a origem definida na criação.

Substituições de configuração

Passe config para definir a configuração do Codex de forma estruturada. Para chaves que não podem ser representadas por caminhos em notação de ponto, use configOverrides para passar strings TOML diretamente, cada uma em um argumento --config separado:

1
2
3
4
5
6const codex = new Codex({
  config: { default_permissions: "audit" },
  configOverrides: [
    'permissions.audit.filesystem={":root"="read","/path/to/project/.env"="deny"}',
  ],
});

As substituições passadas diretamente em TOML têm prioridade sobre a configuração estruturada em config. Em seguida, o SDK aplica as configurações gerenciadas, como baseUrl, e as opções específicas da conversa. Por isso, elas têm prioridade sobre as duas formas de configuração anteriores. Essas substituições não alteram seus arquivos de configuração do Codex.

Para mais detalhes, consulte o repositório do SDK para TypeScript.

Biblioteca para Python

O SDK para Python controla o App Server local do Codex via JSON-RPC. Ele requer o Python 3.10 ou posterior. As versões publicadas do SDK incluem como dependência uma versão fixa do ambiente de execução da CLI do Codex.

Instalação

Para instalar o SDK, execute:

pip install openai-codex

Cada versão publicada do SDK usa automaticamente a versão do ambiente de execução definida para ela. Passe CodexConfig(codex_bin=...) somente se quiser usar um executável local específico do Codex.

O SDK para Python está disponível em versão estável. O comando pip install openai-codex instala a versão estável mais recente. Use pip install --pre openai-codex se quiser instalar versões preliminares mais recentes.

Uso

Inicie o Codex, crie uma conversa e execute um prompt. Os exemplos usam o GPT-6.1 Sol, que precisa estar disponível na conta com a qual você entrou. Caso contrário, omita model para usar o modelo padrão configurado. Consulte a disponibilidade do GPT-6.1 Sol por plano.

1
2
3
4
5
6
7
8
9from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-6.1-sol",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Use AsyncCodex quando seu aplicativo já for assíncrono:

1
2
3
4
5
6
7
8
9
10
11
12import asyncio
from openai_codex import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-6.1-sol")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

Envie conteúdo de outro sistema

Quando uma ferramenta, um aplicativo ou outro agente fornecer conteúdo, passe uma mensagem ExternalMessage como a única entrada de thread.run() ou thread.turn(). Por exemplo, ExternalMessage(tool_name="issue_tracker", content=issue_body) identifica a ferramenta que forneceu a descrição de uma issue. O Codex trata a descrição como saída da ferramenta e dá a ela prioridade menor que às instruções do usuário e do desenvolvedor. A mensagem pode iniciar um turno ou ser incorporada a um turno regular em andamento.

Retome uma conversa sem carregar o histórico

Passe include_turns=False para codex.thread_resume() ou codex.thread_fork() para que a resposta não inclua os turnos anteriores. O modelo continua com acesso ao contexto da conversa. Para recuperar o histórico depois, chame thread.read(include_turns=True).

Na versão 0.166.0 ou posterior da CLI do Codex, retome a conversa com o provedor de modelo registrado nela. Se você mudar de provedor, chame codex.thread_fork(thread_id) para continuar com o mesmo histórico no novo provedor.

Defina o nível de serviço para um turno

Para escolher o nível de serviço de um único turno novo, passe turn_service_tier para run() ou turn(). Por exemplo, turn_service_tier="default" usa a velocidade padrão nesse turno. Para mudar o nível de serviço desse turno e dos seguintes, passe service_tier. Entrar em um turno em andamento preserva o nível de serviço desse turno.

Se você usar seu próprio executável do Codex, precisará da versão 0.151.0 ou posterior da CLI do Codex para usar ExternalMessage, definir include_turns explicitamente ao retomar uma conversa ou criar um fork dela, ou usar turn_service_tier.

Configurações predefinidas de sandbox

Use as mesmas configurações predefinidas de Sandbox ao criar uma conversa ou ao alterar o acesso dela ao sistema de arquivos para um turno posterior:

1
2
3
4
5
6from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

Configurações disponíveis:

• Sandbox.read_only: Permite ler arquivos e bloqueia a gravação.
• Sandbox.workspace_write: Permite ler arquivos e gravar no espaço de trabalho e nos diretórios raiz configurados para gravação.
• Sandbox.full_access: Permite a execução sem restrições de acesso ao sistema de arquivos.

Quando você omite sandbox=, o App Server usa a configuração padrão definida para ele. A configuração de sandbox passada para run(...) ou turn(...) se aplica ao turno em questão e aos turnos seguintes da mesma conversa.

Para mais detalhes, consulte o repositório do SDK para Python.