SDK Codex

Si vous utilisez Codex via Codex CLI, l’extension pour IDE ou Codex Cloud, vous pouvez aussi le piloter par programmation.

Utilisez le SDK pour :

• Piloter Codex depuis votre pipeline CI/CD
• Créer votre propre agent capable de collaborer avec Codex pour réaliser des tâches d’ingénierie complexes
• Intégrer Codex à vos outils internes et à vos workflows
• Intégrer Codex à votre propre application

Utilisez le SDK Codex pour automatiser des tâches de développement, y compris celles de votre pipeline CI. Utilisez l’App Server de Codex pour créer des clients personnalisés qui gèrent l’authentification, l’historique des conversations, les approbations et les événements que l’agent transmet en continu.

La commande codex mcp-server et le binaire autonome codex-mcp-server ont été supprimés. Pour vos intégrations existantes, utilisez l’App Server de Codex.

Si vous avez accès à la bêta et que vous devez analyser des dépôts ou des modifications pour obtenir des résultats de sécurité structurés et connaître la couverture de l’analyse, utilisez le SDK TypeScript de Codex Security.

Bibliothèque TypeScript

La bibliothèque TypeScript permet à votre application de créer des fils de discussion Codex en local, de les poursuivre et de les reprendre.

Utilisez la bibliothèque côté serveur. Elle nécessite Node.js 18 ou une version ultérieure.

Installation

Pour commencer, installez le SDK Codex avec npm :

npm install @openai/codex-sdk

Utilisation

Démarrez un fil de discussion avec Codex et envoyez-lui votre 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);

Appelez de nouveau run() pour poursuivre le même fil, ou indiquez l’identifiant d’un fil précédent pour le reprendre.

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

Pour identifier les fils créés par votre intégration, définissez threadSource à la création de chaque fil. Par exemple, codex.startThread({ threadSource: "ci" }) attribue au fil l’étiquette ci. Lorsque vous reprenez un fil, il conserve sa source d’origine.

Remplacement des valeurs de configuration

Passez une configuration structurée à Codex via config. Pour les clés que vous ne pouvez pas exprimer sous forme de chemins séparés par des points, utilisez configOverrides pour passer chaque chaîne TOML brute dans un argument --config distinct :

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

Les valeurs TOML brutes ont priorité sur celles de config. Le SDK applique ensuite les paramètres qu’il gère, comme baseUrl, ainsi que les options propres au fil. Ces paramètres et options ont donc priorité sur les deux formes de configuration. Ces remplacements ne modifient pas vos fichiers de configuration Codex.

Pour en savoir plus, consultez le dépôt du SDK TypeScript.

Bibliothèque Python

Le SDK Python pilote l’App Server local de Codex via JSON-RPC. Il nécessite Python 3.10 ou une version ultérieure. Chaque version publiée du SDK dépend d’une version précise de l’environnement d’exécution de Codex CLI.

Installation

Pour installer le SDK, exécutez la commande suivante :

pip install openai-codex

Chaque version publiée du SDK utilise automatiquement la version de l’environnement d’exécution prévue pour elle. Passez CodexConfig(codex_bin=...) uniquement si vous souhaitez utiliser un exécutable Codex local précis.

Le SDK Python est disponible en version stable. La commande pip install openai-codex installe la dernière version stable. Utilisez pip install --pre openai-codex pour installer une préversion plus récente.

Utilisation

Démarrez Codex, créez un fil de discussion et envoyez un prompt. Les exemples utilisent GPT-6.1 Sol. Pour les exécuter tels quels, le compte avec lequel vous êtes connecté doit avoir accès à ce modèle. Sinon, omettez model pour utiliser le modèle configuré par défaut. Consultez la disponibilité de GPT-6.1 Sol selon l’abonnement.

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)

Utilisez AsyncCodex si votre application est déjà asynchrone :

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

Transmettre du contenu provenant d’un autre système

Lorsqu’un outil, une application ou un autre agent fournit du contenu, passez un objet ExternalMessage comme seule entrée à thread.run() ou à thread.turn(). Par exemple, ExternalMessage(tool_name="issue_tracker", content=issue_body) identifie l’outil qui a fourni la description d’un ticket. Codex traite cette description comme une sortie d’outil et lui accorde une priorité inférieure à celle des instructions de l’utilisateur et du développeur. Le message peut démarrer un échange ou rejoindre un échange standard en cours.

Reprendre un fil sans charger son historique

Passez include_turns=False à codex.thread_resume() ou à codex.thread_fork() pour exclure les échanges précédents de la réponse. Le modèle conserve le contexte du fil. Pour récupérer l’historique ultérieurement, appelez thread.read(include_turns=True).

Avec Codex CLI 0.166.0 ou une version ultérieure, utilisez le fournisseur de modèles enregistré pour le fil afin de reprendre ce fil. Si vous changez de fournisseur, appelez codex.thread_fork(thread_id) pour poursuivre avec le même historique chez le nouveau fournisseur.

Définir l’offre pour un seul échange

Pour choisir l’offre d’un seul nouvel échange, passez turn_service_tier à run() ou à turn(). Par exemple, turn_service_tier="default" sélectionne la vitesse standard pour cet échange. Pour modifier l’offre de cet échange et des suivants, passez service_tier. Si vous rejoignez un échange en cours, il conserve son offre.

Si vous fournissez votre propre exécutable Codex, utilisez Codex CLI 0.151.0 ou une version ultérieure pour utiliser ExternalMessage, passer explicitement include_turns lorsque vous reprenez ou forkez un fil, ou utiliser turn_service_tier.

Profils prédéfinis du bac à sable

Utilisez les mêmes profils Sandbox pour créer un fil ou modifier ses droits d’accès au système de fichiers lors d’un échange ultérieur :

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)

Profils disponibles :

• Sandbox.read_only : accès aux fichiers en lecture seule.
• Sandbox.workspace_write : lecture des fichiers et écriture dans l’espace de travail et les répertoires racines configurés pour autoriser l’écriture.
• Sandbox.full_access : exécution sans restriction d’accès au système de fichiers.

Si vous omettez sandbox=, l’App Server utilise le profil configuré par défaut. Le profil de bac à sable passé à run(...) ou à turn(...) s’applique à l’échange en cours et aux échanges suivants du même fil.

Pour en savoir plus, consultez le dépôt du SDK Python.