Vercel AI SDK

Give a Vercel AI SDK agent access to Tako by dropping in @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.

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.

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.

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

pnpm add @takoviz/ai-sdk ai @ai-sdk/openai

yarn add @takoviz/ai-sdk ai @ai-sdk/openai

bun add @takoviz/ai-sdk ai @ai-sdk/openai

Set up your environment

Get a Tako API key and a model-provider key, and export both:

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

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

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.

Example output

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.)

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:

import { takoSearch, takoContents } from '@takoviz/ai-sdk';

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

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.

Configuration

takoSearch and takoAnswer take the same config:

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:

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, answer, and contents.

TypeScript

Full type definitions ship with the package:

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

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

Install

Set up your environment

Quick start

The tools

Give your agent the toolset

Render the cards yourself? Use `takoSearch`

Configuration

TypeScript

Resources

​Install

​Set up your environment

​Quick start

​The tools

​Give your agent the toolset

​Render the cards yourself? Use takoSearch

​Configuration

​TypeScript

​Resources

Install

Set up your environment

Quick start

The tools

Give your agent the toolset

Render the cards yourself? Use `takoSearch`

Configuration

TypeScript

Resources