Skip to main content

​
Overview

The @nimble-way/ai-sdk package provides a pre-built tool for Vercel’s AI SDK v6, making it easy to add real-time web search to your AI applications. Register nimbleSearch() on an agent and the model decides when to search, runs the query through Nimble, and gets back clean, structured results to cite.
  • One tool, zero boilerplate — drop nimbleSearch() 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.
v1 ships Web Search only. 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;
  }>;
}

​
Limitations

  • Web Search only in v1 — Extract, 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.

Example Cookbook

Runnable integration examples.