mirror of
https://github.com/openai/codex.git
synced 2026-05-01 03:42:05 +03:00
130 lines
3.8 KiB
Markdown
130 lines
3.8 KiB
Markdown
# Codex SDK for Python
|
|
|
|
Embed the Codex agent in Python workflows by spawning the Codex CLI and consuming structured events.
|
|
|
|
The SDK launches the bundled `codex` binary (or a custom path) and exchanges JSONL events over stdin/stdout.
|
|
|
|
## Installation
|
|
|
|
Until packages are published, install locally in editable mode:
|
|
|
|
```
|
|
pip install -e .
|
|
```
|
|
|
|
Requires Python 3.9+ and a Codex binary reachable either via the packaged vendor path or `codex_path_override`.
|
|
|
|
## Quickstart
|
|
|
|
```python
|
|
from codex_sdk import Codex
|
|
|
|
codex = Codex()
|
|
thread = codex.start_thread()
|
|
turn = thread.run("Diagnose the test failure and propose a fix")
|
|
|
|
print(turn.final_response)
|
|
print(turn.items)
|
|
```
|
|
|
|
Call `run()` again on the same `Thread` to continue the conversation.
|
|
|
|
```python
|
|
next_turn = thread.run("Implement the fix")
|
|
```
|
|
|
|
## Streaming responses
|
|
|
|
`run()` buffers events. To react to intermediate progress—tool calls, streamed responses, and file change notifications—use `run_streamed()` instead. It returns a generator of structured events.
|
|
|
|
```python
|
|
from codex_sdk import ThreadEvent
|
|
|
|
stream = thread.run_streamed("Diagnose the test failure and propose a fix")
|
|
|
|
for event in stream.events:
|
|
if event.type == "item.completed":
|
|
print("item", event.item)
|
|
elif event.type == "turn.completed":
|
|
print("usage", event.usage)
|
|
```
|
|
|
|
## Structured output
|
|
|
|
Provide a JSON schema per turn to receive structured assistant responses.
|
|
|
|
```python
|
|
schema = {
|
|
"type": "object",
|
|
"properties": {
|
|
"summary": {"type": "string"},
|
|
"status": {"type": "string", "enum": ["ok", "action_required"]},
|
|
},
|
|
"required": ["summary", "status"],
|
|
"additionalProperties": False,
|
|
}
|
|
|
|
from codex_sdk import TurnOptions
|
|
|
|
turn = thread.run("Summarize repository status", TurnOptions(output_schema=schema))
|
|
print(turn.final_response)
|
|
```
|
|
|
|
## Attaching images
|
|
|
|
Pass structured input entries when including images alongside text. Text entries are concatenated into the prompt; image entries are forwarded to the Codex CLI via `--image`.
|
|
|
|
```python
|
|
turn = thread.run([
|
|
{"type": "text", "text": "Describe these screenshots"},
|
|
{"type": "local_image", "path": "./ui.png"},
|
|
{"type": "local_image", "path": "./diagram.jpg"},
|
|
])
|
|
```
|
|
|
|
## Resuming an existing thread
|
|
|
|
Threads persist in `~/.codex/sessions`. If you lose the in-memory `Thread`, reconstruct it with `resume_thread()` and keep going.
|
|
|
|
```python
|
|
import os
|
|
|
|
saved_thread_id = os.environ["CODEX_THREAD_ID"]
|
|
thread = codex.resume_thread(saved_thread_id)
|
|
thread.run("Implement the fix")
|
|
```
|
|
|
|
## Working directory controls
|
|
|
|
Codex runs in the current working directory by default. To bypass the Git repository check for temporary directories, pass `skip_git_repo_check=True` when creating a thread.
|
|
|
|
```python
|
|
from codex_sdk import ThreadOptions
|
|
|
|
thread = codex.start_thread(ThreadOptions(working_directory="/path/to/project", skip_git_repo_check=True))
|
|
```
|
|
|
|
## Controlling the Codex CLI environment
|
|
|
|
By default, the CLI inherits `os.environ`. Override it when you need a sandboxed environment and the SDK will inject required variables (`OPENAI_BASE_URL`, `CODEX_API_KEY`, and the SDK originator marker).
|
|
|
|
```python
|
|
from codex_sdk import CodexOptions
|
|
|
|
codex = Codex(CodexOptions(env={"PATH": "/usr/local/bin"}))
|
|
```
|
|
|
|
## Options reference
|
|
|
|
- `CodexOptions`: `codex_path_override`, `base_url`, `api_key`, `env`
|
|
- `ThreadOptions`: `model`, `sandbox_mode`, `working_directory`, `skip_git_repo_check`, `model_reasoning_effort`, `network_access_enabled`, `web_search_enabled`, `approval_policy`, `additional_directories`
|
|
- `TurnOptions`: `output_schema`, `cancellation_event`
|
|
|
|
## Running tests
|
|
|
|
```
|
|
python -m unittest discover -v
|
|
```
|
|
|
|
Set `codex_path_override` if the bundled binary is unavailable; the test suite expects a Codex binary and will exercise a local HTTP proxy to avoid external calls.
|