SDK do Codex

Se você usa o Codex por meio da CLI do Codex, da extensão para IDE ou do 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 para interagir com o Codex e executar tarefas complexas de engenharia
• Incorporar o Codex às suas ferramentas internas e aos seus fluxos de trabalho
• Integrar o Codex ao seu próprio aplicativo

Use o SDK do Codex para threads do Codex voltadas à programação. Se o Codex for um dos especialistas em um fluxo de trabalho orquestrado mais amplo, execute a CLI do Codex como um servidor MCP e orquestre-a com o SDK de Agentes.

Se você tiver acesso à versão beta e precisar de varreduras de repositórios ou alterações com achados estruturados de segurança e cobertura, use o SDK de TypeScript do Codex Security.

Biblioteca TypeScript

A biblioteca TypeScript permite que seu aplicativo inicie, continue e retome threads locais do Codex.

Use a biblioteca no lado do servidor; ela requer Node.js 18 ou uma versão posterior.

Instalação

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

npm install @openai/codex-sdk

Uso

Inicie uma thread com o Codex e execute-a com seu prompt.

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 thread ou retome uma thread anterior fornecendo o ID dela.

// 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);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

Para saber mais, consulte o repositório do TypeScript.

Biblioteca Python

O SDK para Python controla o app-server local do Codex via JSON-RPC. Ele requer Python 3.10 ou uma versão posterior. As builds publicadas do SDK incluem como dependência uma versão fixada do runtime da CLI do Codex.

Instalação

Para instalar o SDK, execute:

pip install openai-codex

As builds publicadas do SDK usam automaticamente o runtime fixado correspondente. Passe CodexConfig(codex_bin=...) apenas quando quiser usar deliberadamente um executável local específico do Codex.

O SDK para Python está disponível em uma versão estável. pip install openai-codex instala a versão estável mais recente. Use pip install --pre openai-codex para optar por builds de pré-lançamento mais recentes.

Uso

Inicie o Codex, crie uma thread e execute um prompt:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.6-terra",
        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:

from openai_codex import AsyncCodex


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


asyncio.run(main())

Predefinições de Sandbox

Use as mesmas predefinições de Sandbox ao criar uma thread ou alterar o acesso dela ao sistema de arquivos em um turno posterior:

from 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)

Predefinições disponíveis:

• Sandbox.read_only: Ler arquivos sem permitir gravações.
• Sandbox.workspace_write: Ler arquivos e gravar no workspace e nas raízes graváveis configuradas.
• Sandbox.full_access: Executar sem restrições de acesso ao sistema de arquivos.

Quando você omite sandbox=, o app-server usa o valor padrão configurado. Um sandbox passado para run(...) ou turn(...) aplica-se a esse turno e aos turnos posteriores da thread.

Para saber mais, consulte o repositório do Python.