ClaudeAgentSDK.Transport behaviour (claude_agent_sdk v0.11.0)

Copy Markdown View Source

Behaviour describing the transport layer used to communicate with the Claude CLI.

A transport is responsible for starting and supervising the underlying connection, forwarding JSON control/data frames to the CLI, broadcasting replies to subscribers, and shutting down cleanly when the client stops.

Implementations should be OTP-friendly processes (typically a GenServer) that encapsulate any state required to maintain the connection.

Summary

Types

message()

Binary payload encoded as newline-terminated JSON.

opts()

Transport-specific options propagated from Client.start_link/1.

t()

Opaque transport reference returned from start_link/1.

Callbacks

close(t)

Closes the transport and releases any external resources.

end_input(t)

Signals end of input stream to the CLI process.

send(t, message)

Sends a JSON payload to the CLI.

start_link(opts)

Starts the transport process and establishes the CLI connection.

status(t)

Returns the current connection status for observability/health checks.

subscribe(t, pid)

Subscribes the given process to receive inbound messages.

Types

message()

@type message() :: binary()

Binary payload encoded as newline-terminated JSON.

opts()

@type opts() :: keyword()

Transport-specific options propagated from Client.start_link/1.

t()

@type t() :: pid()

Opaque transport reference returned from start_link/1.

Callbacks

close(t)

@callback close(t()) :: :ok

Closes the transport and releases any external resources.

end_input(t)

(optional) 
@callback end_input(t()) :: :ok | {:error, term()}

Signals end of input stream to the CLI process.

This closes stdin to indicate no more input will be sent. Required for non-streaming queries where the CLI waits for stdin to close before processing.

Implementation Notes

  • For Port-based transports: Close the stdin pipe
  • For erlexec-based transports: Send :eof signal
  • This callback is optional - transports may not support it

send(t, message)

@callback send(t(), message()) :: :ok | {:error, term()}

Sends a JSON payload to the CLI.

start_link(opts)

@callback start_link(opts()) :: {:ok, t()} | {:error, term()}

Starts the transport process and establishes the CLI connection.

status(t)

@callback status(t()) :: :connected | :disconnected | :error

Returns the current connection status for observability/health checks.

subscribe(t, pid)

@callback subscribe(t(), pid()) :: :ok

Subscribes the given process to receive inbound messages.