N AgentNavaKit
agentnava.com →
AgentNavaKit · Guide

Build AI agents in TypeScript.
Bring your own UI.

AgentNavaKit lets you describe an AI agent in a single TypeScript object and run it on a managed runtime. The runtime executes the agent loop, handles tool calls, and streams typed events back — render them in any UI you like.

Quickstart → Read the spec

Quickstart

One TypeScript file walks the whole lifecycle: push a spec, configure an agent version, optionally deploy to test, then deploy to prod. No CLI, no login flow — just the SDK and an API key.

✦
One prompt → working agent
Paste this into Claude Code, Codex, or Cursor. It installs the SDK, scaffolds a real agent end-to-end as TypeScript, runs it, and opens a test URL.
Set up AgentNavaKit (`@agentnava/kit`) in this project end-to-end using ONLY the TypeScript SDK. There is no CLI. Agents always run on the AgentNava backend.

0. Ask me what to call the agent (kebab-case, e.g. `support-bot`, `inbox-triage`). Refer to it as `<agent-name>` below — substitute my answer everywhere.

1. Detect the package manager from the lockfile (bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm). Use it consistently.
2. Install `@agentnava/kit`.
3. Confirm `AGENTNAVA_API_KEY` is set in `.env` (or `process.env`). If it isn't, stop and tell me to generate one at https://console.agentnava.com → Settings → API keys, and paste it into `.env`. Don't proceed until I confirm.
4. Scaffold a Claude-Code-style agent folder at `agents/<agent-name>/`:
   - `AGENT.md` — single H1 with the agent's display name + one short paragraph describing what it does and how it talks. Ask me for a one-line role if it isn't obvious from context.
   - `skills/<example-skill>/SKILL.md` — YAML frontmatter (`name`, `description`, `allowed-tools`) and a 2-sentence body. Same format as Claude Code skills.
   - `commands/reset.md` — a user-invokable `/reset` slash command that clears the session history. Same format as Claude Code commands.
5. (Optional) If I have an existing Claude Code project, ask if I want to import its `.claude/skills/`, `.claude/agents/`, or `.claude/commands/` — copy them in unchanged.
6. Create `agents/<agent-name>.ts` that does the full lifecycle in code:
   - Import { AgentNava, loadAgentDir } from '@agentnava/kit'
   - const an = new AgentNava()
   - Push the spec as one bundle: `an.specs.push(loadAgentDir('./agents/<agent-name>', { key: '<agent-name>' }))` — it auto-discovers AGENT.md, skills/, subagents/, workflows/, commands/.
   - (Optional) `an.knowledge.upload({ key: '<agent-name>-kb', files: ['./agents/<agent-name>/knowledge/*'] })` if a `knowledge/` folder exists.
   - Configure the agent (key: '<agent-name>', name: <display-name>, modelClass: 'standard', spec, knowledge: kb ? [kb] : [], triggers: [{ kind: 'chat' }])
   - Deploy to test: an.agents.deployToTest(version.versionId)
   - console.log the test URL the call returns
   - Do NOT deploy to prod — the user does that explicitly.
7. Run the file: `bun run agents/<agent-name>.ts` (or `tsx agents/<agent-name>.ts` for npm/pnpm). Wait for the test URL.
8. Curl-test the chat endpoint at the test URL with a sample message; show the streaming SSE output.
9. Print a one-paragraph summary of what was created (spec ID, agent ID, version ID, test URL) and what to try next.

Reference: https://docs.agentnava.com
Don't modify unrelated files. Ask before any ambiguous choice.

Or do it by hand

1

Install the SDK

npm install @agentnava/kit
# or: bun add @agentnava/kit
# or: pnpm add @agentnava/kit

AgentNavaKit ships TypeScript source. No build step. There is no CLI to install — everything happens via the SDK.

2

Set your API key

# .env
AGENTNAVA_API_KEY=sk_live_…

Generate the key at console.agentnava.com → Settings → API keys. The SDK reads process.env.AGENTNAVA_API_KEY automatically. You can override per-instance with new AgentNava({ apiKey: '…' }).

3

Lay out the agent folder

Pick a kebab-case name for your agent (e.g. support-bot, inbox-triage). Below we refer to it as <agent-name> — substitute your choice everywhere.

agents/<agent-name>/
├── AGENT.md                 # the agent's core instructions (CLAUDE.md equivalent)
├── skills/
│   └── <example-skill>/SKILL.md   # auto-invokable mini-modules
├── workflows/
│   └── morning-digest.md    # multi-step playbooks
├── commands/
│   └── reset.md             # user-invokable slash commands
└── knowledge/               # RAG: .md / .pdf / .txt / .png / .jpg
    └── handbook.pdf

This is the same layout as Claude Code's .claude/ folder. Drop your existing skills, subagents, and commands in unchanged — the runtime reads them with the same frontmatter conventions. See Import from Claude Code for details.

# agents/<agent-name>/AGENT.md
# <Display name>

<One paragraph: what this agent does, how it talks, what it won't do.>
Answer in two paragraphs max unless the user asks for detail.
Always address the user as "you".

See File kinds for the full set and their frontmatter.

4

Write the lifecycle in TypeScript

// agents/<agent-name>.ts
import { AgentNava, loadAgentDir } from '@agentnava/kit';

const an = new AgentNava();

// 1. Push the spec bundle — AGENT.md + skills + subagents + workflows + commands.
const spec = await an.specs.push(
  loadAgentDir('./agents/<agent-name>', { key: '<agent-name>' }),
);
// → { id: 'spec_4f1c9a', version: 1 }

// 2. Upload the knowledge base (.md / .pdf / .txt / images).
const kb = await an.knowledge.upload({
  key: '<agent-name>-kb',
  files: ['./agents/<agent-name>/knowledge/handbook.pdf'],
});
// → { id: 'kb_8b07', version: 1 }

// 3. Configure the agent → returns a new agent version.
const v = await an.agents.configure({
  key: '<agent-name>',                   // dev-chosen, stable; backend assigns agt_…
  name: '<Display name>',                 // what users address the agent as in chat
  modelClass: 'standard',
  spec,                                   // pins to spec@v1
  knowledge: [kb],                        // agents AND workflows always have full KB access
  triggers: [{ kind: 'chat' }],
});
// → { agentId: 'agt_2b8e', versionId: 'ver_3c5f' }

// 4. (Optional) deploy to test. Dev-only URL; no end-user traffic.
const test = await an.agents.deployToTest(v.versionId);
console.log('test:', test.url);

// 5. When ready, deploy to prod. End users hit this version.
// const prod = await an.agents.deployToProd(v.versionId);

Prefer explicit fields? loadAgentDir is sugar over an.specs.push({ key, instructions, skills, subagents, workflows, commands }) — see Spec.

5

Run it

npx tsx agents/<agent-name>.ts
# or: bun run agents/<agent-name>.ts
#
# spec pushed: spec_4f1c9a@v1
# agent version: ver_3c5f (agt_2b8e)
# test: https://<temp-id>.test.agents.agentnava.com

The TS file IS the deployment script. Re-run it whenever you change the spec or the configuration — push is idempotent on key, configure upserts on key, only changed content gets a new version.

6

Chat with the test agent

curl -N -X POST https://<temp-id>.test.agents.agentnava.com/chat \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Hi!"}]}'

SSE stream of AgentEvents. Plug it into any UI that reads SSE — your own React app, Vue, vanilla JS, our embed widget. See Sessions for the full chat protocol with attachments and multi-turn history.

7

Deploy to prod when ready

const prod = await an.agents.deployToProd(v.versionId);
console.log('prod:', prod.url);
// → https://hello-bot.agents.agentnava.com

Promotes the agent version to the stable production URL. End users now hit this version. See Operate for custom domains, rollbacks, and BYOK.