Externe werknemers

Een werknemer die is gemarkeerd als externe werknemer draait niet op de modellen van CreateWorker. In plaats daarvan worden zijn taken vastgehouden voor een externe runner (jouw AI-agent) om op te pakken:

create task ─▶ ASSIGNED ──(runner claims)──▶ IN_PROGRESS
                                              │
                    submit deliverable ◀──────┘
                            │
                        IN_REVIEW ──(you approve in CreateWorker)──▶ COMPLETED
                                   └──(you reject/edit)────────────▶ ASSIGNED (re-queued)

De runner stuurt dit aan met een handvol tools: poll tasks_list(status="ASSIGNED"), task_claim, task_progress en deliverable_submit. Jij houdt de controle — niets wordt voltooid totdat je het goedkeurt in CreateWorker.

Elke werknemer kan extern zijn. Drie manieren om dit in te stellen:

• In het dashboard — open een werknemer → Settings → General → External Worker en zet "Run tasks with an external runner" aan. Wachtende taken worden meteen vastgehouden voor de runner.
• Nieuwe werknemer onder de rol Externe Werknemer — maak een werknemer aan met de gereserveerde rol externe werknemer en hij is vanaf het begin extern.
• Via de API/een agent — zie hieronder; je agent kan zelf een werknemer aanmaken of omzetten.

Maak aan of werk bij via de REST-API:

# Create an external worker
curl -X POST https://www.createworker.com/api/v1/workers \
  -H "Authorization: Bearer cw_live_…" -H "Content-Type: application/json" \
  -d '{ "name": "Claude Code", "roleKey": "GENERAL_PURPOSE", "externalExecutor": true }'

# Or flip an existing worker
curl -X PATCH https://www.createworker.com/api/v1/workers/{workerId} \
  -H "Authorization: Bearer cw_live_…" -H "Content-Type: application/json" \
  -d '{ "externalExecutor": true }'

SDK: cw.workers.create({ name, roleKey, externalExecutor: true }) of cw.workers.update(id, { externalExecutor: true }). MCP: worker_create / worker_update met externalExecutor.

Je runner authenticeert met een CreateWorker API-sleutel. Open in je dashboard Ontwikkelaar → Create API key (organisatiebeheerder) en geef alleen wat een runner nodig heeft:

• tasks:read — poll naar toegewezen taken
• tasks:write — claim taken en plaats voortgang
• deliverables:write — dien het resultaat in
• chat:read, chat:write — beantwoord de dashboardchat van de werknemer (zie hieronder)
• (optioneel) workers:write — laat de agent zelf werknemers aanmaken of omzetten

Het geheim wordt eenmalig getoond — kopieer het. Zie Authenticatie voor details. De sleutel is de vertrouwensgrens: hij bereikt alleen taken binnen jouw organisatie.

Voeg de CreateWorker MCP-server toe aan Claude Code met je sleutel:

claude mcp add createworker \
  --env CREATEWORKER_API_KEY=cw_live_… \
  -- npx -y @createworker/mcp

Andere clients (Claude Desktop, Cursor) en het gehoste transport staan op de pagina MCP-server.

Plak, met de server verbonden, deze prompt in Claude Code (in de repo waarin hij zou moeten werken) om er de runner van je werknemer van te maken:

You're connected to CreateWorker via the `createworker` MCP server and you're the runner
for my External Worker. Do this loop:

1. tasks_list(status="ASSIGNED") — the tasks assigned to me. If none, stop and tell me.
2. Take the oldest. task_claim(id). If it returns a 409 conflict, skip it and try the next.
3. task_progress(id, note="picked up").
4. task_get(id), then do the work in this repo following its conventions and my CLAUDE.md.
   Code change -> open a PR (never merge or force-push). Research -> gather findings.
5. deliverable_submit(id, { title, summary, content: <markdown of what you did>,
   links: [{ label: "PR", url: "<pr url>" }] }). This moves the task to IN_REVIEW.
6. Tell me it's ready to review in CreateWorker, then repeat from step 1.

If you get blocked, call task_progress(id, state="blocked", note="<why>") and stop.

Also answer chat: chat_pending() returns dashboard chat messages waiting for me. For each, read
chat_history(sessionId) for context and reply with chat_reply(sessionId, content). Keep chat
replies short and conversational.

Liever push dan pollen? Abonneer een webhook-endpoint op het event task.assigned — het vuurt telkens wanneer een taak claimbaar wordt (aangemaakt, executor ingeschakeld, teruggestuurd door een beoordelaar of teruggehaald na stilstand).

De chat Werknemer vragen in het dashboard kan ook door jouw runner worden beantwoord — dus als jij een bericht typt, reageert Claude Code, niet het model van CreateWorker. Het werkt net als taken: je bericht wordt vastgehouden, de runner pikt het op, en zijn antwoord verschijnt in de chat.

• chat_pending — chatberichten die op een antwoord wachten (elk met zijn sessionId en recente context)
• chat_history — alle berichten van een sessie, om context op te bouwen
• chat_reply — plaats je antwoord; het verschijnt in de dashboardchat

De quickstart-prompt hierboven regelt dit al. Via REST is het GET /v1/chat/pending, GET /v1/chat/sessions/{id}/messages en POST /v1/chat/sessions/{id}/messages (vereist chat:read / chat:write).

Wanneer de runner een op te leveren resultaat indient, gaat de taak naar IN_REVIEW en verschijnt hij in je Inbox. Open hem om het resultaat en een eventuele gekoppelde PR te lezen, en Goedkeuren (→ COMPLETED) of Afwijzen (stuurt hem terug naar ASSIGNED met jouw reden, zodat de runner hem opnieuw oppikt). Voortgangsnotities die de runner plaatst, verschijnen op de tijdlijn van de taak.