> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inquantum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK Integration

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

export const strings = {
  additionalHeadersForSessions: "Planck provides additional headers to help you manage and analyze your sessions.",
  azureOpenAIDocs: `To learn more about the differences between OpenAI and AzureOpenAI, review the <a href="https://learn.microsoft.com/en-us/azure/ai-services/openai/overview">documentation here</a>.`,
  chainOfThoughtPromptingCookbookDescription: "Craft effective prompts, ideal for complex responses requiring multi-step problem solving.",
  chatbotCookbookDescription: "This step-by-step guide covers function calling, response formatting and monitoring with Planck.",
  createPlanckManualLogger: "Create a new PlanckManualLogger instance",
  configureWebSocketConnection: "Configure WebSocket connection",
  environmentTrackingCookbookDescription: "Effortlessly track and manage your environments with Planck across different deployment contexts.",
  exportBaseUrl: tool => `Export your ${tool} base URL`,
  getStartedWithPackage: "To get started, install the @inquantum/planck-helpers package",
  generateKey: "Create an account and generate an API key",
  generateKeyInstructions: `Log into <a href="https://www.inquantum.ai" target="_blank">Planck</a> or create an account. Once you have an account, you can generate an <a href="https://inquantum.ai/developer" target="_blank">API key here</a>.`,
  generateSessionId: "Generate the unique session ID that will be used to track the session.",
  gettingUserRequestsCookbookDescription: "Retrieve user-specific requests to monitor, debug, and track costs for individual users.",
  groupingCallsWithSessions: "Grouping Calls with Planck Sessions",
  handleWebSocketEvents: "Handle WebSocket events",
  planckLoggerAPIReference: `To learn more about the <code>PlanckManualLogger</code> API, see the <a href="/getting-started/integration-method/custom" target="_blank">API Reference here</a>.`,
  howToIntegrate: "How to Integrate",
  howToPromptThinkingModelsCookbookDescription: "Best practices to to effectively prompt thinking models like Deepseek and OpenAI o1-o3 for optimal results.",
  howToUseSessions: "To group related API calls and analyze them collectively, you can use Planck's session tracking features. This is useful for grouping all interactions within a single conversation or user session.",
  includeHeadersInRequests: "Include headers in your requests",
  includeSessionHeaders: "Include the session headers when you make API requests. This way, the session information is attached to each request, allowing Planck to group and analyze them together.",
  installRequiredDependencies: "Install required dependencies",
  installSDK: tool => `Install ${tool}`,
  logYourRequest: "Log your request",
  modifyBasePath: "Modify the base URL path and set up authentication",
  optional: "Optional",
  relatedGuides: "Related documentation",
  replayLlmSessionsCookbookDescription: "Learn how to replay and modify LLM sessions using Planck to optimize your AI agents and improve their performance.",
  sessionManagement: "Session Management",
  setApiKey: "Set up your Planck API key in your .env file",
  setUpToolBaseUrl: tool => `Set up your ${tool} base URL`,
  setUpToolApiKey: tool => `Set up your ${tool} API key as an environment variable`,
  startUsing: tool => `Start using ${tool} with Planck`,
  useTheSDK: tool => `Use the ${tool} SDK`,
  verifyInPlanck: "Verify your requests in Planck",
  verifyInPlanckDescription: tool => `With the above setup, any calls to ${tool} will automatically be logged and monitored by Planck. Review them in your <a href="https://www.inquantum.ai/dashboard" target="_blank">Planck dashboard</a>.`,
  whyUseSessions: "By including the session headers in each request, you have more granular control over session tracking. This approach is especially useful if you want to handle sessions dynamically or manage multiple sessions concurrently.",
  viewRequestsInDashboard: "View requests in the Planck dashboard",
  viewRequestsInDashboardDescription: product => `All your ${product} requests are now visible in your <a href="https://us.inquantum.ai/dashboard" target="_blank">Planck dashboard</a>`,
  modelRegistryDescription: "You can find all 100+ supported models at <a href=\"https://inquantum.ai/models\" target=\"_blank\">inquantum.ai/models</a>."
};

## 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 Planck provider for Vercel AI SDK lives in this repository as the
  `@inquantum/planck-ai-sdk-provider` workspace package.
</Note>

<Warning>
  The provider is not published to npm yet. The checked-in Next.js example
  consumes it through a local `file:` dependency. Publish the package before
  using the npm, pnpm, Yarn, or Bun registry commands in an external project.
</Warning>

## Integration Steps

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

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

  {" "}

  <Step title={strings.setApiKey}>`bash PLANCK_API_KEY=sk-planck-... `</Step>

  <Step title="Install the local Planck AI SDK provider">
    The example declares the workspace package as a local dependency:

    ```json theme={null}
    {
      "dependencies": {
        "@inquantum/planck-ai-sdk-provider": "file:../../packages/ai-sdk-provider"
      }
    }
    ```

    Build the unpublished package, then install the example:

    ```bash theme={null}
    cd packages/ai-sdk-provider
    npm ci --workspaces=false
    npm run build
    cd ../../examples/vercel-ai-sdk-example
    npm ci
    ```
  </Step>

  <Step title="Configure Vercel AI SDK with Planck">
    ```typescript theme={null}
    import { createPlanck } from '@inquantum/planck-ai-sdk-provider';
    import { generateText } from 'ai';

    // Initialize Planck provider
    const planck = createPlanck({
      apiKey: process.env.PLANCK_API_KEY
    });

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

    console.log(result.text);
    ```

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

## Complete Working Examples

### Basic Text Generation

```typescript theme={null}
import { createPlanck } from "@inquantum/planck-ai-sdk-provider";
import { generateText } from "ai";

const planck = createPlanck({
  apiKey: process.env.PLANCK_API_KEY,
});

const { text } = await generateText({
  model: planck("gemini-2.5-flash-lite"),
  prompt: "What is Planck?",
});

console.log(text);
```

### Streaming Text

```typescript theme={null}
import { createPlanck } from "@inquantum/planck-ai-sdk-provider";
import { streamText } from "ai";

const planck = createPlanck({
  apiKey: process.env.PLANCK_API_KEY,
});

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

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

console.log("\n\nStream completed!");
```

### Provider Selection

By default, Planck's AI gateway automatically routes to the cheapest provider. You can also manually select a specific provider:

```typescript theme={null}
import { createPlanck } from "@inquantum/planck-ai-sdk-provider";
import { generateText } from "ai";

const planck = createPlanck({
  apiKey: process.env.PLANCK_API_KEY,
});

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

// Manual provider selection
const manualResult = await generateText({
  model: planck("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 fallbackResult = await generateText({
  model: planck("claude-4.5-sonnet/anthropic,gpt-4o/openai"),
  prompt: "Hello!",
});
```

### With Custom Properties and Session Tracking

```typescript theme={null}
import { createPlanck } from "@inquantum/planck-ai-sdk-provider";
import { generateText } from "ai";

const planck = createPlanck({
  apiKey: process.env.PLANCK_API_KEY,
});

const result = await generateText({
  model: planck("claude-4.5-haiku", {
    requestMetadata: {
      requestId: crypto.randomUUID(),
      sessionId: "my-session",
      userId: "user-123",
      properties: {
        environment: "production",
        appVersion: "2.1.0",
        feature: "quantum-explanation",
      },
    },
  }),
  prompt: "Explain quantum computing",
});
```

### Tool Calling

```typescript theme={null}
import { createPlanck } from "@inquantum/planck-ai-sdk-provider";
import { generateText, tool } from "ai";
import { z } from "zod";

const planck = createPlanck({
  apiKey: process.env.PLANCK_API_KEY,
});

const result = await generateText({
  model: planck("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) => {
        return `It's sunny in ${args.location}`;
      },
    }),
  },
});

console.log(result.text);
```

### Planck Prompts Integration

Use prompts created in your Planck dashboard instead of hardcoding messages in your application:

```typescript theme={null}
import { createPlanck } from "@inquantum/planck-ai-sdk-provider";
import type { WithPlanckPrompt } from "@inquantum/planck-ai-sdk-provider";
import { generateText } from "ai";

const planck = createPlanck({
  apiKey: process.env.PLANCK_API_KEY,
});

const result = await generateText({
  model: planck("gpt-4o", {
    promptId: "sg45wqc",
    inputs: {
      customer_name: "Sarah Johnson",
      issue_type: "billing",
      account_type: "premium",
    },
    environment: "production",
    requestMetadata: {
      sessionId: "support-session-123",
      properties: {
        department: "customer-support",
      },
    },
  }),
  messages: [{ role: "user", content: "placeholder" }],
} as WithPlanckPrompt);
```

<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 Planck dashboard, and the placeholder messages will be
  ignored.
</Note>

**Benefits of using Planck prompts:**

* 🎯 **Centralized Management**: Update prompts without code changes
* 👩🏻‍💻 **Perfect for non-technical users**: Create prompts using the Planck 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 a complete Geist-style Next.js application, see the
[Vercel AI SDK example](https://github.com/In-Quantum/planck/tree/main/examples/vercel-ai-sdk-example).
It includes routed examples for chat streaming, model discovery, embeddings,
image generation, asynchronous video generation, and request feedback. The
example consumes the unpublished provider directly from this monorepo.

## Related Documentation

<CardGroup cols={2}>
  <Card title="AI Gateway Overview" icon="arrow-progress" href="/gateway/overview">
    Learn about Planck'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://inquantum.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 Planck 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>

## Additional Resources

* [Vercel AI SDK Documentation](https://sdk.vercel.ai)
* [Local Planck AI SDK provider](https://github.com/In-Quantum/planck/tree/main/packages/ai-sdk-provider)