Vercel AI SDK

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

Install

npm install @grantex/vercel-ai @grantex/sdk ai zod

Scope-Enforced Tools

Create Vercel AI SDK tools with Grantex authorization. Scope is checked at construction time — if the token is missing the required scope, createGrantexTool throws immediately:

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 at construction time
  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:

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:

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 — checked at construction time
execute	(args, options) => Promise<Result>	Tool implementation

Throws GrantexScopeError if scope is missing.

getGrantScopes(grantToken)

Returns string[] of scopes from the token’s scp claim (offline).

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