WebSocket API

The WebSocket API enables real-time, bidirectional communication with your workflows. Use this API for interactive workflows that require continuous updates or event streaming.

Connection Details

WebSocket URL

wss://run.agnt5.me/ws?x-wf-endpoint=<your-workflow-endpoint>

Authentication

Authentication requires two components:

• Workflow endpoint (as URL query parameter)
• API key (via WebSocket protocol header)

Example connection parameters:

const socket = new WebSocket(
  'wss://run.agnt5.me/ws?x-wf-endpoint=coffee-shop-e66b8d23',
  ['x-api-key.your-api-key-here']
);

Message Format

Sending Messages

Send JSON messages in the following format:

{
    "name": "workflow-name",
    "parameters": {
        "param1": "value1",
        "param2": "value2"
    },
    "metadata": {
        // Optional metadata
    },
    "connection_id": "ws_uniqueIdentifier"
}

Example Message

{
    "name": "search-candidates",
    "parameters": {
        "user_query": "Full stack engineer with 10+ years of experience in React willing to work remotely",
        "organization_id": "272e9e73-fe36-4ea1-acf6-4ea08d21aa0c",
        "filters": {}
    },
    "metadata": {},
    "connection_id": "ws_c2GDFfT7bywQZW4He6CNFw"
}

Events

The WebSocket connection emits various events during workflow execution. Subscribe to these events to monitor workflow progress and handle responses.

Execution Events

Monitor overall execution status:

• execution_started: Workflow execution begins
• execution_completed: Workflow completes successfully
• execution_failed: Workflow fails with an error
• execution_cancelled: Workflow is cancelled

Workflow Events

Track workflow-level operations:

• workflow_start: Workflow initialization
• workflow_end: Workflow completion
• workflow_error: Workflow-level error occurs

Task Events

Monitor individual task execution:

• task_start: Task begins execution
• task_end: Task completes
• task_error: Task encounters an error

LLM Events

Track Language Model operations:

• llm_start: LLM processing begins
• llm_end: LLM processing completes
• llm_error: LLM encounters an error

Tool Events

Monitor external tool interactions:

• tool_start: Tool execution begins
• tool_end: Tool execution completes
• tool_error: Tool encounters an error

Event Message Format

Events are received in the following format:

{
    "type": "event_name",
    "data": {
        "timestamp": "2024-01-10T12:00:00Z",
        "details": {},
        "execution_id": "exec_abc123"
    }
}

Error Handling

Connection Errors

Handle these common connection scenarios:

• Connection timeout
• Authentication failure
• Invalid endpoint

Example error handling:

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

socket.onclose = (event) => {
    if (event.code === 1006) {
        // Handle unexpected closure
    }
};

Reconnection Strategy

Implement exponential backoff for reconnection:

function connect(retryCount = 0) {
    const maxRetries = 5;
    const backoffMs = Math.min(1000 * Math.pow(2, retryCount), 30000);
    
    if (retryCount >= maxRetries) {
        throw new Error('Maximum retry attempts reached');
    }
    
    // Attempt connection
    // If fails, retry with: setTimeout(() => connect(retryCount + 1), backoffMs);
}

Best Practices

1. Message Handling

   • Implement message queuing for high-frequency events
   • Validate message format before sending
   • Handle partial message reconstruction

2. Connection Management

   • Implement heartbeat mechanism
   • Handle reconnection with exponential backoff
   • Clean up resources on connection close

3. Error Recovery

   • Cache important messages for retry
   • Maintain operation state for recovery
   • Log connection and message events

4. Performance

   • Batch small messages when possible
   • Implement message compression for large payloads
   • Monitor connection health metrics

Rate Limits

• Maximum message size: 64KB
• Maximum messages per second: 100
• Maximum concurrent connections per endpoint: 50

Example Implementation

class WorkflowSocket {
    constructor(endpoint, apiKey) {
        this.endpoint = endpoint;
        this.apiKey = apiKey;
        this.connect();
    }

    connect() {
        this.socket = new WebSocket(
            `wss://run.agnt5.me/ws?x-wf-endpoint=${this.endpoint}`,
            [`x-api-key.${this.apiKey}`]
        );

        this.socket.onopen = this.handleOpen.bind(this);
        this.socket.onmessage = this.handleMessage.bind(this);
        this.socket.onerror = this.handleError.bind(this);
        this.socket.onclose = this.handleClose.bind(this);
    }

    handleMessage(event) {
        const message = JSON.parse(event.data);
        // Handle different event types
        switch(message.type) {
            case 'execution_completed':
                // Handle completion
                break;
            case 'task_error':
                // Handle error
                break;
            // ... handle other events
        }
    }
}

For detailed examples and advanced usage, visit our WebSocket API documentation.