> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ceramic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK

> Use Ceramic Search within the Vercel AI SDK

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

## Installation

```bash theme={null}
npm install @ceramicai/sdk ai @ai-sdk/openai
```

## API keys

Get your Ceramic API key and export it:

<Card title="Get API Key" icon="key" href="https://platform.ceramic.ai/keys" arrow="true">
  Create a Ceramic account for free to get an API key.
</Card>

```
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

```typescript theme={null}
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:

```json theme={null}
{ "type": "module" }
```

Then run:

```bash theme={null}
npx tsx example.ts
```

## Configuration

```typescript theme={null}
webSearch({
  apiKey: 'your_api_key',       // defaults to process.env.CERAMIC_API_KEY
  maxDescriptionLength: 3000,   // 1000–8000, defaults to 3000
})
```

| Option                 | Type     | Default                       | Description                                       |
| ---------------------- | -------- | ----------------------------- | ------------------------------------------------- |
| `apiKey`               | `string` | `process.env.CERAMIC_API_KEY` | Your Ceramic API key                              |
| `maxDescriptionLength` | `number` | `3000`                        | Max characters per result description (1000–8000) |

## Result shape

Each search call returns:

```typescript theme={null}
{
  requestId: string;
  results: Array<{
    title: string;
    url: string;
    description: string;
  }>;
  totalResults: number;
  executionTime: number; // seconds
}
```

<Columns cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/CeramicTeam/ceramic-ai-sdk" arrow="true">
    View source code
  </Card>

  <Card title="npm" icon="npm" href="https://www.npmjs.com/package/@ceramicai/sdk" arrow="true">
    View package
  </Card>
</Columns>