# Vercel AI SDK

> Check every tool call an AI SDK agent makes with Thoth before the tool runs.

Source: https://docs.atensecurity.com/docs/sdks/vercel-ai-sdk

`governAiSdkTools` wraps an [AI SDK](https://ai-sdk.dev) tool set so that each
tool call is checked with Thoth before its `execute` runs. Use the governed set
with `generateText`, `streamText` or an `Agent`, exactly as you would the
original. It needs `@atensec/thoth` 0.2.0 or later and AI SDK 7, and is tested
with `ai` 7.0.159 ([framework compatibility](https://docs.atensecurity.com/docs/sdks/framework-compatibility)).

## Install

```bash
npm install @atensec/thoth ai zod
```

Register the agent in Thoth first, and give your app its connection settings:

```bash
export THOTH_TENANT_ID="your-tenant-id"
export THOTH_API_URL="https://api.atensecurity.com"  # trial and self-serve; Enterprise: your enforce. host
export THOTH_API_KEY="..."                                     # a runtime key for this agent
```

[Your first governed agent](https://docs.atensecurity.com/docs/getting-started/quickstart) covers
registering an agent and creating its key.

## Govern a tool set

```typescript title="agent.ts"
import { generateText, isStepCount, tool } from "ai";
import { z } from "zod";
import { governAiSdkTools } from "@atensec/thoth/ai-sdk";

const tools = governAiSdkTools(
  {
    lookupOrder: tool({
      description: "Look up an order by ID",
      inputSchema: z.object({ orderId: z.string() }),
      execute: async ({ orderId }) => orders.get(orderId),
    }),
    sendRefund: tool({
      description: "Refund an order",
      inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
      execute: async ({ orderId, amount }) => payments.refund(orderId, amount),
    }),
  },
  {
    agentId: "support-agent",
    tenantId: process.env.THOTH_TENANT_ID!,
    approvedScope: [],
    userId: "alice@example.com", // the user this request is for
  },
);

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  tools,
  prompt: "Refund order A-1, it arrived damaged.",
  stopWhen: isStepCount(5),
});
```

Each call is checked with the tool's name and its input as the arguments. The
AI SDK's call options (`toolCallId`, `abortSignal`, messages) reach your
`execute` unchanged. Tools without an `execute`, such as tools your client
runs, are passed through as they are and aren't checked.

Govern the tool set once per session, for example per request. To govern it
once at startup and serve many users, leave out `userId` and run each request
inside `actingFor`:

```typescript
import { actingFor } from "@atensec/thoth";

app.post("/chat", (req, res) =>
  actingFor(req.user.email, () => generateText({ model, tools, prompt })),
);
```

## What each decision does

| Decision  | What happens                                                                                                                                                                       |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ALLOW`   | `execute` runs.                                                                                                                                                                    |
| `DENY`    | `execute` never runs. The governed tool throws `ThothPolicyViolation`, and the AI SDK records it as that tool call's error, so the model sees the call was refused.                |
| `STEP_UP` | The call waits for a person to approve it, up to `stepUpTimeoutMinutes` (15 by default). If it's approved, `execute` runs; otherwise it's refused as for `DENY`.                    |

If Thoth can't be reached, calls are refused unless you set `failOpen: true`.
See [error handling](https://docs.atensecurity.com/docs/sdks/typescript) in the TypeScript SDK reference.

Start a new agent in [observe](https://docs.atensecurity.com/docs/operations/enforcement-modes): Thoth
records what it would have decided and every call runs. Switch the agent to
enforce when the observe summary shows it's ready.

## Cloudflare Agents

Cloudflare's chat agents (`AIChatAgent` from `@cloudflare/ai-chat`) run tools
through the AI SDK, and `this.mcp.getAITools()` returns connected MCP servers'
tools as an AI SDK tool set. Govern the whole set you pass to `streamText`. Workers
have no `process.env`, so pass the connection in the config:

```typescript
const tools = governAiSdkTools(
  { ...myTools, ...this.mcp.getAITools() },
  {
    agentId: "support-agent",
    tenantId: this.env.THOTH_TENANT_ID,
    apiUrl: this.env.THOTH_API_URL,
    apiKey: this.env.THOTH_API_KEY,
    approvedScope: [],
    userId: this.name,
  },
);
```
