---
title: AI SDK
description: Give a Vercel AI SDK agent the looot tools with @looot/ai-sdk. Install, token, a generateText example and the five tools.
sidebar:
  label: AI SDK
---

`@looot/ai-sdk` gives an agent built with the [Vercel AI SDK](https://ai-sdk.dev) five looot tools.
With one agent token and one prepaid balance, the agent can search 4,200+ data operations from 300+
providers, such as work emails, phone numbers, company and people search, Google results, web pages
and LinkedIn profiles. It reads the price before it runs and pays per call. A failed call costs
nothing.

## Install

```bash
npm install @looot/ai-sdk ai zod
```

The package needs Node 22.18 or newer. Its peer dependencies are `ai` 6 or 7 and `zod` 3.25.76+ or
4.1.8+.

## Token

Create an agent token on looot.ai under Settings, **Agent tokens**. Tick `catalog.read`, `runs.read`,
`runs.execute` and `usage.read`. Export it as `LOOOT_TOKEN`:

```bash
export LOOOT_TOKEN="your-agent-token"
```

The tools read `LOOOT_TOKEN` on each call. To pass the token in code instead, use
`loootTools({ apiKey })`. For more on tokens and scopes, see [Headless and CI](/connect/headless).

Top up the balance before the first paid run. See [Money](/money#before-your-first-run).

## Example

```ts
import { generateText, isStepCount } from "ai";
import { loootTools } from "@looot/ai-sdk";

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  tools: loootTools(),
  stopWhen: isStepCount(8),
  prompt: "Find the work email of Jane Doe at example.com and tell me what it cost.",
});

console.log(text);
```

The model string goes through the Vercel AI Gateway. Any AI SDK model provider works the same way.
On `ai` 6, the stop condition is `stepCountIs(8)`.

A typical run takes four tool calls. The model calls `searchCatalog` with the task in plain words,
`inspectOperation` on the endpoint it picks to read the inputs and the price, `runOperation` with
those inputs, and `getRun` if the result was not ready within the wait. `streamText` takes the same
`tools`.

## Tools

| Tool | What it does | Cost | API call |
|---|---|---|---|
| `searchCatalog` | Ranked endpoints for a task in plain words, with each endpoint's ID and price. | Free | `GET /v1/catalog/search` |
| `inspectOperation` | The input schema, output schema and price of one endpoint. | Free | `GET /v1/operations/{endpointId}` |
| `runOperation` | Runs one endpoint and pays from the balance. Waits up to `waitSeconds` (default 20, max 60), then returns a run ID. | Paid | `POST /v1/runs` |
| `getRun` | The status, result and cost of one run. | Free | `GET /v1/runs/{runId}` |
| `getBalance` | The available and reserved balance, and the minimum top-up. | Free | `GET /v1/balance` |

`loootTools()` returns all five. Each one is also exported on its own, for example
`tools: { searchCatalog: searchCatalog(), runOperation: runOperation() }`.

### Options

Every tool function and `loootTools()` take the same options.

| Option | Default | Meaning |
|---|---|---|
| `apiKey` | `process.env.LOOOT_TOKEN` | The agent token. |
| `baseUrl` | `https://api.looot.ai` | The looot API address. |
| `fetch` | `globalThis.fetch` | A custom fetch, for tests or a proxy. |
| `timeoutMs` | `75000` | Timeout per request, long enough for a 60 second wait. |
| `requireApproval` | `false` | `runOperation` and `loootTools()` only. When `true`, the AI SDK asks for approval before each paid run. |

## Results and errors

Read `status` in the `runOperation` result. A resolved call is not a success: a bad input comes back
with `status: "failed"` and is not charged. `queued` or `running` means the model should call
`getRun` with the run ID.

`runOperation` sends an idempotency key on every run. The model can pass its own `idempotencyKey`;
the same key with the same input never pays twice. See [Idempotency](/concepts/idempotency).

When the API answers with a non-2xx status, the tool throws a `LoootApiError` with `status`, `code`
and `body`. A missing token throws `missing_token` before any request.

## Links

- npm: [@looot/ai-sdk](https://www.npmjs.com/package/@looot/ai-sdk)
- Source: [github.com/loootai/looot-ai-sdk](https://github.com/loootai/looot-ai-sdk)
- AI SDK: [ai-sdk.dev](https://ai-sdk.dev)
- Support: [walid@looot.ai](mailto:walid@looot.ai)
- Other packages: [Integrations](/integrations)

<Related />