Macrae

Updated 2026-10-08 20:15 · status: modules built, integration running

A voice agent for the Jungwirth group (IOCB Prague): it knows the group's papers, answers with citations, and when you click a task it does real work on cloud hardware, so you can watch exactly which papers it read and which calculations it ran.

1 · The pieces

The browser only talks to one Cloudflare address. The Worker serves the page, hands the browser a short-lived ElevenLabs voice session, and forwards /api calls to the backend with a secret header the browser never sees. The backend answers paper questions from its own index and starts tasks as agent-runner flows; Harbor runs each agent step in a sandbox on Modal and keeps the full trace.

YOU CLOUDFLARE (EDGE) BACKEND · CLOUDFLARE CONTAINER MODAL Web pageweb/ · tin-can style • 2–3 task cards• Talk to the agent • live transcript• run timeline: 📄 read 🔎 search 🧮 calc✍️ write ✅ result • citation cards → DOIworks with backend down ElevenLabs agentvoice in/out, its own LLM calls server tools:search_papers · start_task run_status Worker "macrae"cloudflare/ · wrangler deploy • serves web/• /api/* → backend adds X-Macrae-Secret• /voice/signed-url ElevenLabs key stays here Secrets + R2 storage ELEVENLABS key · agent idClaude login · Modal token MACRAE_TOOL_SECRETR2: index + run traces API (FastAPI)server/ /api/tasks · /api/runs · events/api/search /api/tools/* (ElevenLabs)every call checks the secret header RAGrag/ PDF → pagesBM25 + bge-smallfused ranking [n] citations agent-runnertasks/ flows scripts here,agents viaHarbor -e modal accounts, retries Container disk (synced to R2) papers/ (your PDFs, never in git)index/ (chunks + embeddings) runs/ (flow state, logs)jobs/ (Harbor traces) group_publications.json → titles,authors, DOIs for citations Sandbox per agent stepbuilt once from the agent image, cached by Modal Claude Code (Opus/Sonnet)reads the paper excerpts runs Python / xtb / OpenMMwrites result.json + card CPU/GPU as the task needs Trace (per step)trajectory.json every tool call + outputreward from check: changed files, costcopied back to jobs/ /api/* signed url tool webhooks (straight to backend) 1 sandbox / step → trace back
what the visitor touches voice backend code cloud compute stored data / secrets

2 · What happens when you…

…ask a question by voice
  1. Page asks the Worker for a signed URL; the voice session starts in the browser.
  2. The ElevenLabs agent calls search_papers, a webhook that goes straight to the backend.
  3. RAG returns the best passages, numbered [1] [2], with title, authors, page, DOI.
  4. The agent answers only from those passages and says the source ("Košťál 2026, page 3").
  5. It calls the page's show_citations; the cards appear beside the transcript.
…click a task (or ask for one)
  1. POST /api/tasks/{id}/start starts the task's flow in the background → run_id.
  2. Script steps pull paper passages from RAG; agent steps run in Modal sandboxes.
  3. The page polls /api/runs/{id}/events: each tool call becomes a timeline row (📄 read, 🧮 calc, ✍️ write…).
  4. A check: verifies the output (e.g. result.json has numbers) → reward.
  5. The agent narrates progress from run_status; the full trace is kept (container disk, copied to R2).

3 · Code map

folderwhat's in itstatus
data/, scripts/479 group publications (titles, authors, DOIs) from the IOCB sitedone
web/landing (task cards, "Talk to the agent", try-asking chips, typed questions that search the papers even without voice), run view (live timeline 📄🔎🧮✍️✅, counters, cited papers, steps), offline state, light/darkbuilt
cloudflare/Worker macrae: serves the page, proxies /api, ElevenLabs signed URL, rate limits; local dev server + mock backendbuilt
server/FastAPI: tasks, runs, trace events (tool calls → read / calc / write…), search, ElevenLabs tools; 51 testsbuilt
rag/PDF → clean pages (headers, hyphenation, reference lists removed) → chunks; BM25 + bge-small embeddings, fused ranking; [n] citations with pagebuilt
tasks/2 placeholder tasks (methods card, small calculation on Modal) + Modal support in agent-runnerbuilt your tasks: pending
voice/ElevenLabs agent "macrae" (Claude Sonnet 5.5 via ElevenLabs, cites every claim), three server tools, setup script checked against the live APIbuilt
deploy/backend Dockerfile (Harbor uses Modal, no Docker needed inside), scripts, Makefilebuilt → Cloudflare Container
whole systemintegrator agent fixes the seams between modules and tests end to endrunning

4 · Where it runs: all on Cloudflare

The page, the Worker and the backend live on one Cloudflare account and one address, deployed with wrangler deploy. The backend is a Cloudflare Container (the same Docker image) that stays awake about two hours after use so running tasks aren't cut off. Its disk is temporary, so the paper index is baked into the image and run traces are copied to R2. The heavy work (agents, calculations) runs in Modal sandboxes. AWS was the first plan and is no longer needed.

5 · How it was built

With agent-runner itself. A written contract (CONTRACT.md) fixed every interface, then six Claude Opus 5.5 agents (high effort) built their modules at the same time across three Claude accounts, each in its own container. All six passed their checks on the first attempt.

moduletimecost (API-equivalent)
web + Worker18.5 min$5.24
server14.4 min$3.86
rag15.6 min$3.41
tasks + Modal16.5 min$4.95
voice10.2 min$2.99
deploy15.7 min$3.44
total~19 min wall clock$23.90, on Claude subscriptions

Next in the same flow: an integrator agent fixes mismatches and tests the whole system, then the site deploys. A second flow then moves the backend into a Cloudflare Container with R2.

6 · What the owner provides

itemstatus
ElevenLabs API keyprovided verified
Claude login for the agentsprovided verified (to be replaced with a fresh key)
Modal token (dedicated, for the container)pending
Paper PDFspending indexed on the server, never published
The 2–3 clickable taskspending two placeholders until then
Hostingdecided Cloudflare

Glossary

RAGRetrieval-augmented generation: find the relevant passages first, answer only from them, cite them.
HarborOpen-source harness that runs an agent in a sandbox and saves its trajectory, reward and files.
ModalCloud that starts sandboxes/containers on demand, CPU or GPU, billed per second.
Trace / trajectoryEvery message, tool call and result of one agent run.
WorkerSmall program on Cloudflare's edge that serves the site and forwards API calls.
Signed URLA short-lived link that lets the browser open a voice session without seeing the API key.