--- 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. For file and media work, CloudBot shares Library artifact references. Backend agents should request signed URLs only when they need original bytes and should save outputs with idempotency keys so retries do not duplicate files. ## 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. ## File Sharing Skills CloudBot exposes two agent-readable file skills: - Frontend file coordinator: https://cloudbot.ai/api/connect-agent/frontend-file-skill - Backend file worker: https://cloudbot.ai/api/connect-agent/backend-file-skill When the user says something like "Cloud, send that image to Kenny and have Kenny create 3 different marketing ideas," the frontend agent should resolve the artifact and backend route, then send a request like: ```json { "message": "Create 3 marketing ideas from the referenced image.", "request_id": "cbbe_1720000000_ab12cd34", "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", "artifacts": [ { "artifact_id": "customer_artifact_uuid", "name": "campaign-image.png", "media_type": "image", "content_hash": "sha256_hex" } ], "instructions": "Return 3 concise marketing ideas and save them to the CloudBot Library." } ``` The backend agent should preserve request_id and artifact_id, use signed URLs only if it needs the original bytes, and save outputs through the runtime Library API with an idempotency key. ## 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.