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

# Use with the Vercel AI SDK

> Give an AI agent the full routing and booking flow with one package of ready made tools.

If your agent runs on the Vercel AI SDK, you do not need to write API calls by hand. The
`@defaulthq/ai-tools` package wraps every public API endpoint as a standard `tool()` definition.
Your agent reads the tool descriptions, decides what to call, and the package handles the
requests.

This is a server side package. It holds your API key, so it must never run in a browser.

## Install both packages

```bash theme={null}
# Install both default's AI tools and vercel's ai package
npm install @defaulthq/ai-tools ai
```

Requires Node 22 or newer and version 6 or 7 of the `ai` package.

## Use

Bind your Default API key once, then spread the tools into any `generateText` or `streamText` call.

```ts theme={null}
import { createDefaultTools } from '@defaulthq/ai-tools'
import { streamText } from 'ai'

const defaultTools = createDefaultTools({
  apiKey: process.env.DEFAULT_API_KEY,
})

streamText({
  model,
  system: `Today is ${new Date().toISOString()}. Jordan is in the America/Chicago timezone.`,
  messages,
  tools: { ...defaultTools },
})
```

Your key never appears in any tool input, so the model cannot see or leak it. Create your API key
in **Settings** → **API Keys** with the `triggers:write` and `scheduling:write` permissions.

## What the model needs from you

The tool descriptions teach the model how to chain the flow. Your prompt supplies what the API
cannot know: today's date and the lead's timezone, as in the example above. The model has no
clock, so without the date a request for slots "next week" can use dates from the past. Without
the timezone it can read "Tuesday at 3pm" in the wrong one and book the wrong slot.

## The tools

**Routing and booking.** The four steps from [Route and book through the API](/api/route-and-book),
as tools the agent chains on its own.

| Tool                | What it does                                                 |
| ------------------- | ------------------------------------------------------------ |
| `listTriggers`      | Finds your triggers and the form fields each one expects     |
| `fireTrigger`       | Runs the routing workflow for a lead and returns the outcome |
| `getAvailableSlots` | Gets open times for the scheduler the workflow handed back   |
| `bookMeeting`       | Books a slot and links the meeting to the workflow run       |

**Direct booking.** For booking on an event without a workflow.

| Tool         | What it does                                            |
| ------------ | ------------------------------------------------------- |
| `listEvents` | Lists your bookable events                              |
| `getEvent`   | Gets one event's duration, hosts, and booking questions |

**Manage meetings.**

| Tool                | What it does                                   |
| ------------------- | ---------------------------------------------- |
| `getMeeting`        | Gets a meeting's status, time, and join link   |
| `getMeetingSlots`   | Gets open times for moving an existing meeting |
| `rescheduleMeeting` | Moves a meeting to a new time                  |
| `cancelMeeting`     | Cancels a meeting, with an optional reason     |

## How errors reach the agent

API errors are returned as tool results instead of thrown. The model sees the error code and
recovers on its own, so a taken slot leads to a fresh slot lookup and a retry rather than a
crash. Transport failures, like the network dropping or a response that is not JSON, will still
throw an error, so keep your usual exception handling around the generation call. The
[error codes](/api/route-and-book#handling-errors) match the REST API exactly.

Response shapes are exported as TypeScript types, so your own code can consume tool results
with full typing.