Skip to main content

​
Introduction

Vercel AI SDK is a TypeScript toolkit for building AI-powered applications with React, Next.js, Vue, and more.
The Helicone provider for Vercel AI SDK is available as a dedicated package: @helicone/ai-sdk-provider.

​
Integration Steps

1
Sign up at helicone.ai and generate an API key.
You’ll also need to configure your provider API keys (OpenAI, Anthropic, etc.) at Helicone Providers for BYOK (Bring Your Own Keys).
2
HELICONE_API_KEY=sk-helicone-...
3

Install the Helicone AI SDK provider

pnpm add @helicone/ai-sdk-provider ai
4

Configure Vercel AI SDK with Helicone

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

// Initialize Helicone provider
const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

// Use any model from 100+ providers
const result = await generateText({
  model: helicone('claude-4.5-haiku'),
  prompt: 'Write a haiku about artificial intelligence'
});

console.log(result.text);
You can switch between 100+ models without changing your code. Just update the model name!
While you’re here, why not give us a star on GitHub? It helps us a lot!

​
Complete Working Examples

​
Basic Text Generation

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

const { text } = await generateText({
  model: helicone('gemini-2.5-flash-lite'),
  prompt: 'What is Helicone?'
});

console.log(text);

​
Streaming Text

import { createHelicone } from '@helicone/ai-sdk-provider';
import { streamText } from 'ai';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

const result = await streamText({
  model: helicone('deepseek-v3.1-terminus'),
  prompt: 'Write a short story about a robot learning to paint',
  maxTokens: 300
});

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

console.log('\n\nStream completed!');

​
UI Message Stream Response

Convert streaming results to a UI-compatible response format: 
import { createHelicone } from '@helicone/ai-sdk-provider';
import { streamText } from 'ai';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

const result = streamText({
  model: helicone("gpt-4o-mini", {
    extraBody: {
      helicone: {
        tags: ["simple-stream-test"],
        properties: {
          test: "toUIMessageStreamResponse",
        },
      },
    },
  }),
  prompt: 'Say "Hello streaming world!"',
});

const response = result.toUIMessageStreamResponse();

console.log(
  "Response headers:",
  Object.fromEntries(response.headers.entries())
);
// Just checks that we can create it - actual consumption needs to be in a server

​
Provider Selection

By default, Helicone’s AI gateway automatically routes to the cheapest provider. You can also manually select a specific provider: 
import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

// Automatic routing (cheapest provider)
const autoResult = await generateText({
  model: helicone('gpt-4o'),
  prompt: 'Hello!'
});

// Manual provider selection
const manualResult = await generateText({
  model: helicone('claude-4.5-sonnet/anthropic'),
  prompt: 'Hello!'
});

// Multiple provider selection: first model/provider is used, if it fails, the second model/provider is used, and so on.
const manualResult = await generateText({
  model: helicone('claude-4.5-sonnet/anthropic,gpt-4o/openai'),
  prompt: 'Hello!'
});

​
With Custom Properties and Session Tracking

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

const result = await generateText({
  model: helicone('claude-4.5-haiku', {
    extraBody: {
      helicone: {
        sessionId: 'my-session',
        userId: 'user-123',
        properties: {
          environment: 'production',
          appVersion: '2.1.0',
          feature: 'quantum-explanation'
        }
      }
    }
  }),
  prompt: 'Explain quantum computing'
});

​
Tool Calling

import { createHelicone } from '@helicone/ai-sdk-provider';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

const result = await generateText({
  model: helicone('gpt-4o'),
  prompt: 'What is the weather like in San Francisco?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a location',
      parameters: z.object({
        location: z.string().describe('The city name')
      }),
      execute: async (args) => {
        return `It's sunny in ${args.location}`;
      }
    })
  }
});

console.log(result.text);

​
Agents

Use Vercel AI SDK’s Agent API with Helicone to build multi-step reasoning agents: 
import { createHelicone } from "@helicone/ai-sdk-provider";
import { Experimental_Agent as Agent, tool, jsonSchema, stepCountIs } from "ai";

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY!
});

const weatherAgent = new Agent({
  model: helicone("claude-4.5-haiku"),
  stopWhen: stepCountIs(5),
  tools: {
    getWeather: tool({
      description: "Get the current weather for a location",
      inputSchema: jsonSchema({
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA",
          },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            default: "fahrenheit",
            description: "Temperature unit",
          },
        },
        required: ["location"],
      }),
      execute: async ({ location, unit }) => {
        // Simulate weather API call
        const temp =
          unit === "celsius"
            ? Math.floor(Math.random() * 30 + 5)
            : Math.floor(Math.random() * 86 + 32);
        const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"][
          Math.floor(Math.random() * 4)
        ];
        const result = {
          location,
          temperature: temp,
          unit: unit || "fahrenheit",
          conditions,
          description: `It's ${conditions} in ${location} with a temperature of ${temp}°${unit?.charAt(0).toUpperCase() || "F"}.`,
        };
        console.log(`Result: ${JSON.stringify(result)}`);
        return result;
      },
    }),
    calculateWindChill: tool({
      description: "Calculate wind chill temperature",
      inputSchema: jsonSchema({
        type: "object",
        properties: {
          temperature: {
            type: "number",
            description: "Temperature in Fahrenheit",
          },
          windSpeed: {
            type: "number",
            description: "Wind speed in mph",
          },
        },
        required: ["temperature", "windSpeed"],
      }),
      execute: async ({ temperature, windSpeed }) => {
        const windChill =
          35.74 +
          0.6215 * temperature -
          35.75 * Math.pow(windSpeed, 0.16) +
          0.4275 * temperature * Math.pow(windSpeed, 0.16);
        const result = {
          temperature,
          windSpeed,
          windChill: Math.round(windChill),
          description: `With a temperature of ${temperature}°F and wind speed of ${windSpeed} mph, the wind chill feels like ${Math.round(windChill)}°F.`,
        };
        console.log(`Result: ${JSON.stringify(result)}`);
        return result;
      },
    }),
  },
});

try {
  console.log("🌤️  Asking about weather in multiple cities...\n");

  const result = await weatherAgent.generate({
    prompt:
      "You are a helpful weather assistant. When asked about weather, use the getWeather tool to provide accurate information.\n\nWhat is the weather like in San Francisco, CA and New York, NY? Also, if the wind speed in San Francisco is 15 mph, what would the wind chill feel like?"
  });

  console.log("=== Agent Response ===");
  console.log(result.text);

  console.log("\n=== Usage Statistics ===");
  console.log(`Total tokens: ${result.usage?.totalTokens || "N/A"}`);
  console.log(`Finish reason: ${result.finishReason}`);
  console.log(`Steps taken: ${result.steps?.length || 0}`);

  if (result.steps && result.steps.length > 0) {
    console.log("\n=== Steps Breakdown ===");
    result.steps.forEach((step, index) => {
      console.log(`Step ${index + 1}: ${step.finishReason}`);
      if (step.toolCalls && step.toolCalls.length > 0) {
        console.log(
          `  Tool calls: ${step.toolCalls.map((tc) => tc.toolName).join(", ")}`
        );
        step.toolCalls.forEach((tc, i) => {
          console.log(
            `    Tool ${i + 1}: ${tc.toolName}(${JSON.stringify(tc.input)})`
          );
        });
      }
    });
  }
} catch (error) {
  console.error("❌ Error running agent:", error);
  if (error instanceof Error) {
    console.error("Error details:", error.message);
  }
}

​
Helicone Prompts Integration

Use prompts created in your Helicone dashboard instead of hardcoding messages in your application: 
import { createHelicone } from '@helicone/ai-sdk-provider';
import type { WithHeliconePrompt } from '@helicone/ai-sdk-provider';
import { generateText } from 'ai';

const helicone = createHelicone({
  apiKey: process.env.HELICONE_API_KEY
});

const result = await generateText({
  model: helicone('gpt-4o', {
    promptId: 'sg45wqc',
    inputs: {
      customer_name: 'Sarah Johnson',
      issue_type: 'billing',
      account_type: 'premium'
    },
    environment: 'production',
    extraBody: {
      helicone: {
        sessionId: 'support-session-123',
        properties: {
          department: 'customer-support'
        }
      }
    }
  }),
  messages: [{ role: 'user', content: 'placeholder' }]
} as WithHeliconePrompt);
When using promptId, you must still pass a placeholder messages array to satisfy the Vercel AI SDK’s validation. The actual prompt content will be fetched from your Helicone dashboard, and the placeholder messages will be ignored.
Benefits of using Helicone prompts:
  • 🎯 Centralized Management: Update prompts without code changes
  • 👩🏻‍💻 Perfect for non-technical users: Create prompts using the Helicone dashboard
  • 🚀 Lower Latency: Single API call, no message construction overhead
  • 🔧 A/B Testing: Test different prompt versions with environments
  • 📊 Better Analytics: Track prompt performance across versions

​
Additional Examples

For more comprehensive examples, check out the GitHub repository.
Looking for a framework or tool not listed here? Request it here!

​
Additional Resources

AI Gateway Overview

Learn about Helicone’s AI Gateway features and capabilities

Provider Routing

Configure intelligent routing and automatic failover

Model Registry

Browse all available models and providers

Prompt Management

Version and manage prompts with Helicone Prompts

Custom Properties

Add metadata to track and filter your requests

Sessions

Track multi-turn conversations and user sessions

Rate Limiting

Configure rate limits for your applications

Caching

Reduce costs and latency with intelligent caching