SDK de Codex

Si usas Codex a través de Codex CLI, la extensión para IDE o Codex Cloud, también puedes controlarlo desde tu código.

Usa el SDK cuando necesites:

• controlar Codex como parte de tu pipeline de CI/CD
• crear tu propio agente que interactúe con Codex para realizar tareas complejas de ingeniería
• incorporar Codex a tus herramientas y flujos de trabajo internos
• integrar Codex en tu propia aplicación

Usa el SDK de Codex para automatizar tareas de programación, incluidos los trabajos de CI. Usa el App Server de Codex para crear clientes personalizados que gestionen la autenticación, el historial de conversaciones, las aprobaciones y los eventos que transmite el agente.

Se eliminaron el comando codex mcp-server y el binario independiente codex-mcp-server. Usa el App Server de Codex para tus integraciones existentes.

Si tienes acceso a la versión beta y necesitas analizar repositorios o cambios para obtener hallazgos de seguridad y datos de cobertura en formato estructurado, usa el SDK de Codex Security para TypeScript.

Biblioteca de TypeScript

La biblioteca de TypeScript permite que tu aplicación inicie, continúe y reanude hilos locales de Codex.

Usa la biblioteca en el servidor. Requiere Node.js 18 o una versión posterior.

Instalación

Para empezar, instala el SDK de Codex con npm:

npm install @openai/codex-sdk

Uso

Inicia un hilo con Codex y ejecútalo con tu prompt.

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

Vuelve a llamar a run() para continuar en el mismo hilo o proporciona el ID de un hilo anterior para reanudarlo.

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 los hilos que crea tu integración, define threadSource al crear cada hilo. Por ejemplo, codex.startThread({ threadSource: "ci" }) etiqueta el hilo como ci. Al reanudar un hilo, se conserva su origen.

Sobrescritura de la configuración

Pasa config para definir la configuración de Codex de forma estructurada. Para las claves que no se pueden expresar como rutas separadas por puntos, usa configOverrides para pasar cadenas TOML sin procesar como argumentos --config independientes:

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

Los valores que pasas como cadenas TOML tienen prioridad sobre la configuración estructurada de config. El SDK aplica después los ajustes administrados, como baseUrl, y las opciones específicas del hilo, por lo que estos tienen prioridad sobre ambas formas de configuración. Estas sobrescrituras no modifican tus archivos de configuración de Codex.

Para obtener más detalles, consulta el repositorio de TypeScript.

Biblioteca de Python

El SDK de Python controla el App Server local de Codex mediante JSON-RPC. Requiere Python 3.10 o una versión posterior. Las compilaciones publicadas del SDK incluyen una versión fija del entorno de ejecución de Codex CLI como dependencia.

Instalación

Para instalar el SDK, ejecuta:

pip install openai-codex

Las compilaciones publicadas del SDK usan automáticamente la versión del entorno de ejecución fijada para cada una. Pasa CodexConfig(codex_bin=...) solo cuando quieras usar un ejecutable local específico de Codex.

El SDK de Python está disponible en versión estable. pip install openai-codex instala la versión estable más reciente. Usa pip install --pre openai-codex si quieres instalar compilaciones preliminares más recientes.

Uso

Inicia Codex, crea un hilo y ejecuta un prompt. Los ejemplos usan GPT-6.1 Sol. Para usarlos con ese modelo, la cuenta con la que iniciaste sesión debe tener acceso a él. Si tu cuenta no tiene acceso, omite model para usar el modelo predeterminado que hayas configurado. Consulta la disponibilidad de GPT-6.1 Sol por plan.

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)

Usa AsyncCodex si tu aplicación ya es asíncrona:

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

Pasar contenido de otro sistema

Cuando una herramienta, una aplicación u otro agente proporcione contenido, pasa un ExternalMessage como única entrada a thread.run() o thread.turn(). Por ejemplo, ExternalMessage(tool_name="issue_tracker", content=issue_body) identifica la herramienta que proporcionó la descripción de una incidencia. Codex trata la descripción como salida de la herramienta y le asigna menor prioridad que a las instrucciones del usuario y del desarrollador. El mensaje puede iniciar un turno o incorporarse a un turno normal en curso.

Reanudar un hilo sin cargar su historial

Pasa include_turns=False a codex.thread_resume() o a codex.thread_fork() para omitir la carga de turnos anteriores en la respuesta. El modelo conserva el contexto del hilo. Para recuperar el historial más adelante, llama a thread.read(include_turns=True).

Si usas Codex CLI 0.166.0 o una versión posterior, reanuda el hilo con el proveedor de modelos guardado para ese hilo. Si cambias de proveedor, llama a codex.thread_fork(thread_id) para continuar con el mismo historial en el nuevo proveedor.

Configurar el nivel de servicio para un turno

Para elegir el nivel de servicio de un solo turno nuevo, pasa turn_service_tier a run() o a turn(). Por ejemplo, con turn_service_tier="default" ese turno se ejecuta a velocidad estándar. Para cambiar el nivel de servicio de ese turno y de los siguientes, pasa service_tier. Si te incorporas a un turno en curso, ese turno conserva su nivel de servicio.

Si proporcionas tu propio ejecutable de Codex, necesitas Codex CLI 0.151.0 o una versión posterior para usar ExternalMessage, pasar include_turns de forma explícita al reanudar un hilo o crear un fork, o usar turn_service_tier.

Configuraciones predefinidas del sandbox

Usa las mismas configuraciones predefinidas de Sandbox al crear un hilo o al cambiar su acceso al sistema de archivos para un 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)

Configuraciones predefinidas disponibles:

• Sandbox.read_only: permite el acceso de solo lectura a los archivos.
• Sandbox.workspace_write: permite leer archivos y escribir dentro del espacio de trabajo y de los directorios raíz configurados para escritura.
• Sandbox.full_access: permite la ejecución sin restricciones de acceso al sistema de archivos.

Si omites sandbox=, el App Server usa su configuración predeterminada. Si pasas un sandbox a run(...) o a turn(...), se aplica tanto a ese turno como a los siguientes turnos del hilo.

Para obtener más detalles, consulta el repositorio de Python.