Types

Events, items, inputs, and options payloads.

When to use this page

• You want to inspect event/item dataclasses emitted by streaming.

• You want the exact option keys available in CodexOptions, ThreadOptions, and TurnOptions.

class acodex.types.input.UserInputText(text)

A text input to send to the agent.

class acodex.types.input.UserInputLocalImage(path)

A local image input to send to the agent.

class acodex.types.events.ThreadStartedEvent(thread_id)

Emitted when a new thread is started as the first event.

thread_id

Identifier of the new thread. This can be used to resume the thread later.

type

Discriminator with value "thread.started".

class acodex.types.events.TurnStartedEvent

Emitted when a turn is started by sending a new prompt to the model.

A turn encompasses all events that happen while the agent is processing the prompt.

type

Discriminator with value "turn.started".

class acodex.types.events.Usage(input_tokens, cached_input_tokens, output_tokens)

Describes token usage for a completed turn.

input_tokens

Number of input tokens used during the turn.

cached_input_tokens

Number of cached input tokens used during the turn.

output_tokens

Number of output tokens used during the turn.

class acodex.types.events.TurnCompletedEvent(usage)

Emitted when a turn is completed.

This is typically emitted right after the assistant response.

usage

Token usage for the completed turn.

type

Discriminator with value "turn.completed".

class acodex.types.events.ThreadError(message)

Fatal error payload for a failed turn.

message

Error message describing the failure.

class acodex.types.events.TurnFailedEvent(error)

Indicates that a turn failed with an error.

error

Fatal error payload for the failed turn.

type

Discriminator with value "turn.failed".

class acodex.types.events.ItemStartedEvent(item)

Emitted when a new item is added to the thread.

Typically, the item is initially in progress.

item

Thread item payload that was started.

type

Discriminator with value "item.started".

class acodex.types.events.ItemUpdatedEvent(item)

Emitted when an item is updated.

item

Updated thread item payload.

type

Discriminator with value "item.updated".

class acodex.types.events.ItemCompletedEvent(item)

Signals that an item has reached a terminal state.

The terminal state may be success or failure depending on the item payload.

item

Thread item payload in a terminal state.

type

Discriminator with value "item.completed".

class acodex.types.events.ThreadErrorEvent(message)

Represents an unrecoverable error emitted directly by the event stream.

message

Error message emitted by the stream.

type

Discriminator with value "error".

class acodex.types.items.CommandExecutionItem(id, command, aggregated_output, status, exit_code=None)

A command executed by the agent.

id

Stable identifier for this thread item.

command

Command line executed by the agent.

aggregated_output

Aggregated stdout and stderr captured while the command was running.

status

Current status of the command execution.

exit_code

Exit code once the command exits; None while still running.

type

Discriminator with value "command_execution".

class acodex.types.items.FileUpdateChange(path, kind)

A file update included in a patch operation.

path

Path to the changed file.

kind

Kind of patch change (add, delete, or update).

class acodex.types.items.FileChangeItem(id, changes, status)

A set of file changes by the agent.

Emitted once the patch succeeds or fails.

id

Stable identifier for this thread item.

changes

Individual file changes that comprise the patch.

status

Whether the patch ultimately succeeded or failed.

type

Discriminator with value "file_change".

class acodex.types.items.McpToolCallResult(content, structured_content)

Result payload returned by an MCP server.

content

MCP content blocks returned for successful calls.

structured_content

Structured payload returned by the MCP server.

class acodex.types.items.McpToolCallError(message)

Error payload returned for a failed MCP call.

message

Error message reported by the MCP server.

class acodex.types.items.McpToolCallItem(id, server, tool, arguments, status, result=None, error=None)

Represents a call to an MCP tool.

The item starts when invocation is dispatched and completes when the MCP server reports success or failure.

id

Stable identifier for this thread item.

server

Name of the MCP server handling the request.

tool

Tool invoked on the MCP server.

arguments

Arguments forwarded to the tool invocation.

status

Current status of the tool invocation.

result

Result payload for successful calls; None when not available.

error

Error payload for failed calls; None when not available.

type

Discriminator with value "mcp_tool_call".

class acodex.types.items.AgentMessageItem(id, text)

Response from the agent.

The text can be natural language or JSON when structured output is requested.

id

Stable identifier for this thread item.

text

Agent response payload.

type

Discriminator with value "agent_message".

class acodex.types.items.ReasoningItem(id, text)

Agent reasoning summary.

id

Stable identifier for this thread item.

text

Reasoning summary text.

type

Discriminator with value "reasoning".

class acodex.types.items.WebSearchItem(id, query)

Captures a web search request.

The item completes when results are returned to the agent.

id

Stable identifier for this thread item.

query

Search query text.

type

Discriminator with value "web_search".

class acodex.types.items.ErrorItem(id, message)

Describes a non-fatal error surfaced as an item.

id

Stable identifier for this thread item.

message

Error message.

type

Discriminator with value "error".

class acodex.types.items.TodoItem(text, completed)

An item in the agent to-do list.

text

To-do item text.

completed

Whether the item is completed.

class acodex.types.items.TodoListItem(id, items)

Tracks the agent running to-do list.

Starts when a plan is issued, updates as steps change, and completes when the turn ends.

id

Stable identifier for this thread item.

items

Current to-do list items.

type

Discriminator with value "todo_list".

class acodex.types.codex_options.CodexOptions

Options used to construct a Codex client.

codex_path_override

Optional path to the Codex executable.

base_url

Optional base URL used by Codex API calls.

api_key

Optional API key used by Codex API calls.

config

Additional --config key=value overrides passed to Codex CLI.

Provide a JSON-like object and the SDK will flatten dotted paths and serialize values as TOML literals for CLI compatibility.

env

Environment variables passed to the Codex CLI process.

When provided, the SDK does not inherit from the current process environment.

class acodex.types.thread_options.ThreadOptions

Thread-level options applied to each turn.

model

Model name override.

sandbox_mode

Sandbox mode for command execution.

working_directory

Working directory used for the turn.

skip_git_repo_check

Whether to skip repository checks.

model_reasoning_effort

Requested model reasoning effort.

network_access_enabled

Whether network access is enabled in sandboxed execution.

web_search_mode

Web search mode configuration.

web_search_enabled

Legacy web search enable/disable flag.

approval_policy

Approval policy for tool and command execution.

additional_directories

Additional directories to add to the execution workspace.

class acodex.types.turn_options.TurnOptions

Options for a single turn.

Set the event (event.set()) to request cancellation. Use threading.Event for synchronous flows and asyncio.Event for asynchronous flows.