Skip to main content
We explain how to integrate Ceramic Search with the Vercel AI SDK to ground agent responses in high-quality web search results.

​
Installation

npm install @ceramicai/sdk ai @ai-sdk/openai

​
API keys

Get your Ceramic API key and export it:

Get API Key

Create a Ceramic account for free to get an API key.
export CERAMIC_API_KEY=your_api_key
Also export any additional API keys you need, e.g., OpenAI: 
export OPENAI_API_KEY=your_api_key

​
Example usage

import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { webSearch } from '@ceramicai/sdk';

const { text } = await generateText({
  model: openai('gpt-5.5'),
  tools: {
    webSearch: webSearch(),
  },
  stopWhen: stepCountIs(5),
  prompt: 'What are the latest developments in AI?',
});

console.log(text);
Save the file as example.ts. In the same directory, create a package.json with: 
{ "type": "module" }
Then run: 
npx tsx example.ts

​
Configuration

webSearch({
  apiKey: 'your_api_key',       // defaults to process.env.CERAMIC_API_KEY
  maxDescriptionLength: 3000,   // 1000–8000, defaults to 3000
})
OptionTypeDefaultDescription
apiKeystringprocess.env.CERAMIC_API_KEYYour Ceramic API key
maxDescriptionLengthnumber3000Max characters per result description (1000–8000)

​
Result shape

Each search call returns: 
{
  requestId: string;
  results: Array<{
    title: string;
    url: string;
    description: string;
  }>;
  totalResults: number;
  executionTime: number; // seconds
}

GitHub

View source code

npm

View package