Spec & agent versions

The agent's core instructions — what it does, how it talks, what it won't do. The CLAUDE.md equivalent. Always sent to the model. One per spec.

# agents/concierge/AGENT.md
# BayHomes Concierge

You help prospective buyers explore listings.
Address the user as "you". Keep replies under two paragraphs unless asked.
Never quote a final price — always defer to a human agent for pricing.

A focused, auto-invokable module the agent loads when the description matches the user's request. YAML frontmatter is the same as Claude Code skills — name, description, allowed-tools, model. Drop existing Claude Code skills in unchanged.

# agents/concierge/skills/format-listing/SKILL.md
---
name: format-listing
description: Format a property listing card with price, beds, sqft, and one-line pitch
allowed-tools: [Read, lookup_zestimate]
---
When showing a listing, render…

The platform also bundles built-in capabilities (file ops, web search, structured-output helpers, etc.) that work without any declaration.

A multi-step playbook the agent runs end-to-end — e.g. "morning digest", "weekly report", "intake → qualify → handoff". Frontmatter declares the trigger (chat-keyword, schedule, webhook) and required connections. Every workflow has full access to the agent's Knowledge base and Connections — no extra wiring.

# agents/concierge/workflows/morning-digest.md
---
name: morning-digest
description: Daily 7am email summarizing new listings + price changes
trigger: { kind: schedule, cron: '0 7 * * 1-5' }
requires: [gmail, hubspot]
---
1. Query HubSpot for active buyers…
2. Match against new MLS listings…
3. Draft + send digest emails…

A slash command the end user types in chat (/reset, /refresh-kb, /handoff). Same format as Claude Code commands — argument-hint, allowed-tools, optional model.

# agents/concierge/commands/handoff.md
---
description: Hand the conversation off to a human agent
argument-hint: "[reason]"
---
Tell the user a human will follow up about $ARGUMENTS, then emit a handoff event.

A dev-chosen, stable identifier for this agent in your workspace. The backend uses it to upsert — first configure with a new key creates the agent (and assigns an opaque agt_… ID); later calls with the same key update the existing one.

key: 'bayhomes-concierge'

You control key. The backend controls agentId. Use key in source code; use agentId for sessions, deploys, and rollbacks at runtime.

What users address the agent as in chat (e.g. "Hey Concierge, …") and how it introduces itself. Also appears in the workspace header, embed widget, and catalog cards — but the conversational identity is what matters.

name: 'BayHomes Concierge'

The Spec object you got from an.specs.push(...), or its ID + version as a string ('spec_4f1c9a@v2'). The agent version pins to whichever spec version you pass — re-pushing the spec doesn't change deployed agents.

spec  // pass the object directly
// or
spec: 'spec_4f1c9a@v2'
// or
spec: 'spec_4f1c9a'   // resolves to latest at configure time, then pinned

One or more Knowledge bases for RAG (.md, .pdf, .txt, images). The runtime indexes them and retrieves relevant chunks on every turn. The agent and every workflow, subagent, and skill it spawns always have full access — you do not need to re-declare it anywhere. Pin to specific KB versions the same way as Spec.

knowledge: [kb, 'kb_legal@v5']

End users (or you, post-deploy) can also upload files into a Knowledge base — see Knowledge.

How much reasoning the agent applies on each turn. Higher classes think longer, can chain more tool calls before replying, and cost more.

Pin a snapshot if you want behavior frozen across model upgrades:

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

The role this agent plays for its user. AgentNavaKit infers the compute model and persistence from it — you don't pick those directly. The choice doesn't change how you write the spec; it changes which tools become available, whether state survives between sessions, and how the platform organises the agent inside a team.

// loadAgentDir option:
const input = loadAgentDir('./agents/code-reviewer', {
  key: 'code-reviewer',
  role: 'teammate',
});
// or explicit on the SpecInput:
const spec = await an.specs.push({
  key: 'code-reviewer',
  instructions: '…',
  role: 'teammate',
});

Teammate / Manager sessions get a persistent workspace at /workspace. When the session goes idle, the underlying container hibernates — cost drops to storage only.

The team this agent belongs to. Teams group related agents — a Manager and its Teammates always live in the same team, and the Manager's Delegate tool only sees Teammates that share its team. Workspaces start with a single default team, so most setups never need to pass this explicitly.

const v = await an.agents.configure({
  key: 'researcher',
  name: 'Researcher',
  modelClass: 'standard',
  spec,
  triggers: [{ kind: 'chat' }],
  // teamId omitted — joins the default team.
});

// Or stamp explicitly:
await an.agents.configure({
  key: 'marketing-writer',
  // ...
  teamId: 'tm_marketing',
});

The platform auto-spawns a Manager once a team has its second Teammate. Without an explicit teamId, all Teammates join the same default team and the same auto-spawned Manager.

Whose account pays for the model calls. 'auto' bills the managed runtime. Any other value routes inference through your own cloud account — tokens billed there. See Operate → BYOK.

When the agent wakes up. Without at least one trigger, the agent never runs.

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

How sessions are scoped. Think of the agent as someone the user hires — same person, same continuous relationship.

Cron firings on a per-user agent fan out across users. A real-estate assistant with 1,000 active users + cron: '0 9 * * MON' = 1,000 parallel Monday-morning runs, each on its own per-user session. Agents that nobody has interacted with yet don't fire.

When the user sends a message through chat or your code calls an.agents.run(...), pass user: { id: '…' } — that's the join key. On per-user agents the request fails fast if user.id is missing.

OAuth-managed third-party connectors (Slack, Gmail, GitHub, Stripe, …) — coming. Today the same outcomes are reached through mcpServers + declarative HTTP tools; the connector layer will sit on top of those primitives once the OAuth flow ships. See Connections.

HTTP/SSE Model Context Protocol servers the agent connects to at session start. Every tool the MCP server advertises becomes a callable tool for the model, namespaced as <server-name>__<tool>. Header values may reference workspace secrets so auth tokens never live in the spec.

mcpServers: [
  // public MCP server, no auth
  { name: 'echo', url: 'https://mcp.example.com/echo' },

  // authenticated — secret name is resolved at session start
  {
    name: 'linear',
    url: 'https://mcp.linear.app/sse',
    transport: 'sse',
    headers: { Authorization: 'Bearer {{secrets.LINEAR_TOKEN}}' },
  },
]

If you keep your spec as a folder, drop a mcp-servers.json file alongside AGENT.md with the same array — loadAgentDir picks it up automatically. Stdio MCP servers are not supported (the runtime can't spawn subprocesses).

Names of workspace secrets the agent declares it needs. Where you actually see them depends on the runtime:

• HTTP tools and MCP headers use the {{secrets.NAME}} placeholder — the runtime substitutes the decrypted value at call time.
• Teammate / Manager roles additionally expose every declared secret as a real environment variable inside the container, so a Bash call can read $TOKEN directly (e.g. git clone https://x-access-token:$GITHUB_TOKEN@github.com/…).

secrets: ['GITHUB_TOKEN', 'STRIPE_KEY']

Set the actual values once in the workspace console. Only the names listed here are exposed — never the full workspace secret store.

Custom functions you write in TypeScript. The agent decides when to call them. Use this for behavior no connection covers — calling your internal API, computing something, or hitting a SaaS the catalog doesn't yet support.

import { defineTool, t } from '@agentnava/kit';

const lookupZestimate = defineTool({
  name: 'lookup_zestimate',
  description: 'Get the Zillow zestimate for an address',
  input: t.object({ address: t.string() }),
  handler: async ({ address }, ctx) => {
    // ctx.secrets, ctx.sessionId, ctx.user available here
  },
});

tools: [lookupZestimate]

Pre-packaged bundles of skills, subagents, commands, and MCP servers — installed once at the workspace and referenced by name. Claude Code plugins (.claude-plugin/plugin.json) install unchanged: an.plugins.install('github:owner/repo#v1'), then list them here.

plugins: ['claude-code-review', 'pr-helper@v2']

Event hooks fired by the runtime around the agent loop. Same event names and shape as Claude Code hooks — PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionStart. Use them for audit logging, PII scrubbing, or gating risky tool calls.

hooks: [
  { event: 'PreToolUse',  match: { tool: 'Bash' }, run: async (ctx) => { /* approve or block */ } },
  { event: 'PostToolUse', match: { tool: '*' },    run: async (ctx) => { /* log */ } },
]

Whitelist of built-in tools the agent (and its subagents) can call. If unset, every built-in is available. Built-ins mirror Claude Code: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite.

allowedTools: ['Read', 'WebSearch', 'Task']
// disallowedTools also accepted

How aggressively the agent is allowed to act without confirmation. Same semantics as Claude Code's permission modes — default asks for risky tool calls, acceptEdits auto-approves file edits, plan only proposes, bypass never asks. Surface a UI affordance to your users if you change this from default.

Anything you set here is readable from tool handlers via ctx.meta.X. Use it for per-deploy config the agent doesn't reason about — brand colors, deploy targets, feature flags.

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