Operate

How sessions relate to users

Think of the agent as someone the user hires. Each user gets their own continuous relationship — same history, same knowledge-base notes, same persistent workspace state if the agent's role is teammate or manager. That model is the default and is controlled by sessionMode on agents.configure(...).

Cron + per-user

A schedule trigger on a per-user agent fans out across every user who's interacted. One user (you) running a trading agent = one cron firing on your continuous thread. A real-estate assistant with 1,000 active users + cron: '0 9 * * MON' = 1,000 parallel Monday-morning runs, each on its own user's session. Cron firings on agents that nobody has interacted with yet are a no-op — the agent hasn't been hired by anyone.

When sessions end

Sessions don't end on their own under normal use. Three things can release one:

• Explicit close — an.sessions.close(sessionId). Rare. Useful for "start fresh" resets, end-of-test cleanup, admin tooling.
• Agent version deletion — cascades to every session that pinned to it.
• Inactivity TTL — 90 days for per-user, 5 minutes for per-call. The 90-day rule only matters once you have a long tail of abandoned users; until then, idle sessions hibernate at storage-only cost.

For teammate and manager roles, the agent's container hibernates between turns. State on disk survives — files, cloned repos, installed packages all persist as long as the session does.

Deploy to test and to prod

Configure creates an agent version (a snapshot). Deploying that version runs it on the backend. You pick the destination:

// the configure call returned:
//   const v = { agentId: 'agt_2b8e', versionId: 'ver_3c5f' }

// dev-only URL — no end-user traffic, ephemeral
const test = await an.agents.deployToTest(v.versionId);
// → { url: 'https://<temp>.test.agents.agentnava.com', expiresAt: '…' }

// production URL — end users hit this
const prod = await an.agents.deployToProd(v.versionId);
// → { url: 'https://<agent-name>.agents.agentnava.com', versionNumber: 4 }

Both calls are idempotent on the version ID. deployToProd promotes the version atomically and keeps the previous one warm until the new one passes a health check. Skip deployToTest if you don't need a dev-only environment.

Versions & rollback

// list every version of this agent (newest first)
const versions = await an.agents.versions('agt_2b8e');
// → [{ id: 'ver_3c5f', number: 4, deployedAt: '…', isProd: true }, …]

// instant rollback to a previous version
await an.agents.rollback('agt_2b8e', 'ver_9a1b');

Rollback is instant — every version's spec content and configuration is preserved as long as the agent exists.

Custom domain

Map agent.yourdomain.com to the agent's public URL via CNAME, then attach it in code:

await an.domains.add({
  domain:  'agent.yourdomain.com',
  agentId: 'agt_2b8e',
});

The runtime provisions a managed TLS cert and serves the agent at that domain within a minute.

Embed snippet

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

Drops into any HTML page. The widget creates a session automatically on first message and resumes it across reloads (session ID in localStorage). data-theme accepts light, dark, or auto. Add data-uploads="true" to enable end-user file attachments.

BYOK — bring your own keys

Route model traffic through your own provider account instead of AgentNava's. Useful once usage scales past the free tier, when you want one billing relationship across services, or when compliance requires inference in your own VPC/region.

Configuration is done from the console — not the SDK. Open console.agentnava.com → BYOK, pick a provider, paste credentials, mark as default. Agent code is unchanged.

Two scopes: workspace defaults vs per-agent overrides

BYOK has two levels and you can mix them:

• Workspace default — applies to every agent in the workspace. The most common setup: one key per provider, used by everyone.
• Per-agent override — a key you attach to a single agent. When that agent runs, its override wins; every other agent stays on the workspace default.

The Scope chip row at the top of console.agentnava.com/byok switches between them. "Workspace defaults" is the standard list; clicking an agent's chip shows the resolved view for that agent — workspace rows plus overrides, with a Source column saying where each row came from and overridden workspace rows visibly struck through. What you see is exactly what the runtime will use for that agent's traffic.

Override only what you need. A typical setup uses one workspace default (say, Anthropic via your prod account) and zero or one agents that need a sandbox/staging key.

Supported providers

How it works

1. Provider creds are encrypted at rest with AES-256-GCM. We decrypt only at request time, inside the worker, and never log the plaintext.
2. For every chat turn the runtime resolves which key wins in this order: agent override → workspace default → AgentNava's managed inference. The first hit wins; no implicit cascade beyond that.
3. Generic modelClass values on agents (fast, standard, premium, advanced) translate to provider-specific model IDs automatically — e.g. standard on Bedrock becomes anthropic.claude-3-haiku-20240307-v1:0, on OpenAI becomes gpt-4o-mini. Pin a specific id with tier@model-id when the default isn't what you want.
4. If the resolved BYOK provider returns an error, the request fails — there's no silent fallback to a different scope or to platform pricing. Surprises lead to surprise bills.
5. Remove an override or the workspace default any time; the next request resolves with one fewer level.

Test the connection

The Test connection button on each row makes one validation call (timeout 6s) and stores the result. Status pill on the table:

• Live — last test succeeded.
• Failing — last test failed. Hover for the upstream error.
• Untested — fresh row, never tested.

Test on save plus whenever you suspect the upstream account changed (rotated key, billing on hold, quota hit).

Regions

Agents deploy to the region closest to the workspace owner by default. Override on a per-agent basis via meta:

await an.agents.configure({
  // ...
  meta: { region: 'eu-west' },
});

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

Plan changes and your agents

Changing your plan adjusts existing Teammates and Managers to the capabilities of the new plan automatically. The change lands within seconds of the Stripe webhook firing — no re-deploy needed.

The per-session filesystem on the previous backend is not carried over; that's ephemeral compute scratch space, not your data. Knowledge base entries, journal entries, and session history live in the platform's data store and are unaffected.

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.