Core API

Primary client and thread classes.

When to use this page

• You want docstrings for the main entry points: Codex, Thread, and async equivalents.

• You want the exact run / run_streamed signatures and return types.

class acodex.codex.Codex(**options)

Codex is the main class for interacting with the Codex agent.

Use start_thread() to start a new thread or resume_thread() to resume a previously started thread.

start_thread(**thread_options)

Start a new conversation with an agent.

Returns:

A new thread instance.

resume_thread(thread_id, **thread_options)

Resume a conversation with an agent using a thread ID.

Threads are persisted in ~/.codex/sessions.

Parameters:

thread_id – Identifier of the thread to resume.

Returns:

A new thread instance.

class acodex.codex.AsyncCodex(**options)

Codex is the main class for interacting with the Codex agent.

Use start_thread() to start a new thread or resume_thread() to resume a previously started thread.

start_thread(**thread_options)

Start a new conversation with an agent.

Returns:

A new thread instance.

resume_thread(thread_id, **options)

Resume a conversation with an agent using a thread ID.

Threads are persisted in ~/.codex/sessions.

Parameters:

thread_id – Identifier of the thread to resume.

Returns:

A new thread instance.

class acodex.thread.Thread(*, exec, options, thread_options, thread_id=None)

Represent a thread of conversation with the agent.

One thread can have multiple consecutive turns.

property id

Return the ID of the thread.

The ID is populated after the first turn starts.

run_streamed(input, output_type=None, **turn_options)

Provide input to the agent and stream turn events as they are produced.

Set turn_options[“signal”] via event.set() to request cancellation. Use threading.Event in synchronous flows.

Returns:

A streamed turn result with an iterator of parsed events.

run(input, output_type=None, **turn_options)

Provide input to the agent and return the completed turn.

Set turn_options[“signal”] via event.set() to request cancellation. Use threading.Event in synchronous flows.

Returns:

The completed turn with reduced items, final response, and usage.

class acodex.thread.AsyncThread(*, exec, options, thread_options, thread_id=None)

Represent a thread of conversation with the agent.

One thread can have multiple consecutive turns.

property id

Return the ID of the thread.

The ID is populated after the first turn starts.

async run_streamed(input, output_type=None, **turn_options)

Provide input to the agent and stream turn events as they are produced.

Set turn_options[“signal”] via event.set() to request cancellation. Use asyncio.Event in asynchronous flows.

Returns:

A streamed turn result with an async iterator of parsed events.

async run(input, output_type=None, **turn_options)

Provide input to the agent and return the completed turn.

Set turn_options[“signal”] via event.set() to request cancellation. Use asyncio.Event in asynchronous flows.

Returns:

The completed turn with reduced items, final response, and usage.

class acodex.types.turn.Turn(items, final_response, usage, structured_response_factory)

Completed turn.

This is the result returned by run().

property structured_response

Return the structured response.

class acodex.types.turn.RunStreamedResult(events, result_factory)

The synchronous result of run_streamed.

property result

Return the reduced turn after full stream exhaustion.

class acodex.types.turn.AsyncRunStreamedResult(events, result_factory)

The asynchronous result of run_streamed.

property result

Return the reduced turn after full stream exhaustion.