Skip to content
Agent Platform

Apps

The monorepo has three deployable apps under apps/. Each one composes packages from packages/ into something runnable. The packages are libraries; the apps are products.

AppPurposeStatus
apps/workerThe platform’s main runtime. Cloudflare Worker.Deployed. Phase 1’s order-triage scenario runs here.
apps/exampleStandalone Node CLI. Smoke test for the agent loop without Cloudflare.Local-only. Used during platform development.
apps/docsThis documentation site. Astro + Starlight on Cloudflare Pages.Deployed. You’re reading it now.

Each app’s section below covers what it is, its layout, and how to run or deploy it.

apps/worker — the platform Worker

Section titled “apps/worker — the platform Worker”

The deploy target. Every Phase 1 capability lives here: the HTTP API for synchronous and asynchronous agent runs, the cron handler for scheduled work, the queue consumer for the event bus, the admin endpoint for seeding memory.

A single Cloudflare Worker handles three handler types (fetch, scheduled, queue) — one bundle, one deploy, three entry points. See Cloudflare Workers for why this shape.

Layout

Section titled “Layout”
apps/worker/
├── wrangler.toml                 Deploy config; lists every binding
├── package.json                  Dependencies on @agent-platform/* packages
├── README.md                     Operational runbook
├── migrations/
│   └── 0001_long_term_memory.sql Single D1 schema migration
├── agents/                       YAML agent definitions
│   ├── triage.yaml               + triage.prompt.md
│   ├── refund-decision.yaml      + refund-decision.prompt.md
│   ├── communication.yaml        + communication.prompt.md
│   └── merchandising.yaml        + merchandising.prompt.md
├── scripts/
│   └── e2e-demo.sh               End-to-end demo verification
└── src/
    ├── index.ts                  Entry point: routes + handler registration
    ├── handlers.ts               /run and /jobs request handlers
    ├── auth.ts                   Bearer-token middleware
    ├── agent-job.ts              AgentJob Durable Object class
    ├── job-index.ts              KV-backed job listing layer
    ├── gateways.ts               Wires LongTermMemory + EventBus + Embedder
    ├── queue-consumer.ts         Queue-handler entry point
    ├── seed/                     /admin/seed-memory implementation
    │   ├── refund-history.ts     Hand-crafted seed fixtures
    │   └── seed-handler.ts       Seed orchestration
    ├── scenarios/                Per-scenario glue
    │   └── order-triage/
    │       ├── runtime.ts        Composes the delegation chain
    │       └── schemas.ts        Per-topic event schemas
    └── merchandising.ts          The cron-driven merchandising agent

Running locally

Section titled “Running locally”
Terminal window
cd apps/worker
cp .dev.vars.example .dev.vars     # add real secrets
wrangler dev                        # local Worker on localhost:8787

wrangler dev runs the Worker against real Cloudflare bindings (D1, Vectorize, Queues) over the network — not local stubs. This is what catches Workers-runtime bugs that pure Vitest misses.

Deploying

Section titled “Deploying”
Terminal window
cd apps/worker
wrangler deploy

After deploy, run the demo verification:

Terminal window
RUN_E2E=1 \
WORKER_URL=https://your-worker-url \
WORKER_AUTH_TOKEN=$(cat ~/.agent-platform-token) \
./apps/worker/scripts/e2e-demo.sh

Full setup runbook (D1 migrations, Vectorize index creation, Queues setup, secrets) lives in apps/worker/README.md. See also the demo runbook.

Test count

Section titled “Test count”

The Worker has 70+ tests spanning route handlers, gateway wiring, queue dispatch, agent loops, and seed logic. None of them hit real services — Vitest with mocked bindings. Production-only bugs are caught at deploy time by the e2e script (this is exactly how commit 11’s hotfix was found).

apps/example — Node CLI smoke test

Section titled “apps/example — Node CLI smoke test”

A standalone Node script that exercises the platform’s runtime against real Anthropic without any Cloudflare dependencies. Used during platform development to validate that the runtime itself works in isolation, before adding the Worker layer.

What it does

Section titled “What it does”
$ ANTHROPIC_API_KEY=sk-ant-... pnpm --filter @agent-platform/example start


[example] starting research-assistant agent
[example] agent ran 4 tool calls, 1 delegation
[example] final report: ...

A small research-assistant scenario with one main agent and one sub-agent. Demonstrates the full agent loop (system prompt, tool calls, delegation, structured report output) over plain Node — no Workers, no Cloudflare bindings.

Layout

Section titled “Layout”
apps/example/
├── package.json
├── README.md
└── src/
    ├── index.ts                  CLI entry point
    ├── agents/
    │   ├── research.yaml         Main agent
    │   └── summary.yaml          Sub-agent
    └── tools/                    Pure-Node tool implementations

Running

Section titled “Running”
Terminal window
ANTHROPIC_API_KEY=sk-ant-... pnpm --filter @agent-platform/example start

Why it exists

Section titled “Why it exists”

Two reasons:

  1. Validation that the runtime is platform-agnostic. If the runtime worked only on Workers, that would betray a hidden coupling. apps/example running on Node proves the boundary is clean.
  2. Faster iteration during development. Workers wrangler dev is fast (~1s reload) but requires real Cloudflare bindings. For runtime changes that don’t touch Workers-specific code, running a Node script is even faster.

The example app isn’t deployed anywhere. It’s a local dev tool.

apps/docs — this documentation site

Section titled “apps/docs — this documentation site”

The site you’re reading. Astro + Starlight, deployed to Cloudflare Pages.

Layout

Section titled “Layout”
apps/docs/
├── astro.config.mjs              Site config + sidebar structure
├── package.json
├── tsconfig.json                 Astro strict preset
├── wrangler.jsonc                Pages deploy config
├── README.md                     Local dev + deploy instructions
└── src/
    ├── content.config.ts         Starlight 'docs' collection
    ├── styles/custom.css         Single override surface (color tweak only)
    └── content/docs/
        ├── index.mdx             Landing — splash + audience-routed cards
        ├── platform/             "What is the agent platform?" section
        │   ├── overview.md
        │   ├── concepts.md
        │   └── glossary.md
        └── tech/                 "How is it built?" section (you're here)
            ├── stack/            Per-service pages
            │   ├── index.mdx
            │   ├── cloudflare-workers.md
            │   ├── cloudflare-d1.md
            │   ├── cloudflare-vectorize.md
            │   ├── cloudflare-queues.md
            │   ├── cloudflare-durable-objects.md
            │   ├── cloudflare-pages.md
            │   ├── anthropic.md
            │   └── openai.md
            ├── packages.md       Tour of every monorepo package
            └── apps.md           This page

Pages are added incrementally per the docs-site commit plan (commits 1-8). Each commit adds a section or scenario walkthrough.

Local dev

Section titled “Local dev”
Terminal window
pnpm --filter @agent-platform/docs dev
# → Astro dev server on http://localhost:4321

Hot-reload on every save. Markdown changes are instant; CSS and config changes occasionally need a full restart.

Deploying

Section titled “Deploying”

Two options, documented in apps/docs/README.md:

  • Manual: pnpm --filter @agent-platform/docs deploy (runs astro build then wrangler pages deploy ./dist)
  • Git-driven (recommended): Cloudflare dashboard → Pages → point at the repo, set build command to pnpm --filter @agent-platform/docs build, output to apps/docs/dist. Every push to main deploys; PRs get preview URLs.

Why it lives in the same repo

Section titled “Why it lives in the same repo”

Per the docs-site design conversation: docs are version-locked to the platform code. ADRs land alongside the pages that describe them; package changes land alongside their tour pages. One PR can update code and docs together. If/when a marketing person needs to push without touching platform code, the docs site extracts to its own repo cleanly — but today the version-locked property is worth more than the independence.

Why three apps, not one

Section titled “Why three apps, not one”

A natural question: why not put the docs site inside the platform Worker, or skip apps/example since the Worker exercises everything?

Two reasons:

  • Different deploy targets. apps/worker deploys to Cloudflare Workers; apps/docs to Cloudflare Pages; apps/example is local Node. Each app’s package.json, dependencies, and build pipeline are tuned for its target.
  • Different audiences. The Worker is the product. The docs site is the knowledge base. The example is a developer tool. Mixing them would couple unrelated concerns and confuse the deploy story.

Adding a fourth app (e.g. an operator UI in Phase 3) follows the same pattern: new directory under apps/, new package.json, its own deploy pipeline, depending on packages/* for shared code.