# Vercel AI SDK Integration

> Integrate Helicone AI Gateway with Vercel AI SDK to access 100+ LLM providers with full observability.

import { strings } from "/snippets/strings.mdx";
import Star from "/snippets/star.mdx";
import RequestIntegration from "/snippets/request-integration.mdx";

## Introduction

[Vercel AI SDK](https://sdk.vercel.ai) is a TypeScript toolkit for building AI-powered applications with React, Next.js, Vue, and more.

<Note>
  The Helicone provider for Vercel AI SDK is available as a dedicated package: `@helicone/ai-sdk-provider`.
</Note>

## Integration Steps

<Steps>
  <Step title={strings.generateKey}>
    Sign up at [helicone.ai](https://www.helicone.ai) and generate an [API key](https://us.helicone.ai/settings/api-keys).

    <Note>
      You'll also need to configure your provider API keys (OpenAI, Anthropic, etc.) at [Helicone Providers](https://us.helicone.ai/providers) for BYOK (Bring Your Own Keys).
    </Note>
  </Step>

  <Step title={strings.setApiKey}>
    ```bash
    HELICONE_API_KEY=sk-helicone-...
    ```
  </Step>

  <Step title="Install the Helicone AI SDK provider">
    <CodeGroup>
    ```bash pnpm
    pnpm add @helicone/ai-sdk-provider ai
    ```

    ```bash npm
    npm install @helicone/ai-sdk-provider ai
    ```

    ```bash yarn
    yarn add @helicone/ai-sdk-provider ai
    ```

    ```bash bun
    bun add @helicone/ai-sdk-provider ai
    ```
    </CodeGroup>
  </Step>

  <Step title="Configure Vercel AI SDK with Helicone">
    ```typescript
    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);
    ```

    <Info>
      You can switch between [100+ models](https://helicone.ai/models) without changing your code. Just update the model name!
    </Info>

    <Star />
  </Step>

</Steps>

## Complete Working Examples

### Basic Text Generation

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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);
```

<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.
</Note>

**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](https://github.com/Helicone/ai-sdk-provider/tree/main/examples).

<RequestIntegration />

## Additional Resources

- [Vercel AI SDK Documentation](https://ai-sdk.dev/providers/community-providers/helicone)
- [Helicone AI SDK Provider Github](https://github.com/Helicone/ai-sdk-provider)

## Related Documentation

<CardGroup cols={2}>
  <Card title="AI Gateway Overview" icon="arrow-progress" href="/gateway/overview">
    Learn about Helicone's AI Gateway features and capabilities
  </Card>
  <Card title="Provider Routing" icon="route" href="/gateway/provider-routing">
    Configure intelligent routing and automatic failover
  </Card>
  <Card title="Model Registry" icon="database" href="https://helicone.ai/models">
    Browse all available models and providers
  </Card>
  <Card title="Prompt Management" icon="code" href="/gateway/concepts/prompt-caching">
    Version and manage prompts with Helicone Prompts
  </Card>
  <Card title="Custom Properties" icon="tags" href="/features/advanced-usage/custom-properties">
    Add metadata to track and filter your requests
  </Card>
  <Card title="Sessions" icon="link" href="/features/sessions">
    Track multi-turn conversations and user sessions
  </Card>
  <Card title="Rate Limiting" icon="gauge" href="/features/advanced-usage/custom-rate-limits">
    Configure rate limits for your applications
  </Card>
  <Card title="Caching" icon="bolt" href="/features/advanced-usage/caching">
    Reduce costs and latency with intelligent caching
  </Card>
</CardGroup>