Vercel AI SDK Integration

The Foil SDK integrates with the Vercel AI SDK to automatically trace streaming responses, tool calls, and multi-step interactions.

Quick Start (Recommended)

The easiest way - just initialize Foil and your Vercel AI SDK calls are automatically traced:

const { Foil } = require('@getfoil/foil-js/otel');
const { openai } = require('@ai-sdk/openai');
const { streamText } = require('ai');

// Initialize Foil once at app startup
Foil.init({
  apiKey: process.env.FOIL_API_KEY,
  agentName: 'vercel-ai-agent',
});

// Use Vercel AI SDK as normal - automatically traced!
const result = await streamText({
  model: openai('gpt-4o'),
  prompt: 'Write a haiku about coding',
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
// ↑ This call was automatically traced to Foil

Manual Callbacks (Alternative)

For more control over tracing, use the callbacks:

const { openai } = require('@ai-sdk/openai');
const { streamText } = require('ai');
const { createFoilTracer, createVercelAICallbacks } = require('@getfoil/foil-js');

const tracer = createFoilTracer({
  apiKey: process.env.FOIL_API_KEY,
  agentName: 'vercel-ai-agent',
});

await tracer.trace(async (ctx) => {
  const callbacks = createVercelAICallbacks(tracer, { context: ctx });

  const result = await streamText({
    model: openai('gpt-4o'),
    prompt: 'Write a haiku about coding',
    ...callbacks,
  });

  // Consume the stream
  for await (const chunk of result.textStream) {
    process.stdout.write(chunk);
  }

  return result.text;
});

What Gets Captured

Event	Captured Data
`onStart`	Model, input, start time
`onToken`	Streaming tokens, TTFT
`onToolCall`	Tool name, arguments
`onToolResult`	Tool output, duration
`onFinish`	Full response, tokens, latency
`onError`	Error message, stack

Tool Calls

Automatic tracking of tool executions:

import { tool } from 'ai';
import { z } from 'zod';

await tracer.trace(async (ctx) => {
  const callbacks = createVercelAICallbacks(tracer, { context: ctx });

  const result = await streamText({
    model: openai('gpt-4o'),
    prompt: 'What is the weather in San Francisco?',
    tools: {
      getWeather: tool({
        description: 'Get weather for a location',
        parameters: z.object({
          location: z.string()
        }),
        execute: async ({ location }) => {
          return await fetchWeather(location);
        }
      })
    },
    ...callbacks
  });

  // Process result...
});

Creates a trace like:

Trace: vercel-ai-agent
├── LLM: gpt-4o
│   ├── Tool: getWeather
│   └── (continued response)

Multi-Step Conversations

Track multi-turn interactions:

import { generateText } from 'ai';

await tracer.trace(async (ctx) => {
  const callbacks = createVercelAICallbacks(tracer, { context: ctx });
  const messages = [];

  // First turn
  messages.push({ role: 'user', content: 'Hello!' });
  const response1 = await generateText({
    model: openai('gpt-4o'),
    messages,
    ...callbacks
  });
  messages.push({ role: 'assistant', content: response1.text });

  // Second turn
  messages.push({ role: 'user', content: 'Tell me a joke' });
  const response2 = await generateText({
    model: openai('gpt-4o'),
    messages,
    ...callbacks
  });

  return response2.text;
});

With Next.js Route Handlers

Integrate with Next.js API routes:

Auto-Instrumentation (Recommended)
Manual Callbacks

// instrumentation.ts (Next.js instrumentation file)
import { Foil } from '@getfoil/foil-js/otel';

export function register() {
  Foil.init({
    apiKey: process.env.FOIL_API_KEY!,
    agentName: 'nextjs-chat',
  });
}

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  // Automatically traced!
  const result = await streamText({
    model: openai('gpt-4o'),
    messages,
  });

  return result.toDataStreamResponse();
}

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { createFoilTracer, createVercelAICallbacks } from '@getfoil/foil-js';

const tracer = createFoilTracer({
  apiKey: process.env.FOIL_API_KEY!,
  agentName: 'nextjs-chat',
});

export async function POST(req: Request) {
  const { messages } = await req.json();

  return await tracer.trace(async (ctx) => {
    const callbacks = createVercelAICallbacks(tracer, { context: ctx });

    const result = await streamText({
      model: openai('gpt-4o'),
      messages,
      ...callbacks,
    });

    return result.toDataStreamResponse();
  }, {
    name: 'chat-completion',
    input: messages,
  });
}

With useChat Hook

The server-side tracing works seamlessly with the client useChat hook:

// Client component
'use client';
import { useChat } from 'ai/react';

export function Chat() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat'
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>{m.content}</div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

Object Generation

Track structured output generation:

import { generateObject } from 'ai';
import { z } from 'zod';

await tracer.trace(async (ctx) => {
  const callbacks = createVercelAICallbacks(tracer, { context: ctx });

  const result = await generateObject({
    model: openai('gpt-4o'),
    schema: z.object({
      recipe: z.object({
        name: z.string(),
        ingredients: z.array(z.string()),
        steps: z.array(z.string())
      })
    }),
    prompt: 'Generate a recipe for chocolate cake',
    ...callbacks
  });

  return result.object;
});

Configuration Options

const callbacks = createVercelAICallbacks(tracer, {
  context: ctx,           // Trace context (required)
  captureTokens: true,    // Count tokens (default: true)
  captureContent: true    // Capture full content (default: true)
});

Error Handling

Errors are automatically captured:

await tracer.trace(async (ctx) => {
  const callbacks = createVercelAICallbacks(tracer, { context: ctx });

  try {
    const result = await streamText({
      model: openai('gpt-4o'),
      prompt: 'Hello',
      ...callbacks
    });
    return result.text;
  } catch (error) {
    // Error automatically recorded via onError callback
    throw error;
  }
});

Next Steps

OpenAI Integration

OpenAI-specific features

Signals & Feedback

Record user feedback

Alerting

Set up alerts for issues

Getting Started

SDKs

Concepts

Features

Vercel AI SDK Integration

Vercel AI SDK Integration

Quick Start (Recommended)

Manual Callbacks (Alternative)

What Gets Captured

Tool Calls

Multi-Step Conversations

With Next.js Route Handlers

With useChat Hook

Object Generation

Configuration Options

Error Handling

Next Steps

OpenAI Integration

Signals & Feedback

Alerting

​Vercel AI SDK Integration

​Quick Start (Recommended)

​Manual Callbacks (Alternative)

​What Gets Captured

​Tool Calls

​Multi-Step Conversations

​With Next.js Route Handlers

​With useChat Hook

​Object Generation

​Configuration Options

​Error Handling

​Next Steps

OpenAI Integration

Signals & Feedback

Alerting

Vercel AI SDK Integration

Quick Start (Recommended)

Manual Callbacks (Alternative)

What Gets Captured

Tool Calls

Multi-Step Conversations

With Next.js Route Handlers

With useChat Hook

Object Generation

Configuration Options

Error Handling

Next Steps