Skip to main content

​
Overview

The @nimble-way/ai-sdk package provides pre-built tools for Vercel’s AI SDK v6, making it easy to add real-time web search and page extraction to your AI applications. Register nimbleSearch() or nimbleExtract() on an agent and the model decides when to search the web or read a page, runs the request through Nimble, and gets back clean, structured results to cite.
  • Two tools, zero boilerplate — drop nimbleSearch() and nimbleExtract() into your agent and you’re done.
  • Works with any model — OpenAI, Anthropic, Google, and others supported by the AI SDK.
  • Two search depths — lite for fast metadata, deep for full page content.
  • Type-safe — written in TypeScript with typed options and output.
Ships Web Search and Extract. Map, Crawl, and Agents are planned as follow-ups.

​
Quick Start

1

Install

npm install @nimble-way/ai-sdk ai @ai-sdk/openai
ai (v6) and zod are peer dependencies. The examples use OpenAI via @ai-sdk/openai, but nimbleSearch works with any AI SDK model provider.
2

Set your API keys

Get a Nimble key from the dashboard (free trial available), then set both keys:
export NIMBLE_API_KEY="your-api-key"
export OPENAI_API_KEY="your-openai-api-key"
You can also pass the Nimble key inline: nimbleSearch({ apiKey: '...' }).
3

Add the tool to an agent

import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { nimbleSearch } from '@nimble-way/ai-sdk';

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'What are the latest developments in agentic web search? Cite sources.',
  tools: {
    webSearch: nimbleSearch({ searchDepth: 'lite', maxResults: 5 }),
  },
  stopWhen: stepCountIs(3),
});

console.log(text);

​
How it works

1

The model receives the tool

nimbleSearch() registers a webSearch tool the model can call when it needs current information.
2

The model decides to search

When the prompt needs live data, the model emits a tool call with a query (and optional maxResults).
3

Nimble runs the search

The query goes to Nimble’s Web Search API, which returns clean, structured results.
4

The model answers

Results are fed back to the model, which uses them to write a grounded, citable answer. stopWhen: stepCountIs(n) caps how many search rounds a single turn can take.
Use stepCountIs — not isStepCount. The latter does not exist in ai v6. Set it on every agent to prevent runaway loops and unbounded cost: 3–5 for chat, higher for autonomous agents.

​
Next.js route handler

For a streaming chat app, swap generateText for streamText inside a route handler and return toUIMessageStreamResponse(). The client connects with the AI SDK useChat hook — no extra wiring needed. 
// app/api/chat/route.ts
import {
  convertToModelMessages,
  streamText,
  stepCountIs,
  type UIMessage,
} from 'ai';
import { openai } from '@ai-sdk/openai';
import { nimbleSearch } from '@nimble-way/ai-sdk';

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: openai('gpt-5'),
    messages: await convertToModelMessages(messages),
    tools: {
      webSearch: nimbleSearch({ searchDepth: 'lite', maxResults: 5 }),
    },
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}

​
Configuration options

Configure nimbleSearch() once; the model only ever supplies { query, maxResults? }.
Nimble API credentials. Defaults to process.env.NIMBLE_API_KEY.
'lite' returns metadata only (fast); 'deep' returns full page content. Default 'lite'.
Default number of results per search. Type number, default 5.
Hard upper limit on results the model can request. Type number, default 10.
Per-result content truncation, in characters. Type number, default 10_000.
Two-letter country code for localization. Type string, default 'US'.
Language preference. Type string, default 'en'.
Injectable NimbleSearchClient for testing. Optional.

​
Response shape

Each tool call returns a structured result the model can reason over: 
{
  query: string;
  requestId?: string;
  totalResults?: number;
  results: Array<{
    title: string;
    url: string;
    description?: string;
    content?: string;     // deep searches only
    position?: number;
    entityType?: string;
  }>;
}

​
Extract

nimbleExtract() registers an extract tool that takes a single URL and returns clean page content — markdown by default — for the model to read, quote, or summarize. The model only ever supplies { url }; all policy below is developer-controlled. 
import { generateText, stepCountIs } from 'ai';
import { nimbleExtract } from '@nimble-way/ai-sdk';

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Summarize https://en.wikipedia.org/wiki/Web_scraping',
  tools: { extract: nimbleExtract({ format: 'markdown' }) },
  // Allow a step after the tool call so the model can read the page.
  stopWhen: stepCountIs(2),
});

console.log(text);
Register both tools together so the model can search, then read the best result: 
tools: {
  webSearch: nimbleSearch(),
  extract: nimbleExtract(),
}

​
Configuration options

Configure nimbleExtract() once; the model only ever supplies { url }.
Nimble API credentials. Defaults to process.env.NIMBLE_API_KEY.
Content format returned to the model: 'markdown' or 'html'. Default 'markdown'.
Two-letter ISO country code for geolocation / proxy. Type string, optional.
Extracted content truncation, in characters. Type number, default 50_000.
Injectable NimbleExtractClient for testing. Optional.

​
Response shape

{
  url: string;
  status: string;        // e.g. 'success'
  statusCode?: number;
  format: 'markdown' | 'html';
  content: string;       // truncated to maxContentLength
  links?: string[];
}

​
Limitations

  • Web Search and Extract ship today — Map, Crawl, and Agents are planned follow-ups.
  • No built-in answer generation — the tool returns results; the model writes the answer.
  • Node.js runtime (≥18) is the supported target; edge/serverless compatibility is unverified.

​
Resources

npm Package

@nimble-way/ai-sdk on npm.

GitHub Repository

Source, README, and issues.

Web Search API

Nimble’s underlying search capability.

Extract API

Nimble’s underlying page extraction capability.

Example Cookbook

Runnable integration examples.