openai/codex
1
0
Fork 0
mirror of https://github.com/openai/codex.git synced 2026-09-13 11:47:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

[4/6] Expose dedicated Python goal operations

Browse Source
This commit is contained in:
Ahmed Ibrahim
2026-06-09 16:14:46 -07:00
parent 206478d338
commit a0de197076
8 changed files with 549 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
sdk/python/docs/api-reference.md
View File

@@ -152,6 +152,8 @@ attempt. API-key login completes synchronously and does not return a handle.
- `run(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> TurnResult`
- `turn(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> TurnHandle`
- `run_goal(objective: str) -> TurnResult`
- `start_goal(objective: str) -> TurnHandle`
- `read(*, include_turns: bool = False) -> ThreadReadResponse`
- `set_name(name: str) -> ThreadSetNameResponse`
- `compact() -> ThreadCompactStartResponse`
@@ -160,6 +162,8 @@ attempt. API-key login completes synchronously and does not return a handle.
- `run(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> Awaitable[TurnResult]`
- `turn(input: str | Input, *, approval_mode=None, cwd=None, effort=None, model=None, output_schema=None, personality=None, sandbox: Sandbox | None = None, service_tier=None, summary=None) -> Awaitable[AsyncTurnHandle]`
- `run_goal(objective: str) -> Awaitable[TurnResult]`
- `start_goal(objective: str) -> Awaitable[AsyncTurnHandle]`
- `read(*, include_turns: bool = False) -> Awaitable[ThreadReadResponse]`
- `set_name(name: str) -> Awaitable[ThreadSetNameResponse]`
- `compact() -> Awaitable[ThreadCompactStartResponse]`
@@ -184,6 +188,15 @@ phase-less assistant message item.
Use `turn(...)` when you need low-level turn control (`stream()`, `steer()`,
`interrupt()`) before collecting the turn result.
Use `run_goal(...)` or `start_goal(...)` for an objective that can continue
through multiple internal turns. Goal operations require an idle, persisted
thread and use its existing configuration. Starting one replaces any stored
goal. Streaming, steering, interruption, and the returned `TurnResult` still
present one logical turn with one stable ID.
Closing a goal stream releases its SDK routing state. It does not pause the
persisted goal or stop work already running on the server.
## Sandbox
Use `sandbox=` consistently on thread lifecycle methods and turns:

11
sdk/python/docs/getting-started.md
View File

@@ -72,6 +72,17 @@ with Codex() as codex:
Use `Thread.turn(...)` when you need a `TurnHandle` for streaming, steering,
or interrupting an active turn.
For a longer objective on an idle, persisted thread, run a dedicated goal
operation:
```python
result = thread.run_goal("Improve the benchmark coverage in this repository.")
```
A goal may continue working internally, but it streams and returns as one
logical turn. It uses the thread's existing configuration and replaces any
stored goal.
## 4. Choose Sandbox Access
Use one enum for the initial thread and later turn overrides: