--- name: cloudbot-backend-agent-connector description: Connect an AI backend agent or OpenClaw gateway to CloudBot's frontend voice service. --- # CloudBot Backend Agent Connector Use this skill when a user wants an AI agent, OpenClaw instance, or custom backend agent to connect to CloudBot's frontend voice service. ## Goal CloudBot is the frontend voice service. It owns the browser or phone conversation, LiveKit room, tenant context, frontend agent profile, and customer dashboard. The backend agent owns deeper work: tools, files, workflows, sub-agents, long-running reasoning, and external systems. The connection is an HTTP gateway contract: CloudBot frontend voice agent -> customer backend gateway -> backend AI agent -> response back to CloudBot. ## Registration Ask the user for these values: - CloudBot dashboard URL: https://cloudbot.ai/dashboard - Gateway URL: the public HTTPS base URL of the backend gateway - Gateway API key: a shared secret accepted by the backend gateway as X-API-Key - Backend agent name: the agent or workflow CloudBot should call - Response mode: sync, async, or sync_then_callback - Frontend routes: the frontend agents allowed to call this backend agent In CloudBot, open Dashboard -> Agent Routing, save the gateway URL and key, register the backend agent, choose frontend routes, then run Test Health. ## Backend Gateway Requirements Implement this health endpoint: ```http GET /cloudbot/voice/health X-API-Key: 200 OK { "status": "healthy", "channel": "cloudbot-voice", "auth_configured": true, "timestamp": "2026-07-13T00:00:00.000Z" } ``` Implement this inbound message endpoint: ```http POST /cloudbot/voice/inbound Content-Type: application/json X-API-Key: { "message": "Summarize the current customer request and run the needed tool.", "route_id": "frontend_backend_route_uuid", "backend_agent_id": "backend_agent_profile_uuid", "external_agent_id": "n8n_workflow_or_worker_id", "worker_id": "kw1", "tenant_id": "tenant_slug_or_id", "room_name": "cb_tenant_1720000000", "frontend_agent_id": "frontend_voice_agent_id", "request_id": "cbbe_1720000000_ab12cd34", "response_mode": "sync", "wait_for_reply": true } ``` If wait_for_reply is true, return: ```json 200 OK { "status": "ok", "messageId": "cbv_1720000000_ab12cd", "sessionKey": "agent:main:cloudbot-voice:direct:cloudbot:kw1", "worker_id": "kw1", "tenant_id": "tenant_slug_or_id", "room_name": "cb_tenant_1720000000", "frontend_agent_id": "frontend_voice_agent_id", "route_id": "frontend_backend_route_uuid", "backend_agent_id": "backend_agent_profile_uuid", "request_id": "cbbe_1720000000_ab12cd34", "reply": "Here is the result to speak back to the user." } ``` If wait_for_reply is false, return status "received" quickly and send the final response to the configured callback URL: ```json { "type": "kenny_response", "to": "cloudbot:kw1", "worker_id": "kw1", "text": "Final response text for CloudBot to speak or display.", "replyToId": "optional_message_id", "timestamp": "2026-07-13T00:00:00.000Z" } ``` ## Message Sync Rules Always preserve these fields when CloudBot provides them: - request_id: correlation id for the full backend request and response - tenant_id: customer tenant context - room_name: LiveKit or CloudBot room context - frontend_agent_id: CloudBot frontend voice agent id - route_id: CloudBot frontend-to-backend route id - backend_agent_id: CloudBot backend agent profile id - external_agent_id: optional provider-specific workflow, worker, or agent id - response_mode: sync, async, or sync_then_callback - worker_id: optional worker lane such as kw1 Do not drop these fields in logs, callbacks, or replies. They are how the frontend, runtime, and dashboard keep the message data synced. ## Observability CloudBot runtime components can record backend traffic here: ```http POST /api/runtime/agent/{frontend_agent_id}/backend-events Content-Type: application/json X-Runtime-API-Key: X-Tenant-ID: { "request_id": "cbbe_1720000000_ab12cd34", "connection_id": "openclaw_connection_uuid", "backend_agent_profile_id": "backend_agent_profile_uuid", "route_id": "frontend_backend_route_uuid", "room_name": "cb_tenant_1720000000", "backend_peer_id": "cloudbot:kw1", "direction": "inbound", "event_type": "response", "status": "ok", "status_code": 200, "latency_ms": 842, "payload": { "reply_preview": "Here is the result..." } } ``` Allowed values: - direction: inbound, outbound - event_type: health_check, request, response, error, timeout, circuit, status - status: ok, received, failed, timeout, rate_limited, unauthorized, circuit_open Redact secrets before sending payload data. ## OpenClaw Example Install or copy the CloudBot voice channel plugin into the OpenClaw extensions directory, then configure: ```json { "plugins": { "allow": ["cloudbot-voice"], "entries": { "cloudbot-voice": { "enabled": true, "config": { "apiKey": "", "externalAgentId": "kenny", "responseMode": "sync" } } } }, "channels": { "cloudbot-voice": { "enabled": true, "callbackUrl": "https://your-agent.example.com/cloudbot/callback", "accounts": { "default": { "enabled": true } } } } } ``` The OpenClaw plugin should expose: - GET /cloudbot/voice/health - POST /cloudbot/voice/inbound - optional POST /cloudbot/voice/workers/spawn - optional GET /cloudbot/voice/workers - optional GET /cloudbot/voice/sessions ## Acceptance Test 1. GET the backend health endpoint with X-API-Key. 2. Save the gateway URL and key in CloudBot Dashboard -> Agent Routing. 3. Run Test Health from the dashboard. 4. POST a sample message to /cloudbot/voice/inbound with wait_for_reply true. 5. Confirm the reply includes request_id, tenant_id, room_name, frontend_agent_id, route_id, backend_agent_id, response_mode, and worker_id when provided. 6. Confirm CloudBot's Recent API Traffic shows health_check, request, response, or error events.