mirror of
https://github.com/openai/codex.git
synced 2026-05-20 03:05:02 +00:00
f0166cadbb
## Why
`TurnHandle.run()` returned the raw app-server `Turn`, whose live
start/completed payloads do not include loaded `items`, so users saw
empty `items` after starting a turn. That made the handle-based path
behave differently from `Thread.run(...)`, and pushed examples toward
persisted-thread reads plus helper extraction.
This PR makes the run APIs standalone: starting a turn and running it
returns collected turn data directly, or fails visibly when required
stream events are missing.
## What Changed
- Replaces the public `RunResult` export with `TurnResult`.
- Adds turn metadata to `TurnResult`: `id`, `status`, `error`,
`started_at`, `completed_at`, and `duration_ms`, alongside
`final_response`, `items`, and `usage`.
- Changes `TurnHandle.run()` and `AsyncTurnHandle.run()` to consume
stream events with the same collector used by `Thread.run(...)`.
- Exports `TurnError` from `openai_codex.types` for the new result
shape.
- Updates tests, examples, docs, and the walkthrough notebook to use
`result.final_response` and `result.items` directly.
- Removes persisted-thread helper paths and placeholder/skipped control
flows from the public examples and notebook.
## Verification
- `python3 -m py_compile ...` over changed SDK, example, and test Python
files.
- `python3 -c "import json;
json.load(open('sdk/python/notebooks/sdk_walkthrough.ipynb'))"`
- `git diff --check`
- `PYTHONPATH=sdk/python/src python3 -c ...` import/signature smoke for
`TurnResult`, `TurnHandle.run`, and `AsyncTurnHandle.run`.
91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
# FAQ
|
|
|
|
## Thread vs turn
|
|
|
|
- A `Thread` is conversation state.
|
|
- A `Turn` is one model execution inside that thread.
|
|
- Multi-turn chat means multiple turns on the same `Thread`.
|
|
|
|
## `run()` vs `stream()`
|
|
|
|
- `Thread.run(...)` starts a turn and returns `TurnResult`.
|
|
- `TurnHandle.run()` / `AsyncTurnHandle.run()` consumes events for an existing turn handle and returns the same `TurnResult` shape.
|
|
- `TurnHandle.stream()` / `AsyncTurnHandle.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
|
|
|
|
Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout logic, or custom parsing.
|
|
|
|
## Sync vs async clients
|
|
|
|
- `Codex` is the sync public API.
|
|
- `AsyncCodex` is an async replica of the same public API shape.
|
|
- Prefer `async with AsyncCodex()` for async code. It is the standard path for
|
|
explicit startup/shutdown, and `AsyncCodex` initializes lazily on context
|
|
entry or first awaited API use.
|
|
|
|
If your app is not already async, stay with `Codex`.
|
|
|
|
## How do I log in?
|
|
|
|
- `login_api_key(...)` authenticates immediately with an API key.
|
|
- `login_chatgpt()` starts browser login and returns a handle with `auth_url`.
|
|
- `login_chatgpt_device_code()` starts device-code login and returns a handle
|
|
with `verification_url` and `user_code`.
|
|
- Interactive handles expose `wait()` for the matching
|
|
`account/login/completed` notification and `cancel()` to stop that attempt.
|
|
- `account()` reads the current account state, and `logout()` clears it.
|
|
|
|
## Public kwargs are snake_case
|
|
|
|
Public API keyword names are snake_case. The SDK still maps them to wire camelCase under the hood.
|
|
|
|
If you are migrating older code, update these names:
|
|
|
|
- `approvalPolicy` -> `approval_policy`
|
|
- `baseInstructions` -> `base_instructions`
|
|
- `developerInstructions` -> `developer_instructions`
|
|
- `modelProvider` -> `model_provider`
|
|
- `modelProviders` -> `model_providers`
|
|
- `sortKey` -> `sort_key`
|
|
- `sourceKinds` -> `source_kinds`
|
|
- `outputSchema` -> `output_schema`
|
|
- `sandboxPolicy` -> `sandbox_policy`
|
|
|
|
## Why only `thread_start(...)` and `thread_resume(...)`?
|
|
|
|
The public API keeps only explicit lifecycle calls:
|
|
|
|
- `thread_start(...)` to create new threads
|
|
- `thread_resume(thread_id, ...)` to continue existing threads
|
|
|
|
This avoids duplicate ways to do the same operation and keeps behavior explicit.
|
|
|
|
## Why does constructor fail?
|
|
|
|
`Codex()` is eager: it starts transport and calls `initialize` in `__init__`.
|
|
|
|
Common causes:
|
|
|
|
- published runtime package (`openai-codex-cli-bin`) is not installed
|
|
- local `codex_bin` override points to a missing file
|
|
- app-server version older than the SDK schema
|
|
|
|
## Why does a turn "hang"?
|
|
|
|
A turn is complete only when `turn/completed` arrives for that turn ID.
|
|
|
|
- `run()` waits for this automatically.
|
|
- With `stream()`, keep consuming notifications until completion.
|
|
|
|
## How do I retry safely?
|
|
|
|
Use `retry_on_overload(...)` for transient overload failures (`ServerBusyError`).
|
|
|
|
Do not blindly retry all errors. For `InvalidParamsError` or `MethodNotFoundError`, fix inputs or update the runtime/schema version instead.
|
|
|
|
## Common pitfalls
|
|
|
|
- Starting a new thread for every prompt when you wanted continuity.
|
|
- Forgetting to `close()` (or not using context managers).
|
|
- Reading `Turn.items` from live start/completed payloads instead of using `TurnResult.items`.
|
|
- Mixing SDK input classes with raw dicts incorrectly.
|