Dramatiq
Call Dramatiq actors from xmcp tools through an authenticated HTTP bridge, with typed results and no automatic retries.
For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.@xmcp-dev/dramatiq lets xmcp tools enqueue Dramatiq jobs and read their results. It calls a small HTTP bridge that runs next to your Python workers. The runnable example includes the bridge, a demonstration actor, and Docker Compose for Redis and a worker.
Enqueue and read jobs
getResult(jobId) returns one of these states:
| Status | Meaning |
|---|---|
succeeded | The actor returned result. |
failed | The actor raised. error is a sanitized message; details stay in worker logs. |
unavailable | No result is stored. This does not mean the job is queued or running. |
not_found | The job ID is unknown, or its retention expired. |
Dramatiq's result backend cannot tell whether a job without a result is queued, running, or lost. Never report unavailable as progress.
Bridge API
The bridge exposes a small versioned API, and every request requires Authorization: Bearer <token>:
POST /v1/jobswith{ actor, args?, kwargs? }returns202 { "jobId" }. Unknown actors and invalid arguments return422; Redis failures return503.GET /v1/jobs/{id}returns{ "status": ... }as above, or404for unknown or expired jobs.
The bridge validates actors against an explicit registry and never imports modules by name. The TypeScript client never serializes broker messages. Job metadata lives in Redis next to Dramatiq's results, so lookups survive bridge restarts. Both use one configurable retention period (RESULT_RETENTION_SECONDS).
Errors and retries
The client never retries and rejects redirects so the token never leaves baseUrl. Non-success responses throw DramatiqBridgeError with the HTTP status. A 503 from enqueue means acceptance is unknown, so check before resubmitting. Request signals are forwarded, but cancelling a request does not cancel a job that was already enqueued.
Scheduling, job cancellation, worker monitoring, and multi-tenant job ownership are out of scope.
Tested versions
Dramatiq 2.2.0, FastAPI 0.135.1, Uvicorn 0.41.0, and Redis 7.4 and 8.10. The example's end-to-end test runs Redis, a worker, and the bridge. It covers results across bridge restarts, actor failures, expiry, auth, and Redis outages.
