Getting started

Getting started

Unzip → install → deploy in 15 minutes.

Sourcedocs/GETTING-STARTED.md

A step-numbered walkthrough from the zip file to a live branded landing page on your own domain. No thinking required.

If you only have 5 minutes, do steps 1, 3, 4, 7. The defaults handle the rest. Prefer to let your AI do step 3? Paste prompts/rebrand.md into your coding assistant.

Prerequisites

  • Node 22.12+ (node -v — anything older will fail on Next.js 16 or the test toolchain).
  • An OpenAI or Anthropic API key — optional. Without one, the hero chat plays a scripted demo that looks real.

Step 1 — Unzip & install (1 min)

unzip agentkit-v2.1.0.zip
cd agentkit
bun install
bun run dev

Open http://localhost:3000. You should see the editorial-dark landing page with a live chat widget on the right and an Interactive demo pill in the top-left of the hero.

Expected terminal output:

▲ Next.js 16.2.10 (Turbopack)
- Local:        http://localhost:3000
- Environments: .env.local
✓ Ready in 1.2s

Gotcha — port 3000 is taken. Run PORT=3001 bun run dev instead. The chat hook calls a relative /api/chat so the port doesn't matter.

Step 2 — Browse /components (2 min)

Open http://localhost:3000/components. This is your working reference — 65 components with live previews.

  • Left sidebar groups by category (Chat primitives, Streaming, Agent state, Tool results, RAG, UI primitives). Search is at the top.
  • Each component page has a Preview tab, a Code tab with one-click copy, and the exact source path under src/components/.
  • Star (★) next to AgentTraceViewer marks the flagship — the one people buy AgentKit for.

Leave this tab open. Every time you go to build a section, check /components first before writing anything from scratch.

Gotcha — refresh on a theme-switched page. The theme is persisted in localStorage and re-applied in <head> before paint via /theme-init.js, so there's no flash. If you see one, hard-refresh once.

Step 3 — Make the copy yours (5 min)

Everything the page says lives in one file: site.config.ts at the project root. It ships filled in with an example product called Relay. Open it and start with the hero block: the headline, the subhead and the primary CTA. Save and the page hot-reloads.

Before:

hero: {
  headline: 'Get paged with *the answer*, not the alert.',
  subhead: 'Relay is an on-call agent. When an alert fires it reads the logs, ...',
  primaryCta: { label: 'Start free →', href: '#pricing' },
  // ...
},

After (example, make it yours):

hero: {
  headline: "Your customers' support agent, *live in a week*.",
  subhead: "Nova is the support agent that reads your docs, writes your replies, and escalates what it can't handle.",
  primaryCta: { label: 'Start free · 14-day trial →', href: '#pricing' },
  // ...
},

Wrap one or two words in *…* to get the italic accent in your brand color; don't wrap a whole phrase. While you are in the file, update product (name, URL), seo, pricing and faq, and edit or empty the three hero.metrics if you don't have numbers yet.

Or let your AI do it. Paste prompts/rebrand.md into Cursor or Claude Code, replace the brief at the bottom with your product, and review the diff of site.config.ts.

If you get an error. The config is checked on every bun run dev, bun run build and bun run test. A mistake names its field, for example site.config: hero.primaryCta.href must start with https://, http://, mailto:, # or / (got "relay.com"). Fix that field and save.

Gotcha — Tailwind CSS-var bracket syntax. If you do edit components, Tailwind 4 classes like bg-[var(--color-brand)] must keep the square brackets intact. Don't replace them with plain Tailwind color classes — every theme will break.

Step 4 — Brand color in 30 seconds (1 min)

Open src/app/globals.css. Find the default theme block (around line 29):

:root,
[data-theme="editorial-dark"] {
  --color-bg: #0a0a0a;
  ...
  --color-brand: #c6f432;                        /* change */
  --color-brand-tint-weak: rgba(198, 244, 50, 0.02);   /* change */
  --color-brand-tint: rgba(198, 244, 50, 0.1);          /* change */
  --color-brand-tint-strong: rgba(198, 244, 50, 0.25);  /* change */
  --color-border-brand: rgba(198, 244, 50, 0.25);       /* change */
}

Change --color-brand and run your new hex through a hex-to-rgba converter for the four tint variants. Everything on the page re-tints on save.

Lock to one theme. Three themes ship: editorial-dark (default), bright, cool-blue. Once you've picked one:

  1. In src/app/layout.tsx, set data-theme="your-theme" on <html>.
  2. In src/components/nav.tsx, delete the <ThemeSwitcher /> element.
  3. Delete src/components/theme-switcher.tsx.

Deep dive on theming and fonts: CUSTOMIZE.md.

Step 5 — Wire real AI, or skip (3 min)

The hero chat calls /api/chat, which runs a real AI SDK 7 agent loop: the model reasons, calls tools, asks the visitor to approve anything that changes state, and streams the answer. With no key set, the API returns 503 and the hero plays a clearly labelled scripted demo that still looks real — you can ship without this step and come back later.

To wire the live agent, pick a provider in site.config.ts:

ai: {
  provider: 'openai',      // 'openai', 'anthropic' or 'openrouter'
  model: 'gpt-6-luna',     // a model of that provider from src/lib/models.ts
  systemPrompt: 'You are Nova, a support agent. Be concise. ...',
},

Then put that provider's key in .env.local:

cp .env.example .env.local

OPENAI_API_KEY=sk-proj-...your-key...     # when provider is 'openai'
ANTHROPIC_API_KEY=sk-ant-...your-key...   # when provider is 'anthropic'
OPENROUTER_API_KEY=sk-or-...your-key...   # when provider is 'openrouter' (one key, hundreds of models)
TOOL_APPROVAL_SECRET=...                  # production: signs tool approvals, see CUSTOMIZE.md
UPSTASH_REDIS_REST_URL=https://...upstash.io
UPSTASH_REDIS_REST_TOKEN=...

Create a Redis database in the Upstash console and copy its REST credentials. The Redis variables are optional during local development but required whenever live inference runs in production; production fails closed rather than expose an unbounded model endpoint.

Kill and restart bun run dev (Next doesn't hot-reload env files). Send "Why are 5xx errors spiking on /api/checkout?" in the hero chat — you should see the agent reason, call the list_deploys and search_logs demo tools, and stop at an approval card before rollback_deploy. Approve or Deny it and the agent finishes its answer.

Try the other provider without editing the config. Set AI_PROVIDER=anthropic (and optionally AI_MODEL=<a model from src/lib/models.ts>) in .env.local. These override ai in site.config.ts.

Swap the demo tools for your real tools. src/lib/demo-tools.ts ships with three demo tools: list_deploys and search_logs (read-only) and rollback_deploy (needs approval). All return canned data. Replace them with your own using the AI SDK tool({ inputSchema, execute }) shape — any function that talks to your backend, database, or external API — and list every tool that changes state in demoToolApproval so the visitor must approve it first. The hero UI updates automatically; no frontend changes needed.

Your scripted demo. The run visitors see without a live model is demo.heroRun in site.config.ts (reasoning, tool steps, an approval card, the reply and the run footer). It is always labelled "scripted demo". Rewrite it for your product. Configs from v2.0 that only have the two-message demo.heroChat keep working.

Gotcha — env cache. If the chat still returns 503 after adding the key, you didn't restart bun run dev. Next.js only reads .env.local at boot. The 503 body says what is missing, for example OPENAI_API_KEY is not set. Visitors see the scripted demo.

Step 6 — Remove sections you don't need (2 min)

src/app/page.tsx stacks the sections in order:

<Hero />
<StreamingFeatures />
<AgentTraceSection />
<ToolCallingSection />
<PricingSection />
<SocialProofSection />
<FaqSection />
<FinalCtaSection />

Delete a section's element (and its import) to remove it; move elements to reorder. Most common removals on day one:

  • SocialProofSection — ships with no testimonials and hides itself while socialProof.proof and socialProof.testimonials in site.config.ts are both empty, so you don't need to remove it. Fill it only with real, verifiable facts and quotes.
  • PricingSection — remove if you sell contracts only or aren't ready to publish pricing.

Also remove the matching import line at the top of page.tsx so TypeScript stays happy. Links in nav.links, the footer groups and your CTAs that point at a removed section's anchor (#pricing, etc.) go nowhere — update or remove them in site.config.ts.

Step 7 — Deploy to Vercel (2 min)

bunx vercel

Follow the prompts. Vercel auto-detects Next.js 16; accept the defaults. First deploy gives you a *.vercel.app URL.

Before you deploy, set showcase: false in site.config.ts. That hides the kit's own catalog (/components, /sections, /docs, /starters) so your site shows only your product. See CUSTOMIZE.md.

Add your env vars:

Vercel dashboard → your project → Settings → Environment Variables
  OPENAI_API_KEY = sk-proj-...    (or ANTHROPIC_API_KEY / OPENROUTER_API_KEY, to match site.config.ts ai.provider)
  TOOL_APPROVAL_SECRET = ...      (any long random string, e.g. openssl rand -hex 32)
                                  (apply to: Production, Preview, Development)
  UPSTASH_REDIS_REST_URL = https://...
  UPSTASH_REDIS_REST_TOKEN = ...

Click Redeploy on the latest deployment (or push a commit) so the new env var is picked up. The hero chat now streams real replies on your live URL.

Gotcha — timeout. The chat route runs on the Node.js runtime with maxDuration = 30. If your real agent takes longer than 30s end-to-end, raise maxDuration (within your platform's limit) or move the long-running work to a worker.

Netlify, Cloudflare Workers, and Docker instructions: DEPLOY.md.

Step 8 — Point your domain (1 min)

In Vercel: Settings → Domains → Add → type yourdomain.com. Vercel gives you one of two DNS record sets depending on whether you're using apex or subdomain:

Apex (yourdomain.com) — add at your registrar:

Type  Name  Value
A     @     76.76.21.21

Subdomain (www.yourdomain.com or app.yourdomain.com):

Type   Name  Value
CNAME  www   cname.vercel-dns.com

DNS propagation is usually under 5 minutes for Cloudflare/Namecheap/Google Domains, up to an hour for Route53. HTTPS cert issues automatically once Vercel sees the record.

Test: open https://yourdomain.com, scroll to the hero, send "Hi". You should see a streamed reply with the green padlock.

You're live. What's next?

  • CUSTOMIZE.md — the site.config.ts field walkthrough, theming and fonts, replacing the demo agent with your real tools, honest approaches to social proof.
  • DEPLOY.md — Netlify, Cloudflare Workers, Docker, self-hosted.
  • COPY-FRAMEWORK.md — 8 headline formulas that work for AI products. Read before Step 3 if the blank page scares you.
  • CHANGELOG.md — version history. Compatible v1.x update URLs arrive by email.
  • /components — keep this tab open while you build. It's the fastest way to find the right primitive.

Stuck? Reply to your purchase receipt. Actual human.

— webdesignhot.com