Skip to main content
The prompt WebSocket lets you send prompts to the coding agent and receive streaming output - tokens, tool calls, results, and completion signals - in real time.

Connection

Obtain ws_token from the Token Exchange endpoint with capability: "prompt". Required scope: sessions:prompt Each prompt tab has its own WebSocket. The tab_id identifies which agent tab to connect to - sessions can run multiple agents in parallel across tabs.

Authentication

The token query parameter authenticates the connection. Invalid or expired tokens result in an immediate close with code 4001.

Sending a prompt

Send a JSON message to start a prompt:

Receiving output

The server streams output as a sequence of JSON messages:

token

A chunk of the agent’s text response:

tool_use

The agent is invoking a tool (e.g. editing a file, running a command):

tool_result

The result of a tool invocation:

prompt_end

The agent has finished responding:

error

An error occurred during prompt execution:

Cancelling a prompt

Send a cancel message to stop the agent mid-response:
The server sends a final prompt_end message after cancellation.

Example: streaming output

Tab scoping

Each tab operates independently. You can open multiple WebSocket connections to different tabs to run parallel agents. Tab IDs are returned when listing session workspace state via the REST API.