Build AI agents in TypeScript.
Bring your own UI.

Quickstart

Two paths. The fast one hands a single prompt to your coding agent and ships a working agent in one shot. The manual one is five steps.

Set up AgentNavaKit (`@agentnava/kit`) in this project end-to-end. Agents always run on the AgentNava backend — never locally. The lifecycle is: configure (upload spec + metadata) → test (ephemeral instance) → deploy (versioned production).

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` and `valibot`.
3. Check that the CLI is authenticated to my workspace by running `agentnava-kit whoami`. If it errors, stop and tell me to run `agentnava-kit login` (or set `AGENTNAVAKIT_API_KEY` if running in CI). Don't proceed until I confirm.
4. Create `agents/hello/role.md`:
   - A single H1 "# What this agent does"
   - One short paragraph describing a concise, helpful generalist that calls users "you"
5. Create `agents/hello.ts` calling `defineAgent({...})`:
   - name: 'Hello'
   - modelClass: 'standard'
   - spec: ['./hello/role.md']     // relative path; CLI resolves at configure time
   - triggers: [{ kind: 'chat' }]
6. Add package.json scripts:
   - "agent:configure": "agentnava-kit configure agents/hello.ts"
   - "agent:test": "agentnava-kit test agents/hello.ts"
   - "agent:deploy": "agentnava-kit deploy agents/hello.ts"
7. Run `agent:configure` to upload the spec + metadata. Print whatever the CLI returns.
8. Run `agent:test`. The CLI returns a URL of the form `https://.test.agents.agentnava.com`. Wait for it.
9. Curl-test the chat endpoint at that URL with a sample message; show the streaming SSE output.
10. Print a one-paragraph summary of what was installed, the test URL, and what to try next. Do NOT run `agent:deploy` — that's production and the user does it explicitly.

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

Or do it by hand

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

agentnava-kit login

# opens https://agentnava.com/cli/auth in your browser.
# pick a workspace; the CLI saves a token to ~/.agentnavakit/credentials.

export AGENTNAVAKIT_API_KEY=sk_live_…
# generate one at agentnava.com → Settings → API keys

// agents/hello/role.md
# What this agent does

You are a concise, helpful generalist. Answer in two paragraphs max unless the user asks for detail. Always address the user as "you".

// agents/hello.ts
import { defineAgent } from '@agentnava/kit';

export default defineAgent({
  name: 'Hello',
  modelClass: 'standard',
  spec: ['./hello/role.md'],
  triggers: [{ kind: 'chat' }],
});

agentnava-kit configure agents/hello.ts

# uploading 1 spec file...
# ✓ hello/role  (215 bytes)
# ✓ configuration draft saved for agent 'Hello'

agentnava-kit test agents/hello.ts

# ✓ test instance ready at:
#   https://<temp-id>.test.agents.agentnava.com
# streaming events. ctrl-c to stop.

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

agentnava-kit deploy agents/hello.ts

# ✓ deployed v1 — promoted to production
#   https://hello.agents.agentnava.com
# embed snippet: <script src="..."></script>

Spec

An agent has two parts. The Spec — one or more .md files that describe what the agent does, how it talks, and what it won't do. The wiring — a TypeScript object that hooks the Spec up to a model, triggers, integrations, knowledge, and tools.

Why multiple .md files

Behavior is rarely one paragraph. Splitting the Spec into multiple files keeps each one focused, reviewable, and reusable:

• By concern — separate what the agent does from how it talks from what it won't do. Changing tone shouldn't require re-reading the role file.
• By owner — your legal team owns off-limits.md; product owns role.md; design owns tone.md. Each PR's diff lives where the reviewer expects it.
• By reusability — one shared/legal-off-limits.md file can be referenced by every agent in your workspace. Change it once; every agent picks it up on next deploy.

The runtime concatenates the files in the order you list them — that becomes the agent's instructions.

The agent lifecycle

An agent moves through three stages. Each is one CLI command — they're all the same operation under the hood, just with different persistence and versioning rules.

Test and deploy do the same thing — run your agent on the backend with the current configuration. The only difference: deploy persists + bumps the version, test doesn't.

The workflow

agents/
  concierge/
    role.md
    tone.md
    off-limits.md
  concierge.ts          // calls defineAgent({...})

// agents/concierge.ts
import { defineAgent, connect } from '@agentnava/kit';

export default defineAgent({
  name: 'BayHomes Concierge',
  modelClass: 'standard',
  spec: [
    './concierge/role.md',
    './concierge/tone.md',
    './concierge/off-limits.md',
  ],
  triggers: [{ kind: 'chat' }],
  connections: [connect.slack({ workspace: 'bayhomes' })],
  sources: [{ kind: 'documents', uploadable: true }],
});

agentnava-kit configure agents/concierge.ts

# uploading 3 spec files...
# ✓ concierge/role          (482 bytes)
# ✓ concierge/tone          (211 bytes)
# ✓ concierge/off-limits    (318 bytes)
# ✓ configuration draft saved for agent 'BayHomes Concierge'

agentnava-kit test agents/concierge.ts

# ✓ test instance ready at:
#   https://<temp-id>.test.agents.agentnava.com
# streaming events. ctrl-c to stop.

agentnava-kit deploy agents/concierge.ts

# ✓ deployed v4 — promoted to production
#   https://bayhomes-concierge.agents.agentnava.com
#   previous version v3 kept warm during health check

What the .md files look like

concierge/role.md
# What this agent does

Answers questions from prospective Bay Area buyers about BayHomes listings, school districts, and visit times.

It calls users "you" and always cites a listing ID when discussing a specific home.

concierge/tone.md
# How it talks

Friendly. Direct. Never pushy.

Two paragraphs max per reply unless the buyer asks for detail.

concierge/off-limits.md
# What it will not do

- Quote final or specific pricing — always defer to a human agent.
- Give legal advice.
- Share information about other clients.

When asked anything in this list, say so plainly and offer to connect the buyer with a human.

At a glance

Fields

name: 'BayHomes Concierge'

description: 'Embedded chat for prospective Bay Area buyers — listings, schools, viewings.'

spec: [
  'concierge/role',
  'concierge/tone',
  'shared/legal-off-limits',     // re-used across many agents
]

modelClass: 'standard'           // rolling — auto-upgrades over time
modelClass: 'standard@2026-05'   // pinned to the May 2026 snapshot, forever
modelClass: 'premium@v3'         // pinned to integer release v3

triggers: [
  { kind: 'chat' },
  { kind: 'webhook' },
  { kind: 'schedule', cron: '0 7 * * 1-5' },
  { kind: 'loop', everySeconds: 600, maxRuns: 24 },
  { kind: 'manual' },
]

import { connect } from '@agentnava/kit';

connections: [
  connect.slack({ workspace: 'acme' }),
  connect.gmail({ account: '[email protected]' }),
  connect.mcp({ url: 'https://mcp.linear.app/sse' }),
]

sources: [
  { kind: 'documents', uploadable: true },                          // users/devs upload at runtime
  { kind: 'documents', uri: './docs', uploadOnDeploy: true },       // CLI uploads this folder on deploy
  { kind: 'website', url: 'https://example.com/help', depth: 2 },   // crawled at deploy + on a schedule
  { kind: 'mcp', url: 'https://mcp.linear.app/sse' },               // MCP server tools become callable
]

import { defineTool } from '@agentnava/kit';
import { object, string } from 'valibot';

const lookupZestimate = defineTool({
  name: 'lookup_zestimate',
  description: 'Get the Zillow zestimate for an address',
  inputSchema: object({ address: string() }),
  handler: async ({ address }) => {
    // implementation
  },
});

tools: [lookupZestimate]

Uploading documents

A documents source needs files. Three ways to get them in:

• At deploy. Add uri: './docs' + uploadOnDeploy: true to the source. The CLI uploads the folder when you run agentnava-kit deploy. Re-deploy to refresh.
• From a script. Use the upload endpoint to push files programmatically from a backend.
• From your UI. Drop in the upload widget so end-users (or your own admins) can attach files after the agent is deployed.

HTTP upload

POST https://<agent-id>.agents.agentnava.com/sources/<source-id>/files
Authorization: Bearer <workspace-key>
Content-Type: multipart/form-data

[email protected]
[email protected]

Returns { fileId, status: 'indexing' } per file. Indexing typically completes in 30–90s. The file becomes searchable across the agent's next turn.

CLI

agentnava-kit upload --agent concierge --source handbook ./docs

Convenience wrapper around the HTTP endpoint. Skips files already uploaded with the same content hash.

Embed widget

<script
  src="https://embed.agentnava.com/v1.js"
  data-agent="<agent-id>"
  data-uploads="true"
  defer
></script>

The data-uploads="true" flag adds a file-attach button in the chat composer. Uploaded files become available to that user's conversation and (if the source is shared) to the agent's RAG index.

Event stream

The runtime emits a typed SSE stream the host UI consumes.

type AgentEvent =
  | { type: 'message-start'; messageId: string }
  | { type: 'message-delta'; messageId: string; delta: string }
  | { type: 'message-end'; messageId: string; final: string }
  | { type: 'tool-start'; toolId: string; name: string; input: unknown }
  | { type: 'tool-end'; toolId: string; ok: boolean; result?: unknown; error?: string }
  | { type: 'phase'; label: string; state: 'start' | 'end' }
  | { type: 'error'; message: string }
  | { type: 'done' };

Any consumer that reads SSE can render the stream — React, Vue, Svelte, vanilla JS, a CLI. No framework lock-in.

Advanced

meta: {
  deployTarget: 'embed',
  brandColor: '#B91C1C',
  region: 'eu-west',
}

Connections

A connection wires an agent to a third-party service in one declaration. It handles auth, auto-registers a set of tools, and may add a trigger. Most agents only need connections — never individual defineTool calls.

Add the Slack connection to the AgentNavaKit agent in this project.

1. Locate the agent's TS file (likely `agents/*.ts` calling `defineAgent({...})`).
2. Import `connect` from `@agentnava/kit` if not already imported.
3. Add `connect.slack({ workspace: '' })` to the `connections` array. Ask me for the workspace slug if you can't infer it.
4. Run `agentnava-kit auth slack`, print the OAuth URL it returns, and wait for me to authorize it in the browser.
5. Once authorized, run `agentnava-kit configure .ts` to push the updated configuration.
6. Run `agentnava-kit test .ts` and verify the agent can call `post_message` to a test channel.

Reference: https://docs.agentnava.com#connections
Don't deploy to production. Don't touch unrelated agents.

Catalog

How it looks in a spec

import { defineAgent, connect } from '@agentnava/kit';

export default defineAgent({
  name: 'Inbound triage',
  modelClass: 'standard',
  spec: ['triage/role'],
  triggers: [{ kind: 'chat' }],
  connections: [
    connect.slack({ workspace: 'acme' }),
    connect.gmail({ account: '[email protected]' }),
    connect.hubspot({ portalId: 12345 }),
  ],
});

The agent now has nine new tools and a Slack mention trigger, with zero credential handling in the spec.

Sessions

Once an agent is deployed, end users interact with it through sessions. Each session is one user's ongoing conversation — its own message history, its own attached files, its own state. A single deployed agent serves many concurrent sessions in parallel; each one is independent.

How sessions get created

• Embed widget. Mounting <script src="https://embed.agentnava.com/v1.js" data-agent="…"> on a page creates one session per browser tab automatically. The session ID is persisted in localStorage so the user can refresh and resume.
• Your own UI. Call POST /agents/<id>/sessions to mint a session ID, then use it on every subsequent chat call.
• Implicit (single-turn). Hit POST /chat directly without a session ID — the runtime mints a one-shot session that's torn down after the response.

The chat protocol

To send a turn to an existing session:

POST https://<agent-url>/sessions/<session-id>/messages
Authorization: Bearer <public-token>
Content-Type: application/json

{
  "role": "user",
  "content": "Can you walk me through this floor plan?",
  "attachments": [
    { "id": "file_4f1c9a", "type": "image", "name": "floor-plan.png" },
    { "id": "file_2a9d12", "type": "file",  "name": "hoa-rules.pdf"  }
  ]
}

Response is an SSE stream of AgentEvents — message-delta chunks, then message-end, plus any tool-start/tool-end/phase events the agent emits along the way.

Attachments

An attachments entry references a file the user already uploaded for this session. Two ways to put files there:

// 1. Upload a file to a session — returns a file ID you attach to messages
POST https://<agent-url>/sessions/<session-id>/files
Authorization: Bearer <public-token>
Content-Type: multipart/form-data

[email protected]

// → { "id": "file_4f1c9a", "type": "image", "status": "ready" }

// 2. The embed widget does this automatically when the user drops a file
//    into the chat composer (if data-uploads="true" is on the script tag).

Attached files live for the lifetime of the session. They're not added to the agent's RAG index — they're transient context for that one conversation. (For persistent knowledge, use document upload on a documents source instead.)

Session lifecycle

Querying sessions

GET https://<agent-url>/sessions/<session-id>/messages
# → full message history, newest first

GET https://<agent-url>/sessions?since=2026-05-10T00:00:00Z
# → list of recent sessions (workspace-scoped, requires a workspace token)

For analytics, the workspace dashboard surfaces session counts, average turn count, common handoff reasons, and per-version metrics.

Operate

Deploy an agent, point a custom domain at it, embed it on a webpage, and route model calls through your own cloud account.

Deploy

agentnava-kit deploy agents/hello.ts

The CLI returns:

• Public URL — https://<agent-id>.agents.agentnava.com
• Version number — auto-incremented integer (v1, v2, …)
• Embed snippet — one-line <script> tag for any webpage
• Webhook URL — for webhook triggers
• Health URL — https://<agent-id>.agents.agentnava.com/health

Deploys are atomic per agent. Each one stamps a new version and promotes it to production. The previous version stays warm until the new one passes a health check.

Versions & rollback

agentnava-kit versions hello            # list every version of the agent
agentnava-kit rollback hello --to v3    # immediately re-point production to v3

Rollback is instant — versions stay queryable as long as the agent exists. Spec content and TS metadata for every shipped version is preserved.

Custom domain

Map agent.yourdomain.com to the agent's public URL via CNAME, then run:

npx agentnava-kit domain add agent.yourdomain.com --agent hello

The runtime provisions a managed TLS cert and serves the agent there.

Embed snippet

<script
  src="https://embed.agentnava.com/v1.js"
  data-agent="<agent-id>"
  data-theme="auto"
  defer
></script>

Drops in any HTML page. data-theme accepts light, dark, or auto.

BYOK — bring your own keys

Route inference through your cloud account. The runtime still runs on AgentNava; only model calls hit the chosen provider. Credentials attach once at the workspace level and are validated with a probe call before any agent uses them.

defineAgent({
  // ...
  provider: 'auto',   // or omit entirely
});

npx agentnava-kit byok bedrock \
  --access-key AKIA... \
  --secret-key ... \
  --region us-west-2

defineAgent({
  // ...
  provider: 'bedrock',
});

npx agentnava-kit byok azure-openai \
  --resource my-resource \
  --api-key ...

defineAgent({
  // ...
  provider: 'azure-openai',
});

npx agentnava-kit byok vertex \
  --service-account ./sa.json \
  --project my-gcp \
  --region us-central1

defineAgent({
  // ...
  provider: 'vertex',
});

npx agentnava-kit byok openrouter --api-key sk-or-...

defineAgent({
  // ...
  provider: 'openrouter',
});

Regions

Agents deploy to the region closest to the workspace owner by default. Override per agent:

meta: { region: 'eu-west' }

Supported: us-west, us-east, eu-west, eu-central, ap-southeast.

Billing

The runtime is charged per workspace plan; model usage is metered separately. With provider: 'auto', model calls are billed by AgentNava. With BYOK, they're billed by your cloud provider. Plan details and pricing are on agentnava.com/pricing.