Build an AI Debate Simulator with Vercel AI Gateway

Learn how to create an interactive AI debate application that demonstrates four different integration approaches for Vercel AI Gateway with Helicone observability. This cookbook shows you how to support both streaming and non-streaming responses across different SDKs.

What You'll Build#

An AI debate simulator where:

Users can select topics and watch AI-generated debates
Four different integration methods showcase flexibility
Helicone provides complete observability for all approaches
Both streaming and non-streaming responses are supported

Prerequisites#

Next.js project with TypeScript
Vercel AI Gateway API key from your Vercel dashboard
Helicone API key from Helicone

Setup#

Install the required dependencies:

npm install @ai-sdk/openai @ai-sdk/gateway ai openai

Set up your environment variables:

VERCEL_AI_GATEWAY_API_KEY=your_vercel_gateway_keyHELICONE_API_KEY=your_helicone_key

Integration Methods#

1. Vercel AI SDK (Non-Streaming)#

Create a basic debate generation endpoint using the Vercel AI SDK:

// app/api/vercel-ai-debate/route.tsimport { createGateway } from '@ai-sdk/gateway';import { generateText } from 'ai';// Configure gateway with Heliconeconst gateway = createGateway({  apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY,  baseURL: "https://vercel.helicone.ai/v1/ai",  headers: {    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,  },});export async function POST(request: Request) {  const { topic, position } = await request.json();  try {    const result = await generateText({      model: gateway('openai/gpt-4o-mini'),      messages: [        {          role: 'system',          content: `You are a skilled debater. Argue ${position} the topic with passion and logic.`        },        {          role: 'user',          content: `Topic: ${topic}. Present your ${position} argument.`        }      ],      headers: {        'Helicone-Property-Topic': topic,        'Helicone-Property-Position': position,        'Helicone-Property-Method': 'vercel-ai-sdk'      },      temperature: 0.8,      maxTokens: 300    });    return Response.json({       argument: result.text,      usage: result.usage     });  } catch (error) {    console.error('Debate generation failed:', error);    return Response.json({ error: 'Failed to generate debate' }, { status: 500 });  }}

2. Vercel AI SDK (Streaming)#

Enable real-time debate streaming for better user experience:

// app/api/vercel-ai-stream/route.tsimport { createGateway } from '@ai-sdk/gateway';import { streamText } from 'ai';const gateway = createGateway({  apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY,  baseURL: "https://vercel.helicone.ai/v1/ai",  headers: {    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,  },});export async function POST(request: Request) {  const { topic, position } = await request.json();  const result = await streamText({    model: gateway('openai/gpt-4o-mini'),    messages: [      {        role: 'system',        content: `You are a skilled debater. Argue ${position} the topic.`      },      {        role: 'user',        content: `Topic: ${topic}. Present your ${position} argument.`      }    ],    headers: {      'Helicone-Property-Topic': topic,      'Helicone-Property-Position': position,      'Helicone-Property-Method': 'vercel-ai-stream',      'Helicone-Property-Stream': 'true'    },    temperature: 0.8,    maxTokens: 300  });  return result.toTextStreamResponse();}

3. OpenAI SDK (Non-Streaming)#

Use the OpenAI SDK directly with Vercel AI Gateway routing:

// app/api/openai-debate/route.tsimport OpenAI from 'openai';// Configure OpenAI client with Helicone-enabled Vercel AI Gatewayconst openai = new OpenAI({  apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY,  baseURL: "https://vercel.helicone.ai/v1",  defaultHeaders: {    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,  },});export async function POST(request: Request) {  const { topic, position } = await request.json();  try {    const completion = await openai.chat.completions.create({      model: 'gpt-4o-mini',      messages: [        {          role: 'system',          content: `You are a skilled debater. Argue ${position} the topic.`        },        {          role: 'user',          content: `Topic: ${topic}. Present your ${position} argument.`        }      ],      temperature: 0.8,      max_tokens: 300,      // Track metadata in Helicone      headers: {        'Helicone-Property-Topic': topic,        'Helicone-Property-Position': position,        'Helicone-Property-Method': 'openai-sdk'      }    });    return Response.json({       argument: completion.choices[0].message.content,      usage: completion.usage     });  } catch (error) {    console.error('OpenAI debate generation failed:', error);    return Response.json({ error: 'Failed to generate debate' }, { status: 500 });  }}

4. OpenAI SDK (Streaming)#

Enable streaming with the OpenAI SDK:

// app/api/openai-stream/route.tsimport OpenAI from 'openai';const openai = new OpenAI({  apiKey: process.env.VERCEL_AI_GATEWAY_API_KEY,  baseURL: "https://vercel.helicone.ai/v1",  defaultHeaders: {    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,  },});export async function POST(request: Request) {  const { topic, position } = await request.json();  const stream = await openai.chat.completions.create({    model: 'gpt-4o-mini',    messages: [      {        role: 'system',        content: `You are a skilled debater. Argue ${position} the topic.`      },      {        role: 'user',        content: `Topic: ${topic}. Present your ${position} argument.`      }    ],    temperature: 0.8,    max_tokens: 300,    stream: true,    headers: {      'Helicone-Property-Topic': topic,      'Helicone-Property-Position': position,      'Helicone-Property-Method': 'openai-stream',      'Helicone-Property-Stream': 'true'    }  });  // Convert OpenAI stream to Response stream  const encoder = new TextEncoder();  const readableStream = new ReadableStream({    async start(controller) {      for await (const chunk of stream) {        const text = chunk.choices[0]?.delta?.content || '';        controller.enqueue(encoder.encode(text));      }      controller.close();    }  });  return new Response(readableStream, {    headers: { 'Content-Type': 'text/plain; charset=utf-8' }  });}

Frontend Integration#

Create a debate interface that supports all integration methods:

// app/debate/page.tsx'use client';import { useState } from 'react';type IntegrationMethod = 'vercel-ai' | 'vercel-ai-stream' | 'openai' | 'openai-stream';export default function DebatePage() {  const [topic, setTopic] = useState('');  const [method, setMethod] = useState<IntegrationMethod>('vercel-ai-stream');  const [proArgument, setProArgument] = useState('');  const [conArgument, setConArgument] = useState('');  const [isLoading, setIsLoading] = useState(false);  const generateDebate = async () => {    setIsLoading(true);    setProArgument('');    setConArgument('');    try {      // Generate pro argument      const proResponse = await generateArgument(topic, 'for', method);      if (method.includes('stream')) {        await streamResponse(proResponse, setProArgument);      } else {        const data = await proResponse.json();        setProArgument(data.argument);      }      // Generate con argument      const conResponse = await generateArgument(topic, 'against', method);      if (method.includes('stream')) {        await streamResponse(conResponse, setConArgument);      } else {        const data = await conResponse.json();        setConArgument(data.argument);      }    } catch (error) {      console.error('Debate generation failed:', error);    } finally {      setIsLoading(false);    }  };  const generateArgument = async (topic: string, position: string, method: IntegrationMethod) => {    const endpoint = `/api/${method.replace('-stream', method.includes('stream') ? '-stream' : '-debate')}`;        return fetch(endpoint, {      method: 'POST',      headers: { 'Content-Type': 'application/json' },      body: JSON.stringify({ topic, position })    });  };  const streamResponse = async (response: Response, setter: (text: string) => void) => {    const reader = response.body?.getReader();    const decoder = new TextDecoder();    if (!reader) return;    while (true) {      const { done, value } = await reader.read();      if (done) break;            const chunk = decoder.decode(value);      setter(prev => prev + chunk);    }  };  return (    <div className="max-w-4xl mx-auto p-6">      <h1 className="text-3xl font-bold mb-6">AI Debate Simulator</h1>            <div className="mb-6 space-y-4">        <input          type="text"          value={topic}          onChange={(e) => setTopic(e.target.value)}          placeholder="Enter debate topic..."          className="w-full p-3 border rounded-lg"        />                <select          value={method}          onChange={(e) => setMethod(e.target.value as IntegrationMethod)}          className="w-full p-3 border rounded-lg"        >          <option value="vercel-ai">Vercel AI SDK</option>          <option value="vercel-ai-stream">Vercel AI SDK (Streaming)</option>          <option value="openai">OpenAI SDK</option>          <option value="openai-stream">OpenAI SDK (Streaming)</option>        </select>                <button          onClick={generateDebate}          disabled={!topic || isLoading}          className="w-full p-3 bg-blue-600 text-white rounded-lg disabled:opacity-50"        >          {isLoading ? 'Generating Debate...' : 'Start Debate'}        </button>      </div>      <div className="grid md:grid-cols-2 gap-6">        <div className="bg-green-50 p-6 rounded-lg">          <h2 className="text-xl font-semibold mb-3 text-green-800">Pro Argument</h2>          <p className="whitespace-pre-wrap">{proArgument || 'Waiting for debate to start...'}</p>        </div>                <div className="bg-red-50 p-6 rounded-lg">          <h2 className="text-xl font-semibold mb-3 text-red-800">Con Argument</h2>          <p className="whitespace-pre-wrap">{conArgument || 'Waiting for debate to start...'}</p>        </div>      </div>    </div>  );}

Monitoring in Helicone#

View comprehensive analytics for your debate simulator:

Method Comparison: Compare performance across integration methods
Topic Analytics: See which debate topics are most popular
Stream vs Non-Stream: Analyze latency and user experience differences
Cost Tracking: Monitor costs per debate and integration method

Custom Filters#

Use Helicone's property filters to analyze:

Performance by integration method: property:Method = "vercel-ai-stream"
Popular topics: Group by property:Topic
Streaming usage: Filter by property:Stream = "true"

Next Steps#

Sessions

Track multi-turn debates

Prompts

Manage debate templates

Rate Limiting

Control debate frequency

Custom Properties

Track debate metadata