WebSocket API

Xagent exposes WebSocket endpoints for real-time task execution and monitoring — streaming trace events, chat responses, and status updates as a task runs.

Base URL

ws://localhost:8000       # self-hosted
wss://your-domain.com     # over HTTPS

Authentication

Connections authenticate with a token passed as a query parameter:

const ws = new WebSocket(
  `ws://localhost:8000/ws/chat/${taskId}?token=${token}`
);
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  handleEvent(data);
};

Chat Endpoint

ws://localhost:8000/ws/chat/{task_id} — real-time communication for one task: execution, status, and manual intervention. A second endpoint, ws://localhost:8000/ws/build/preview, streams agent previews on the Build page without persisting anything.

Client Messages

Messages you send to the server, each with a type:

{ "type": "chat", "message": "Your question here" }
{ "type": "execute_task", "query": "Task description" }
{ "type": "intervention", "step_id": "step_123", "action": "approve" }
{ "type": "pause_task" }
{ "type": "resume_task" }
{ "type": "status_request" }

Server Events

Messages the server streams back. Trace events carry the fine-grained execution timeline; other types carry chat, status, and errors:

{ "type": "chat", "message": "Agent response", "step_id": "step_123" }
{ "type": "status", "status": "running", "progress": 0.5 }
{ "type": "error", "message": "Error description" }

Trace events use a richer shape — see the Trace Events reference for the full catalogue.

Error Codes

Next Steps

• Trace Events →
• Chat / Tasks API →
• Task Execution →