Architecture

Control Plane

D1 stores relational metadata for users, workspaces, agents, versions, runs, tasks, schedules, skills, tools, memory records, message records, approvals, usage, queue jobs, workflow runs, and audit logs. Large bodies live in R2 and are referenced from D1 by object key.

The first deployment uses one D1 database with workspace_id indexes. The schema keeps workspace IDs on all tenant-scoped tables so hot workspaces can later move to a dedicated database.

Runtime Plane

Workers remain stateless:

• apps/api handles admin APIs, auth/session bootstrap, CRUD, run enqueueing, run replay, and Telegram webhooks.
• apps/runtime consumes queues, executes agent runs, dispatches tasks and schedules, applies approvals, writes traces, stores memory, indexes memory, and sends notifications.
• apps/workflows provides durable orchestration for long-running runs and approval waits.

Model calls default through Cloudflare AI Gateway using the Workers AI binding. The agent version stores the provider choice, so direct Workers AI remains an explicit fallback path when needed.

Durable Objects are intentionally absent from the main scaffold. Add them later only for per-agent locks, live admin sessions, rate-limit buckets, and streaming fanout.

Agent Execution

Each run resolves the agent’s active version, loads workspace and version-level runtime policy, acquires a per-agent lock, and then runs through a model/tool loop.

• Tools can be HTTP, remote MCP, or built-in web search.
• Tool use can require approval before execution.
• Run traces are persisted to R2 and the trace key is stored back in D1.
• Usage events are recorded for model, tool, queue, and other runtime activity.

Memory

Memory is split across:

• D1: compact memory records, scope, visibility, importance, retention metadata.
• R2: long-form payloads, transcripts, documents, chunks, and generated artifacts.
• Vectorize: semantic vectors with workspace/agent/user/channel metadata filters.

Retrieved memory must be treated as untrusted context unless it comes from an admin or system-authored source.

Queues

• webhook-events: normalized platform events.
• agent-runs: run execution.
• agent-runs also carries task execution jobs.
• memory-index: embedding and vector indexing.
• notifications: outbound messaging updates.
• dead-letter: retry exhaustion and operator recovery.

API Surface

See API Reference for the complete current route list.

The main surfaces are:

• session and workspace bootstrap
• agent and run management
• task and schedule automation
• skills and tools
• memory, approvals, messages, and usage
• Telegram webhook integration

Deployment Notes

Replace placeholder resource IDs in each wrangler.jsonc, then create:

• D1 database: agentic-dev
• R2 bucket: agentic-dev-objects
• Queues: webhook-events, agent-runs, memory-index, notifications, dead-letter
• Vectorize index: agentic-memory
• Workflow: agentic-long-run

Set secrets:

pnpm --dir apps/api exec wrangler secret put TELEGRAM_BOT_TOKEN
pnpm --dir apps/runtime exec wrangler secret put TELEGRAM_BOT_TOKEN
pnpm --dir apps/api exec wrangler secret put TELEGRAM_WEBHOOK_SECRET

Apply D1 migrations:

pnpm --filter @agentic/db migrate:local