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

# Vercel AI SDK

> Scope-enforced tools and audit logging for Vercel AI SDK agents.

## Install

```bash theme={null}
npm install @grantex/vercel-ai @grantex/sdk ai zod
```

## Scope-Enforced Tools

Create Vercel AI SDK tools with Grantex authorization. The token signature and
claims are verified and the required scope is checked **at execution time**,
immediately before the application callback runs:

```typescript theme={null}
import { createGrantexTool } from '@grantex/vercel-ai';
import { z } from 'zod';

const readCalendar = createGrantexTool({
  name: 'read_calendar',
  description: 'Read upcoming calendar events',
  parameters: z.object({
    date: z.string().describe('Date in YYYY-MM-DD format'),
  }),
  grantToken,                     // JWT from Grantex token exchange
  requiredScope: 'calendar:read', // checked after JWKS verification at execution
  execute: async (args) => {
    return await getCalendarEvents(args.date);
  },
});

// Use with generateText, streamText, etc.
import { generateText } from 'ai';

const { text } = await generateText({
  model: openai('gpt-4'),
  tools: { read_calendar: readCalendar },
  prompt: 'What meetings do I have today?',
});
```

## Inspect Grant Scopes

Use `getGrantScopes` to check what scopes a token has before creating tools:

```typescript theme={null}
import { getGrantScopes } from '@grantex/vercel-ai';

const scopes = getGrantScopes(grantToken);
// → ['calendar:read', 'email:send']
```

## Audit Logging

Wrap tools with `withAuditLogging` to log every invocation to the Grantex audit trail:

```typescript theme={null}
import { Grantex } from '@grantex/sdk';
import { createGrantexTool, withAuditLogging } from '@grantex/vercel-ai';

const client = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

const audited = withAuditLogging(readCalendar, client, {
  agentId: 'ag_01ABC...',
  agentDid: 'did:key:z6Mk...',
  grantId: 'grnt_01XYZ...',
  principalId: 'user_01',
});
// Use audited in place of readCalendar
```

## API Reference

### `createGrantexTool(options)`

| Option | Type | Description |
| - | - | - |
| `name` | `string` | Tool name |
| `description` | `string` | Tool description |
| `parameters` | `z.ZodTypeAny` | Zod schema for tool arguments |
| `grantToken` | `string` | Grantex JWT from token exchange |
| `requiredScope` | `string` | Scope required after JWKS verification at execution time |
| `execute` | `(args, options) => Promise<Result>` | Tool implementation |

Execution throws `GrantexScopeError` if the verified scope is missing and does
not call the application implementation.

### `getGrantScopes(grantToken)`

Returns unverified `string[]` scopes decoded from the token's `scp` claim. Use this only for display or debugging; protected tool execution performs signature verification.

### `withAuditLogging(tool, client, options)`

| Option | Type | Description |
| - | - | - |
| `agentId` | `string` | Agent ID for audit attribution |
| `agentDid` | `string` | Agent DID (e.g. `did:key:z6Mk...`) |
| `grantId` | `string` | Grant ID for the session |
| `principalId` | `string` | Principal ID that granted authorization |
| `toolName` | `string?` | Override tool name in audit entries |

### `GrantexScopeError`

| Property | Type | Description |
| - | - | - |
| `requiredScope` | `string` | The scope that was required |
| `grantedScopes` | `string[]` | The scopes the token actually has |

## Requirements

* Node.js 18+
* `@grantex/sdk` >= 0.1.0
* `ai` >= 4.0.0 (Vercel AI SDK)
* `zod` >= 3.0.0

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).

## Current Authority and Human Identity

Use the exact integration version and minimum primary SDK in [Release Status](/release-status).
Per-invocation issuer authority and trusted principal/agent binding are opt-in.
Configure the callback with the trusted issuer and derive identity from the host's
authenticated session; signature and scope checks alone do not prove current
revocation or human consent. See [SDK execution authority](/guides/sdk-execution-authority)
for configuration, denial behavior and manifest/decision/caps boundaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.