Getting Started

Build a typed AI agent in 60 seconds. Dawn is file-system routing for agents — no registry, no hand-written tool schemas, no glue.

By the end of this guide you'll have a working deep-research assistant at /research that plans sub-questions, searches a local corpus, and writes cited reports. Live runs use a real model and API key; the included tests and evals use deterministic fixtures and run offline.

Prefer to build with a coding agent? Copy the prompt above and paste it into Claude Code, Cursor, or your agent of choice.

1. Install

bash

npm create dawn-ai-app@latest my-agent
cd my-agent
npm install

Requires Node.js 24 or later and npm 11.

For a minimal greeter scaffold instead, pass --template basic:

bash

npm create dawn-ai-app@latest my-app -- --template basic

2. What you got

The scaffold is a complete deep-research assistant, generated as a two-package npm workspace: server/ is the Dawn app, and web/ is the Dawn Workbench — a browser client in front of it. The root npm install installs both. These are the important files — no registration step is required.

text

package.json                          # workspace root: "workspaces": ["server", "web"]
server/                               # the Dawn app
  src/
    app/research/
      index.ts                        # research coordinator agent
      state.ts                        # route state shape
      plan.md                         # seeds the thread's planning todos
      memory.md                       # route-specific persistent prompt guidance
      memory.ts                       # typed cross-session research memory
      subagents/
        researcher/index.ts           # specialist dispatched per sub-question
      skills/
        cite-sources/SKILL.md         # loaded on demand: citation rules
        synthesize-findings/SKILL.md  # loaded on demand: report structure
      evals/
        research-quality.eval.ts      # quality eval with scorers and a gate
    tools/
      searchCorpus.ts                 # shared keyword search over the corpus
      readDoc.ts                      # shared full-document reader
  test/
    research.test.ts                  # main offline harness suite
    sandbox-docker.test.ts            # optional gated Docker sandbox smoke test
  workspace/
    AGENTS.md                         # persistent prompt guidance injected every turn
    corpus/                           # bundled documents the agent searches
    scripts/
      fetch-source.mjs                # network fetch script called via runBash
  AGENTS.md                           # contributor guidance for coding agents
  dawn.config.ts                      # app config: permissions, tool-output offloading
  .env.example                        # provider environment template
web/                                  # the Dawn Workbench (Next.js + CopilotKit)
  app/
    page.tsx                          # the CopilotKit provider tree and thread state
    components/                       # thread rail, transcript, composer, activity cards
    api/copilotkit/route.ts           # registers an AG-UI agent on the Dawn endpoint
    api/dawn/[...path]/route.ts       # allowlisted same-origin proxy to the server
    theme.css                         # the whole palette, as CSS variables

The route entry (index.ts) is a research coordinator. It recalls durable context, plans sub-questions, dispatches the researcher subagent for each one, and synthesizes a cited report. Shared tools under server/src/tools/ are available to both agents. dawn typegen writes their generated types from the function signatures; dawn check validates the app without writing files.

import { agent } from "@dawn-ai/sdk"
 
export default agent({
  model: "gpt-5-mini",
  recursionLimit: 100,
  description:
    "A deep-research assistant: plans sub-questions, dispatches researchers, and writes a cited report.",
  systemPrompt: `You are a deep-research coordinator. Given a question:
 
1. Start by checking durable context with \`recall({ query: "<the user's topic and preferences>" })\`.
2. Plan the sub-questions to investigate and record them in your todos.
3. For each sub-question, dispatch a specialist with \`task({ subagent: "researcher", input: "<sub-question>" })\`.
4. You may also \`searchCorpus({ query })\` and \`readDoc({ path })\` directly for quick lookups.
5. When the corpus lacks coverage, you may run \`runBash({ command: "node scripts/fetch-source.mjs <topic>" })\` — the human must approve it.
6. Synthesize the findings into a cited report and save it with \`writeFile({ path: "reports/<slug>.md", content: "<report>" })\`.
7. When the user gives a durable preference or you verify a reusable finding, call \`remember({ data, content })\` so it can be reviewed and recalled later.
 
Cite every claim with its source path in square brackets, e.g. [corpus/agent-architectures.md]. Keep the final answer concise.`,
})

The plan.md file opts the route into Dawn's planning capability — its checklist items seed each thread's todos. workspace/AGENTS.md and route-local memory.md provide persistent prompt guidance; memory.ts defines typed cross-session records exposed through recall and remember. Skills under skills/ are loaded on demand by name.

3. Verify and test

Run everything from the workspace root; each root script delegates into the package that owns it.

bash

npm run typegen
npm run check
npm run typecheck

typegen writes server/.dawn/dawn.generated.d.ts; check then validates route discovery, tool definitions, and configuration without writing generated files; typecheck validates the TypeScript sources in both packages. The validation output looks like:

text

Dawn app is valid: 2 routes discovered.
- /research (agent)
- /research/subagents/researcher (agent)

bash

npm test

Runs both packages' suites. The server half is the harness suite in server/test/research.test.ts: it replays fixture responses while exercising corpus search and citation, durable-memory recall and candidate approval, subagent dispatch, tool-output offloading, and the human-in-the-loop permission gate. The web half is the workbench's own Vitest unit tests over its proxy allowlist, thread source, transcript mapping, and components. No API key is needed for either. The separate npm run test:sandbox:docker --workspace server script enables the optional Docker sandbox smoke test.

bash

npm run eval

Runs the quality eval in server/src/app/research/evals/research-quality.eval.ts. Its dataset exercises research questions against the corpus; the scorers require corpus search, source citations, and a passing model-graded quality verdict. The inline fixtures cover both agent and judge requests, so the scaffolded eval runs without an API key.

These fixture-backed tests and evals provide deterministic offline confidence; they are not a keyless product demo.

4. Run it live

The model credentials live in the server package. Copy its environment example, add a real API key, run the preflight, and start the generated dev script:

bash

cp server/.env.example server/.env
# Add a real OPENAI_API_KEY to server/.env
npm run verify
npm run dev:server

The verify preflight covers app integrity, type declarations, dependencies, Node, the selected provider environment, and configured infrastructure. The generated dev script serves http://127.0.0.1:3002 and exposes Agent Protocol and AG-UI. In another terminal, create a thread, capture its id, then run the research agent on that thread:

bash

THREAD_ID=$(curl -s -X POST http://127.0.0.1:3002/threads \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .thread_id)
 
curl -s -X POST http://127.0.0.1:3002/threads/$THREAD_ID/runs/wait \
  -H "Content-Type: application/json" \
  -d '{
    "route": "/research#agent",
    "input": {
      "messages": [{ "role": "user", "content": "What are common agent architectures?" }]
    }
  }' | jq .

The #agent suffix is required — it selects the agent entry on the route. The report lands in server/workspace/reports/ inside the project. Thread state checkpoints to server/.dawn/checkpoints.sqlite; threads persist across dev-server restarts.

5. See it in a UI

curl is not the only surface. The web/ package is the Dawn Workbench, a chat UI over the same agent. Leave the server running and start it in a second terminal:

bash

npm run dev:web

Open http://localhost:3010 and ask a research question. The workbench has a thread rail, a streaming transcript with plan and researcher activity cards, generic tool cards, inline permission prompts, and a memory-candidate review panel. Until the server answers it shows a connect screen instead, and re-probes every few seconds. It talks to Dawn over AG-UI and holds no model credentials of its own — those stay in server/.env.

The plan and researcher cards are not hand-built. Dawn ships them from @dawn-ai/ag-ui/react, and the workbench restyles them through that package's classNames prop before handing them to CopilotKit's renderActivityMessages — validation and layout stay in the package. A client that wants Dawn's default look passes the packaged dawnActivityRenderers array instead and is done. The Research assistant web UI recipe walks through that wiring if you want to build your own client.

The scaffold also installs @dawn-ai/inspector, so a third terminal can open the Inspector — a browser UI over the app's live memory store, where the records the agent writes with remember show up for review:

bash

npx dawn inspect --cwd server

When you are ready to ship, compare Deployment Options and follow Node and Docker for the default self-hosted path.

Where to go next

Mental Model

understand the application model

Add a Tool

build the first feature

Deployment Options

choose the production path