> For clean Markdown of any page, append `.md` to the page URL.
> Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL).
> Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key).
> Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing.
> OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`.

# Vercel AI SDK

Give your AI applications real-time access to the web through the hosted You.com MCP server. The `@youdotcom-oss/ai-sdk-plugin` package exposes an async `createYouClient()` helper that connects to `https://api.you.com/mcp` and returns the underlying AI SDK MCP client. By default, `await client.tools()` resolves to the default hosted tool set: `you-search`, `you-contents`, `you-balance`, and `you-discover`.

> **Launch**
>
> Starting from scratch? We recommend using Skills, so your agent can build this integration for you. [Learn how](/docs/agents/skills).

---

## Getting Started

### Install the Package

```bash
# NPM
npm install @youdotcom-oss/ai-sdk-plugin ai

# Bun
bun add @youdotcom-oss/ai-sdk-plugin ai

# Yarn
yarn add @youdotcom-oss/ai-sdk-plugin ai
```

### Set Your API Key

```bash
export YDC_API_KEY="<YDC_API_KEY>"
```

Get your API key at [you.com/platform](https://you.com/platform). Set your model provider credentials (e.g. `ANTHROPIC_API_KEY`) separately.

### Add Tools to Your Application

Import `createYouClient()`, await the MCP-backed client, then resolve tools from that client for your AI SDK call:

```typescript
import { createAnthropic } from '@ai-sdk/anthropic';
import { generateText, stepCountIs } from 'ai';
import { createYouClient } from '@youdotcom-oss/ai-sdk-plugin';

const anthropic = createAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const client = await createYouClient({
  apiKey: process.env.YDC_API_KEY,
});

try {
  const tools = await client.tools();

  const result = await generateText({
    model: anthropic('claude-sonnet-4-5-20250929'),
    tools,
    stopWhen: stepCountIs(5),  // Required for tool result processing
    prompt: 'Search for the latest developments in quantum computing',
  });

  console.log(result.text);
} finally {
  await client.close();
}
```

`createYouClient()` returns the underlying MCP client. Call `await client.tools()` to resolve the tool set, and `await client.close()` when finished. Use `stopWhen: stepCountIs(n)` to enable multi-step tool execution—your AI automatically selects the right tool and handles the orchestration.

### Test Your Setup

Ask your AI something that needs real-time information:

* "What are the latest developments in quantum computing?"
* "Find recent articles about sustainable energy and summarize the key trends"
* "Extract and analyze the content from [https://anthropic.com](https://anthropic.com)"

---

## Tool Set

The package always connects to `https://api.you.com/mcp`.

**Default tools:**

* `you-search`—real-time web and news search
* `you-contents`—full page content extraction in markdown or HTML
* `you-balance`—remaining credit balance for the API key
* `you-discover`—pointed recommendations for the right You.com integration path

**Optional tools** (not included by default, request explicitly with `tools`):

* `you-finance`—finance-optimized research with citations
* `you-research`—comprehensive research with configurable effort levels

## Scoping Tools

`tools` scopes the visible tool set. `profile` selects a hosted server profile. If provided, `profile` takes precedence over `tools`.

#### Explicit tools

Request a specific tool set:

```typescript
import { createYouClient } from '@youdotcom-oss/ai-sdk-plugin';

const client = await createYouClient({
  apiKey: 'your-api-key-here',
  tools: ['you-search', 'you-contents'],
});

const tools = await client.tools();
```

#### Finance only

Lead with the smallest explicit form when you only want finance:

```typescript
const client = await createYouClient({
  tools: 'you-finance',
});

const financeTools = await client.tools();
```

#### All six tools

If you want the default tools plus finance and research, request all of them explicitly:

```typescript
const client = await createYouClient({
  tools: ['you-search', 'you-contents', 'you-balance', 'you-discover', 'you-finance', 'you-research'],
});

const tools = await client.tools();
```

#### Free profile

Use `profile` when you want the hosted server to resolve tools through a named profile instead. The free profile is keyless—no API key, no signup—and exposes `you-search` and `you-discover`:

```typescript
const client = await createYouClient({
  profile: 'free',
});

const tools = await client.tools();
```

### Configuration type

```typescript
export type YouClientConfig = {
  apiKey?: string;           // Defaults to YDC_API_KEY
  tools?: string | string[]; // Added as ?tools=...
  profile?: string;          // Added as ?profile=...
};
```

## Using Different Model Providers

This plugin works with any AI SDK compatible model provider:

```typescript
import { generateText, stepCountIs } from 'ai';

// Anthropic Claude
import { createAnthropic } from '@ai-sdk/anthropic';

const anthropic = createAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const client = await createYouClient();
const tools = await client.tools();

const result = await generateText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  tools,
  stopWhen: stepCountIs(3),
  prompt: 'Search for AI news',
});
```

OpenAI (`@ai-sdk/openai`) and Google Gemini (`@ai-sdk/google`) work the same way—create the provider with its own credentials and pass the resolved `tools` into `generateText`.

## Troubleshooting

#### “YDC\_API\_KEY is required” error

Set your API key as an environment variable, or pass it directly:

```bash
export YDC_API_KEY=your-api-key-here
# Then restart your application
```

```typescript
const client = await createYouClient({ apiKey: 'your-api-key-here' });
```

Get a new key at [you.com/platform/api-keys](https://you.com/platform/api-keys) if needed.

#### AI isn't using the tools, or the response is empty

Make sure you're using `stopWhen: stepCountIs(n)` to enable multi-step tool execution. The deprecated `maxSteps` option executes tools but doesn't integrate their results into the response—replace it with `stopWhen`.

#### 401 authentication errors

Verify the key is set and correct:

```bash
echo $YDC_API_KEY
# If empty, set it
export YDC_API_KEY=your-api-key-here
```

#### 429 rate limit errors

You've hit the API rate limit. Wait a few minutes before retrying, or check your usage at [you.com/platform/api-keys](https://you.com/platform/api-keys).

---

## Resources

#### [GitHub Repository](https://github.com/youdotcom-oss/ai-sdk-plugin)

Source code, examples, and issues for the AI SDK plugin

#### [Vercel AI SDK Docs](https://sdk.vercel.ai/)

Official Vercel AI SDK documentation

#### [Web Search API Reference](/docs/api-reference/search/v1-search)

Full Web Search API parameters and response schema

#### [Contents API Reference](/docs/api-reference/contents)

Full Contents API parameters and response schema

#### [Research API Reference](/docs/api-reference/research/v1-research)

Full Research API parameters and response schema