Migrating from Tavily to Naive

• Retrieval lives behind a Tavily API key (tvly-...) — a credential that exists only inside Tavily, unrelated to where the same agent’s cards, email, and KYC live.
• Whether the agent may search, and how much it may spend doing so, is not something Tavily governs at execution time — it is a key you hold. There is no “can this agent research right now?” check tied to the agent’s broader permission set.
• “Which agent ran this query, for which end-user, and who let it?” is answered in Tavily’s usage dashboard for search, and in unrelated systems for the agent’s spend, comms, and identity.

• The Account Kit that decides whether the agent may issue a card or send email also decides whether it may use search at all — checked at execution time, not in a separate dashboard.
• Search spend is metered in the same credit balance and budget ceiling as every other primitive, so a runaway agent hits one cap, not a separate Tavily bill.
• Every query records the acting agent and lands in the same activity log as its card spend, email sends, and KYC events.

​

Concept map

​

Before / after: the core path

import { tavily } from "@tavily/core";

// One account-wide API key. It is unrelated to where this agent's card,
// inbox, phone, and KYC live — and whether the agent "may search" is a key
// you hold, not a governed, execution-time decision.
const tvly = tavily({ apiKey: process.env.TAVILY_API_KEY! });

// 1. Search (POST /search)
const search = await tvly.search("AI agent frameworks comparison 2026", {
  maxResults: 5,
});

// 2. Read the top result (POST /extract)
const top = search.results[0];
const extract = await tvly.extract([top.url]);
const content = extract.results[0]?.rawContent ?? "";

// No dedicated search sub-client yet — call the primitive over REST.
// The same NAIVE_API_KEY reaches cards, email, phone, vault, and KYC.
const auth = { Authorization: `Bearer ${process.env.NAIVE_API_KEY}` };
const json = { ...auth, "Content-Type": "application/json" };

// 1. Search (POST /v1/search) — `count` maps to Tavily `maxResults`
const searchRes = await fetch("https://api.usenaive.ai/v1/search", {
  method: "POST",
  headers: json,
  body: JSON.stringify({ query: "AI agent frameworks comparison 2026", count: 5 }),
});
const { results } = await searchRes.json(); // [{ title, url, snippet }]

// 2. Read the top result (POST /v1/search/url) — one URL per call
const urlRes = await fetch("https://api.usenaive.ai/v1/search/url", {
  method: "POST",
  headers: json,
  body: JSON.stringify({ url: results[0].url, extract: "key takeaways" }),
});
const { content } = await urlRes.json();

// Whether this agent may search at all is its Account Kit's `search` primitive,
// checked at execution time; each call spends 0.2 credits against the SAME budget
// ceiling as its cards, email, and phone — and the query is logged against the
// acting agent.

• maxResults → count. Both cap at 20; Naive defaults to 5.
• Result field rename. Tavily’s per-result content snippet becomes snippet on Naive; Naive’s response is { title, url, snippet } and does not include score or rawContent.
• extract reads one URL. Tavily’s extract accepts up to 20 URLs per call; Naive’s read_url takes a single url (loop if you have several), plus an optional extract focus prompt that returns an AI-narrowed extracted field.
• Synthesis is a separate call. Where you’d set Tavily include_answer: true, call Naive POST /v1/search/research for a cited, multi-source answer (see below).

​

The synthesis path

const tvly = tavily({ apiKey: process.env.TAVILY_API_KEY! });

// A quick one-line LLM answer alongside the results.
const res = await tvly.search("GTM strategies for AI dev tools in 2026", {
  includeAnswer: true, // or compose results with your own LLM
});
console.log(res.answer, res.results);

const json = {
  Authorization: `Bearer ${process.env.NAIVE_API_KEY}`,
  "Content-Type": "application/json",
};

// `quick` returns inline; `thorough`/`exhaustive` return a job to poll.
const res = await fetch("https://api.usenaive.ai/v1/search/research", {
  method: "POST",
  headers: json,
  body: JSON.stringify({
    query: "GTM strategies for AI dev tools in 2026",
    depth: "quick",
  }),
});
const { summary, sources } = await res.json(); // sources: [{ title, url }]

​

Minimal viable migration

​

Consolidate further once you’re on Naive

// The tvly key searches; it knows nothing about this agent's money or identity.
const tvly = tavily({ apiKey: process.env.TAVILY_API_KEY! });
await tvly.search("supplier pricing for Q3", { maxResults: 5 });

// The card, inbox, phone, and KYC for this customer's agent live elsewhere —
// separate accounts, separate billing, separate audit — and "may this agent
// search?" is a key you hold, not a governed decision.

// One tenant user per customer; the same handle reaches every primitive.
const acme = await naive.users.create({
  external_id: dbCustomer.id,
  email: dbCustomer.email,
});

// Search over the per-user route — gated + metered like the rest.
await fetch(`https://api.usenaive.ai/v1/users/${acme.id}/search`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NAIVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "supplier pricing for Q3", count: 5 }),
});

// The SAME identity owns this customer's card, inbox, phone, and KYC — one
// account, one budget, one audit trail, every capability governed by its
// Account Kit.
const client = naive.forUser(acme.id);
await client.cards.create({ name: "Ops", spending_limit_cents: 25_000, provider: "managed_virtual" });
await client.email.createInbox({ local_part: "ops" });

​

Gain #1 — one account across primitives

• With Tavily, search is an island behind its own key and credit pool. With Naive, naive.forUser(acme.id) is a single handle to search and cards and email and phone and KYC — no second vendor account, no tvly-... key to provision and rotate, no separate invoice.
• Third-party connections (OAuth grants like Slack or Notion) and the agent’s native primitives sit under one identity and one Account Kit — the SaaS the agent connected and the web it searches, governed the same way.

​

Gain #2 — execution-time permission enforcement

• Whether an agent may search at all is the search primitive on the user’s Account Kit, decided at execution time — not a key you gate separately from everything else the agent can do.

// This tier's agents get email + cards, but cannot use search at all.
const kit = await naive.accountKits.create({
  name: "No-search tier",
  primitives_config: {
    email: { enabled: true },
    cards: { enabled: true },
    search: { enabled: false }, // search calls are refused with `forbidden`
  },
});
await naive.accountKits.assignUser(kit.id, acme.id);

• The agent’s code path stays the same for every tier — the same POST /v1/search. Whether it runs is decided by policy: a user whose Account Kit does not enable search is refused with forbidden (primitive_disabled_by_kit), with no code change on your side.
• Each web_search spends 0.2 credits (read_url 0.05, research 0.5–1.6) against the same budget ceiling as the agent’s cards, phone, and LLM calls — so a misbehaving agent trips one combined cap, not a separate Tavily limit you monitor on its own.

​

Gain #3 — unified accountability

• Every query records the acting agent and lands in one per-user activity log — alongside that customer’s card spend, email sends, and KYC events, not in a separate Tavily usage dashboard:

const { events } = await naive.forUser(acme.id).logs.query({ limit: 50 });
// "what did this agent do, for whom?" — searches, card spend, email sends, one timeline

• That is the question that is hard to answer when queries live in Tavily, cards live in Stripe, and the inbox lives somewhere else. Under Naive it is a single query.

​

What does not map yet

​

Where to go next

• search primitive — full web_search / read_url / research reference, depth levels, and the choose-the-right-tool guide
• search CLI — naive search, naive search url, naive search research
• Account Kits — enabling/disabling the search primitive per user at execution time
• Tenant users — the identity that owns search, cards, email, and phone
• Billing — the shared credit balance and budget ceiling search spends against
• Logs — the unified per-user activity trail every query lands in

​

Related reading (blog)

• Why consolidate agent infra on one governed identity — migration thesis behind this guide
• Building AI Agents Into Your SaaS — tenant user anchor for every migration
• The Governed Agent Profile — governed research and search