WebSocket API

Real-time communication for live updates and agent interaction.

Connection

URL

wss://your-domain.com/agent/{agentId}

JavaScript Example

const ws = new WebSocket('wss://your-domain.com/agent/my-agent')

ws.onopen = () => {
  console.log('Connected')
}

ws.onmessage = (event) => {
  const message = JSON.parse(event.data)
  handleMessage(message)
}

ws.onclose = () => {
  console.log('Disconnected')
}

ws.onerror = (error) => {
  console.error('WebSocket error:', error)
}

Message Format

Incoming Messages

{
  "type": "state:update",
  "data": {
    "connectedClients": 5,
    "pendingSchedules": []
  },
  "timestamp": 1702648800000
}

Outgoing Messages

{
  "type": "action",
  "action": "subscribe",
  "data": {
    "events": ["workflow:status", "message:received"]
  }
}

Message Types

State Updates

{
  "type": "state:update",
  "data": {
    "config": {
      "name": "my-agent",
      "model": "@cf/meta/llama-3.1-8b-instruct"
    },
    "connectedClients": 3,
    "mcpServers": [],
    "pendingSchedules": []
  }
}

Client Connected

{
  "type": "client:connected",
  "data": {
    "count": 5,
    "clientId": "client-123"
  }
}

Client Disconnected

{
  "type": "client:disconnected",
  "data": {
    "count": 4,
    "clientId": "client-123"
  }
}

Workflow Status

{
  "type": "workflow:status",
  "data": {
    "workflowId": "workflow-123",
    "executionId": "exec-456",
    "status": "running",
    "currentNode": "email-1"
  }
}

Workflow Complete

{
  "type": "workflow:complete",
  "data": {
    "workflowId": "workflow-123",
    "executionId": "exec-456",
    "status": "complete",
    "result": {...}
  }
}

Schedule Executed

{
  "type": "schedule:executed",
  "data": {
    "scheduleId": "schedule-123",
    "result": "success",
    "nextRun": "2024-12-16T09:00:00Z"
  }
}

Message Received

{
  "type": "message:received",
  "data": {
    "id": 123,
    "role": "user",
    "content": "Hello!",
    "conversationId": "conv-456"
  }
}

Browser Action

{
  "type": "browser:action",
  "data": {
    "sessionId": "session-123",
    "action": "navigate",
    "status": "complete"
  }
}

Error

{
  "type": "error",
  "data": {
    "code": "RATE_LIMITED",
    "message": "Too many messages"
  }
}

Client Actions

Subscribe to Events

{
  "type": "subscribe",
  "events": ["workflow:status", "message:received"]
}

Unsubscribe

{
  "type": "unsubscribe",
  "events": ["workflow:status"]
}

Ping

{
  "type": "ping"
}

Response:

{
  "type": "pong",
  "timestamp": 1702648800000
}

Request State

{
  "type": "state:request"
}

Connection Handling

Reconnection

class WebSocketClient {
  constructor(url) {
    this.url = url
    this.reconnectDelay = 1000
    this.maxReconnectDelay = 30000
  }

  connect() {
    this.ws = new WebSocket(this.url)

    this.ws.onopen = () => {
      this.reconnectDelay = 1000
    }

    this.ws.onclose = () => {
      setTimeout(() => this.connect(), this.reconnectDelay)
      this.reconnectDelay = Math.min(
        this.reconnectDelay * 2,
        this.maxReconnectDelay
      )
    }
  }
}

Heartbeat

setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'ping' }))
  }
}, 30000)

Authentication

With Cloudflare Access

const ws = new WebSocket('wss://your-domain.com/agent/my-agent', {
  headers: {
    'CF-Access-JWT-Assertion': jwtToken
  }
})

Via URL Parameter

const ws = new WebSocket('wss://your-domain.com/agent/my-agent?token=' + token)

Rate Limiting

Limit	Value
Connections per IP	10
Messages per second	10
Max message size	64 KB

Example: Chat Interface

const ws = new WebSocket('wss://your-domain.com/agent/my-agent')

// Subscribe to messages
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    events: ['message:received']
  }))
}

// Handle incoming messages
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)

  if (msg.type === 'message:received') {
    displayMessage(msg.data)
  }
}

// Send message via REST API, receive via WebSocket
async function sendMessage(content) {
  await fetch('/api/agents/my-agent/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: content })
  })
  // Response will come via WebSocket
}

Example: Workflow Monitor

const ws = new WebSocket('wss://your-domain.com/agent/my-agent')

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    events: ['workflow:status', 'workflow:complete']
  }))
}

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)

  switch (msg.type) {
    case 'workflow:status':
      updateWorkflowStatus(msg.data)
      break
    case 'workflow:complete':
      showWorkflowResult(msg.data)
      break
  }
}

Errors

Code	Description
1000	Normal closure
1001	Going away
1008	Policy violation
1011	Server error
4000	Invalid message
4001	Unauthorized
4029	Rate limited