Punk Docs - Vercel AI SDK

Vercel AI SDK Integration

Punk works with the Vercel AI SDK through the OpenAI-compatible provider. Create a provider with Punk's baseURL, keep using generateText, streamText, tools, and structured output, and let Punk observe, cache, govern, and explain the traffic behind the scenes.

Use this path when an app already uses ai and wants a gateway-agnostic model route behind the same AI SDK interface.

Install

npm install ai @ai-sdk/openai-compatible @punktechnologies/sdk

Create a Punk tenant API key in the hosted dashboard:

export PUNK_BASE_URL=https://app.punktechnologies.com
export PUNK_API_KEY=pk_...

Provider keys and BYOK credentials live in Punk's hosted control plane, not in this app.

Provider Setup

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";
import { createPunkVercelAIConfig } from "@punktechnologies/sdk/vercel-ai";

const punk = createOpenAICompatible(createPunkVercelAIConfig({
  app: "web-app",
  agent: "support-agent",
  subject: "user-123"
}));

const result = await generateText({
  model: punk("gpt-4o-mini"),
  temperature: 0,
  system: "Classify the ticket: billing, bug, or how-to. Answer with one word.",
  prompt: "The export button crashes the app."
});

console.log(result.text);

The model call still uses the Vercel AI SDK interface. Punk receives the OpenAI-compatible HTTP request and records the run. The config helper can read PUNK_BASE_URL, PUNK_API_KEY, PUNK_APP, PUNK_AGENT, and PUNK_SUBJECT; explicit options override those values.

Streaming

Use streamText the same way:

import { streamText } from "ai";

const stream = streamText({
  model: punk("gpt-4o-mini"),
  prompt: "Draft a short support reply."
});

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

Punk proxies live provider SSE chunks through unchanged. Cached and artifact-served responses are replayed as short compatible streams so existing consumers keep working.

Route Evidence

Depending on SDK version and adapter path, response headers may be available on the result metadata. When they are not surfaced, read the route story from the Punk dashboard or API:

curl -H "Authorization: Bearer $PUNK_API_KEY" \
  https://app.punktechnologies.com/api/v1/runs \
  | jq '.runs[0].routeExplanation'

Send the same deterministic prompt twice. The first run should route live, governed, or blocked according to tenant policy; the repeat can hit exact_cache when the request is cache-eligible.

When To Use `@punktechnologies/sdk`

The Vercel AI SDK path is enough for model traffic. Use the root Punk client in the same process when you need app-side features such as tool tracing, side-effect declarations, read-only tool-result caching, feedback, SOM web fetches, receipts, evidence packets, and artifact lifecycle APIs. For direct SDK calls, use client.openai.chat(...), client.streamChat(...), and client.withRun(...).

//DOCS Vercel AI SDK