Struct AsyncClient 

pub struct AsyncClient { /* private fields */ }

Asynchronous multi-turn client for the Codex app-server.

Communicates with a long-lived codex app-server process via newline-delimited JSON-RPC over stdio. Manages request/response correlation and buffers incoming notifications that arrive while waiting for RPC responses.

The client automatically kills the app-server process when dropped.

Implementations

impl AsyncClient

pub fn new(child: Child) -> Result<Self>

Create a client from an existing Tokio child process.

The child’s stdin, stdout, and stderr must all be piped. This does not perform the app-server initialize handshake or a Codex version check. Use AppServerBuilder::build_command to retain the SDK’s command-line and stdio configuration while customizing how the process is spawned.

pub async fn start() -> Result<Self>

Start an app-server with default settings.

Spawns codex app-server --listen stdio://, performs the required initialize handshake, and returns a connected client ready for thread_start().

Errors

Returns an error if the codex CLI is not installed, the version is incompatible, the process fails to start, or the initialization handshake fails.

pub async fn start_with(builder: AppServerBuilder) -> Result<Self>

Start an app-server with a custom AppServerBuilder.

Performs the required initialize handshake before returning. Use this to configure the binary path, working directory, environment, or CLI arguments.

Errors

Returns an error if the process fails to start, stdio pipes cannot be established, or the initialization handshake fails.

pub async fn spawn(builder: AppServerBuilder) -> Result<Self>

Spawn an app-server without performing the initialize handshake.

Use this if you need to send a custom InitializeParams (e.g., with specific capabilities). You must call AsyncClient::initialize before any other requests.

pub async fn request<P: Serialize, R: DeserializeOwned>( &mut self, method: &str, params: &P, ) -> Result<R>

Send a JSON-RPC request and wait for the matching response.

Any notifications or server requests that arrive before the response are buffered and can be retrieved via AsyncClient::next_message.

Errors

• Error::JsonRpc if the server returns a JSON-RPC error
• Error::ServerClosed if the connection drops before a response arrives
• Error::Json if response deserialization fails

pub async fn thread_start( &mut self, params: &ThreadStartParams, ) -> Result<ThreadStartResponse>

Start a new thread (conversation session).

A thread must be created before any turns can be started. The returned ThreadStartResponse contains the thread_id needed for subsequent calls.

pub async fn thread_resume( &mut self, params: &ThreadResumeParams, ) -> Result<ThreadResumeResponse>

Resume a previously persisted thread by id.

Replays the thread’s history so turns can continue where they left off.

pub async fn thread_fork( &mut self, params: &ThreadForkParams, ) -> Result<ThreadForkResponse>

Fork an existing thread into a new independent thread.

pub async fn turn_start( &mut self, params: &TurnStartParams, ) -> Result<TurnStartResponse>

Start a new turn within a thread.

Sends user input to the agent. After calling this, use AsyncClient::next_message to stream notifications until turn/completed arrives.

pub async fn turn_interrupt( &mut self, params: &TurnInterruptParams, ) -> Result<TurnInterruptResponse>

Interrupt an active turn.

pub async fn thread_archive( &mut self, params: &ThreadArchiveParams, ) -> Result<ThreadArchiveResponse>

Archive a thread.

pub async fn thread_delete( &mut self, params: &ThreadDeleteParams, ) -> Result<ThreadDeleteResponse>

Delete a thread.

pub async fn initialize( &mut self, params: &InitializeParams, ) -> Result<InitializeResponse>

Perform the initialize handshake with the app-server.

Sends initialize with the given params and then sends the initialized notification. This must be the first request after spawning the process.

pub async fn respond<R: Serialize>( &mut self, id: RequestId, result: &R, ) -> Result<()>

Respond to a server-to-client request (e.g., approval flow).

When the server sends a ServerMessage::Request, it expects a response. Use this method with the request’s id and a result payload. For command approval, pass a CommandExecutionApprovalResponse. For file change approval, pass a FileChangeApprovalResponse.

pub async fn respond_error( &mut self, id: RequestId, code: i64, message: &str, ) -> Result<()>

Respond to a server-to-client request with an error.

pub async fn next_message(&mut self) -> Result<Option<ServerMessage>>

Read the next incoming server message (notification or server request).

Returns buffered messages first (from notifications that arrived during an AsyncClient::request call), then reads from the wire.

Returns Ok(None) when the app-server closes the connection (EOF).

Typical notification methods

Method	Meaning
turn/started	Agent began processing
item/agentMessage/delta	Streaming text chunk
item/commandExecution/outputDelta	Command output chunk
item/started / item/completed	Item lifecycle
turn/completed	Agent finished the turn
error	Server-side error

pub fn events(&mut self) -> EventStream<'_>

Return an async event stream over ServerMessages.

Wraps AsyncClient::next_message in a stream-like API. Call EventStream::next in a loop, or EventStream::collect to gather all messages until EOF.

pub fn pid(&self) -> Option<u32>

Get the process ID.

pub fn is_alive(&mut self) -> bool

Check if the child process is still running.

pub async fn shutdown(self) -> Result<()>

Shut down the app-server process.

Consumes the client. If you don’t call this explicitly, the Drop implementation will kill the process automatically.

Trait Implementations

impl Drop for AsyncClient

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.