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

# Vercel AI SDK

Give a [Vercel AI SDK](https://sdk.vercel.ai/docs) agent access to Tako by dropping in [`@takoviz/ai-sdk`](https://www.npmjs.com/package/@takoviz/ai-sdk) — tools the model can call to ground its answers in well-sourced, up-to-date data and charts. You register the tools; the SDK runs the tool loop and the model decides when to call them.

This page covers installing the package, giving an agent the Tako toolset, and configuring it.

<Info>
  The three tools map 1:1 to Tako's GA endpoints (`search`, `answer`, `contents`) and are fast, synchronous calls. The model supplies only the dynamic input — `query` or `url` — while everything else (sources, effort, locale) is set once when you construct the tool.
</Info>

## Install

`ai` (the Vercel AI SDK) is a peer dependency and works with v6 or v7. This guide uses an OpenAI model, so it also installs `@ai-sdk/openai`.

<CodeGroup>
  ```bash npm theme={null}
  npm install @takoviz/ai-sdk ai @ai-sdk/openai
  ```

  ```bash pnpm theme={null}
  pnpm add @takoviz/ai-sdk ai @ai-sdk/openai
  ```

  ```bash yarn theme={null}
  yarn add @takoviz/ai-sdk ai @ai-sdk/openai
  ```

  ```bash bun theme={null}
  bun add @takoviz/ai-sdk ai @ai-sdk/openai
  ```
</CodeGroup>

## Set up your environment

Get a [Tako API key](https://developer.tako.com/console/api-keys) and a model-provider key, and export both:

```bash theme={null}
export TAKO_API_KEY=<your tako key>
export OPENAI_API_KEY=<your openai key>
```

Each tool reads `TAKO_API_KEY` (or `TAKO_API_TOKEN`) automatically — or you can pass `apiKey` when you construct it. To target a non-prod host, pass `baseUrl` (e.g. `https://staging.tako.com`); it defaults to `https://tako.com`.

## Quick start

Register `takoAnswer` and let the model call it. `stopWhen: isStepCount(...)` caps the tool-use loop:

```typescript theme={null}
import { generateText, isStepCount } from 'ai';
import { openai } from '@ai-sdk/openai';
import { takoAnswer } from '@takoviz/ai-sdk';

const { text } = await generateText({
  model: openai('gpt-4o-mini'),
  prompt: 'How has US unemployment trended over the last 5 years?',
  tools: { tako_answer: takoAnswer() },
  stopWhen: isStepCount(5),
});

console.log(text);
```

## The tools

| Tool             | Endpoint                | Returns                                                                                                        |
| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `takoSearch()`   | `POST /api/v3/search`   | Tako knowledge cards (charts/metrics with their sources) plus web results — no synthesis                       |
| `takoAnswer()`   | `POST /api/v1/answer`   | A citation-backed, synthesized answer **plus** the backing cards and web results (`cards[0]` is the lead card) |
| `takoContents()` | `POST /api/v1/contents` | The data behind a result URL — a card's CSV or a web page's extracted text                                     |

`takoSearch` and `takoAnswer` return [Tako cards](/documentation/getting-started/what-is-tako/knowledge-cards) and web results that carry URLs (`webpage_url`, `url`). The agent can then call `takoContents` with one of those URLs to pull the underlying data. The model supplies only `{ query }` for search/answer and `{ url }` for contents — everything else comes from the tool's config.

## Give your agent the toolset

Pair `takoAnswer` with `takoContents` so the agent can answer a question and then drill into the data behind a result:

```typescript theme={null}
import { generateText, isStepCount } from 'ai';
import { openai } from '@ai-sdk/openai';
import { takoAnswer, takoContents } from '@takoviz/ai-sdk';

const { text } = await generateText({
  model: openai('gpt-4o-mini'),
  prompt:
    'Did Nvidia or AMD grow headcount faster over the last decade? Then download the data behind it.',
  tools: {
    tako_answer: takoAnswer(),
    tako_contents: takoContents({ mode: 'inline' }),
  },
  stopWhen: isStepCount(6),
});

console.log(text);
```

Each card also carries an `image_url` (a rendered chart) and an `embed_url` you can surface in your own UI.

<Accordion title="Example output">
  ```text theme={null}
  Over the last decade, Nvidia grew headcount substantially faster than AMD:
  Nvidia went from ~9,200 employees (2016) to ~42,000 (2026) — roughly a
  4.5× increase — while AMD grew from ~8,200 to ~31,000 over the same period.
  (Source: the "NVIDIA / AMD Full Time Employees" cards.)
  ```
</Accordion>

## Render the cards yourself? Use `takoSearch`

`takoAnswer` returns prose plus the backing cards — best when you want the model to read an answer back. If instead you want to **render the cards yourself** (embed the interactive charts, post-process the data) without a written answer on top, swap in `takoSearch`, which returns cards and web results only:

```typescript theme={null}
import { takoSearch, takoContents } from '@takoviz/ai-sdk';

const tools = {
  tako_search: takoSearch(),
  tako_contents: takoContents(),
};
```

<Warning>
  Register `takoSearch` **or** `takoAnswer`, not both. They take the same input and differ only in whether you want cards or prose back, so exposing both forces the model to guess. Pick the one that matches how your app consumes the result, and keep `takoContents` alongside it.
</Warning>

## Configuration

`takoSearch` and `takoAnswer` take the same config:

```typescript theme={null}
takoSearch({
  apiKey: 'your_api_key',         // optional; defaults to TAKO_API_KEY / TAKO_API_TOKEN
  baseUrl: 'https://tako.com',    // optional; e.g. https://staging.tako.com
  effort: 'fast',                 // 'fast' (default) | 'instant' | 'deep'
  sources: {                      // a source is searched iff its key is present; omit to search both
    data: { count: 5, includeContents: false, deferDataRetrieval: false },
    web: { count: 5, includeContents: false },
  },
  countryCode: 'US',              // default 'US'
  locale: 'en-US',                // default 'en-US'
  timezone: 'America/New_York',   // optional IANA timezone
  outputSettings: {
    imageDarkMode: false,
    forceRefresh: false,          // instant mode only
  },
});
```

`takoContents` takes:

```typescript theme={null}
takoContents({
  apiKey: 'your_api_key',
  baseUrl: 'https://tako.com',
  mode: 'url',                    // 'url' (default) → presigned download link; 'inline' → content in the response
});
```

For the full request/response field reference, see the API docs for [search](/api-reference/search-v3), [answer](/api-reference/answer), and [contents](/api-reference/contents).

## TypeScript

Full type definitions ship with the package:

```typescript theme={null}
import type {
  TakoRetrievalConfig,
  TakoContentsConfig,
  TakoSearchResult,
  TakoAnswerResult,
  TakoContentsResult,
  TakoCard,
  TakoWebResult,
  TakoContentItem,
} from '@takoviz/ai-sdk';
```

## Resources

* [`@takoviz/ai-sdk` on npm](https://www.npmjs.com/package/@takoviz/ai-sdk)
* [GitHub repository](https://github.com/TakoData/ai-sdk)
* [Vercel AI SDK documentation](https://sdk.vercel.ai/docs)
* [AI SDK Tools Registry](https://ai-sdk.dev/tools-registry)
* [Tako API reference](/api-reference/search-v3)
* [Tako developer console](https://developer.tako.com/console/api-keys)