---
name: cloudbot-backend-file-worker
description: Let a backend AI agent access, reference, transform, and save CloudBot Library files without duplicate uploads or lost work.
---

# CloudBot Backend File Worker

Use this skill when a backend AI agent receives a CloudBot request involving files, media, artifacts, library entries, or generated outputs.

## Backend Agent Responsibilities

1. Preserve all correlation fields CloudBot sends.
2. Work from artifact references when possible.
3. Request signed URLs only when original bytes are required.
4. Save drafts before final outputs for long-running work.
5. Use idempotency keys for every upload or generated result.
6. Return status updates that CloudBot can show to the customer.

## Runtime File Access

List relevant files:

```http
GET /api/runtime/agent/{frontend_agent_id}/library?request_id=cbbe_1720000000_ab12cd34
X-Runtime-API-Key: <cloudbot_runtime_key>
```

Get a signed URL for original bytes:

```http
GET /api/runtime/agent/{frontend_agent_id}/library/{artifact_id}?signed=1
X-Runtime-API-Key: <cloudbot_runtime_key>
```

Save a generated output:

```http
POST /api/runtime/agent/{frontend_agent_id}/library
X-Runtime-API-Key: <cloudbot_runtime_key>
Content-Type: multipart/form-data

file=<binary>
summary=Three marketing ideas based on the selected image.
request_id=cbbe_1720000000_ab12cd34
idempotency_key=cbbe_1720000000_ab12cd34:marketing-ideas:v1
frontend_agent_id=frontend_voice_agent_id
backend_agent_id=backend_agent_profile_uuid
route_id=frontend_backend_route_uuid
```

Create or update work state:

```http
POST /api/runtime/agent/{frontend_agent_id}/file-work
X-Runtime-API-Key: <cloudbot_runtime_key>
Content-Type: application/json

{
  "request_id": "cbbe_1720000000_ab12cd34",
  "frontend_agent_id": "frontend_voice_agent_id",
  "backend_agent_id": "backend_agent_profile_uuid",
  "route_id": "frontend_backend_route_uuid",
  "source_artifact_id": "customer_artifact_uuid",
  "instructions": "Create 3 marketing ideas from the selected image.",
  "status": "working",
  "idempotency_key": "cbbe_1720000000_ab12cd34:work"
}
```

## Idempotency

Use an idempotency key derived from the request and output role:

- cbbe_1720000000_ab12cd34:draft:1
- cbbe_1720000000_ab12cd34:marketing-idea:1
- cbbe_1720000000_ab12cd34:final:3

If the same save is retried, CloudBot should return the existing artifact instead of creating a duplicate.

## Storage Discipline

- For videos, prefer transcript, poster image, keyframes, and preview derivatives before requesting or creating another full-size video.
- For audio, prefer transcript and compressed preview.
- For images, prefer previews unless the original is required.
- For documents, prefer extracted text, OCR, and previews.

## Status Language

Report one of these states when possible:

- created
- dispatched
- accepted
- working
- saved_draft
- completed
- retrying
- blocked
- failed

## Reply Shape

```json
{
  "request_id": "cbbe_1720000000_ab12cd34",
  "status": "completed",
  "reply": "Saved 3 marketing ideas to the Library.",
  "artifacts": [
    { "artifact_id": "artifact_uuid_1", "output_role": "result" },
    { "artifact_id": "artifact_uuid_2", "output_role": "result" },
    { "artifact_id": "artifact_uuid_3", "output_role": "result" }
  ]
}
```