@helicone/ai-sdk-provider weekly downloads statistics

Helicone AI SDK Provider

A Vercel AI SDK provider for Helicone, enabling seamless integration with Helicone's AI gateway and observability platform.

Features

• ✅ 100+ AI Models: Access to OpenAI, Anthropic, Google, Groq, and more through Helicone's AI gateway
• ✅ Observability: Automatic request logging, metrics, and monitoring through Helicone
• ✅ Model Switching: Easy switching between different AI providers and models
• ✅ Fallbacks: Configure model fallbacks for improved reliability
• ✅ Caching: Built-in caching support for faster responses
• ✅ Sessions & Tags: Organize requests with sessions, user IDs, and custom tags
• ✅ BYOK: Bring your own key
• ✅ TypeScript: Full TypeScript support with comprehensive type definitions

Installation

npm install @helicone/ai-sdk-provider ai

Quick Start

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

// Initialize the provider
const helicone = createHelicone({
  apiKey: 'your-helicone-api-key'
});

// Generate text using GPT-4o
const result = await generateText({
  model: helicone('gpt-4o'),
  prompt: 'Write a haiku about AI',
});

console.log(result.text);

Configuration

Basic Setup

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

const helicone = createHelicone({
  apiKey: 'your-helicone-api-key'
});

Model Selection

Specify models by name only when making the request. For the complete list of supported model names, visit helicone.ai/models.

Helicone's AI gateway will automatically route to the cheapest provider:

const result = await generateText({
  model: helicone('gpt-4o'),
  prompt: 'Write a haiku about AI'
});

console.log(result.text);

If you'd like to select your own provider, you can do so by passing the provider name as the second argument:

const result = await generateText({
  model: helicone('claude-4.5-sonnet/anthropic'),
  prompt: 'Write a haiku about AI'
});

console.log(result.text);

Advanced Features

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: 'your-helicone-api-key' });

const result = await generateText({
  model: helicone('gpt-4o', {
    promptId: 'sg45wqc', // Get this from your Helicone dashboard after saving your prompt
    inputs: {
      customer_name: 'Sarah Johnson',
      issue_type: 'billing',
      account_type: 'premium'
    },
    environment: 'production', // optional, defaults to 'production'
    extraBody: {
      helicone: {
        sessionId: 'support-session-123',
        properties: {
          department: 'customer-support'
        }
      }
    }
  }),
  messages: [{ role: 'user', content: 'placeholder' }] // Required by AI SDK, ignored when using promptId
} as WithHeliconePrompt);

Note: 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: No need to write code to create prompts, just use 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

Session Tracking

const result = await generateText({
  model: helicone('gpt-4o', {
    extraBody: {
      helicone: {
        sessionId: 'user-chat-session-123',
        userId: 'user-456',
        properties: {
          environment: 'production',
          feature: 'chat',
        },
      },
    },
  }),
  prompt: 'Hello!',
});

Custom Tags and Properties

const result = await generateText({
  model: helicone('gpt-4o', {
    extraBody: {
      helicone: {
        tags: ['customer-support', 'urgent'],
        properties: {
          ticketId: 'TICKET-789',
          priority: 'high',
          department: 'support',
        },
      },
    },
  }),
  prompt: 'Help resolve this customer issue...',
});

Streaming

import { streamText } from 'ai';

const result = await streamText({
  model: helicone('gpt-4o'),
  prompt: 'Write a long story about space exploration',
});

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

Tool Calling

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

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',
      inputSchema: z.object({
        location: z.string().describe('The city name')
      }),
      execute: async (args) => {
        // Your weather API call here
        return `It's sunny in ${args.location}`;
      }
    })
  }
});

console.log(result.text);

See examples/tool-calling.ts for a complete example.

Agent Examples (JSON Schema vs Zod)

We ship two agent demos that are functionally identical but highlight different schema styles:

• examples/agents-json.ts uses jsonSchema(...) helpers with a Claude model (claude-4.5-haiku).
• examples/agents-zod.ts uses raw Zod schemas with a different model (gpt-5-chat-latest).…