LangChain Integration - Helicone OSS LLM Observability

Introduction#

LangChain is a popular open-source framework for building applications with large language models across Python, TypeScript, and other languages. By integrating Helicone AI Gateway with LangChain, you can:

Route to different models & providers with automatic failover through a single endpoint
Unified billing with pass-through billing or bring your own keys
Monitor all requests with automatic cost tracking in one dashboard
Stream responses with full observability for real-time applications

Note

This integration requires only two changes to your existing LangChain code - updating the base URL and API key.

Integration Steps#

Create an account + Generate an API Key

Note

You'll also need to configure your provider API keys (OpenAI, Anthropic, etc.) at Helicone Providers for BYOK (Bring Your Own Keys).

Set environment variables

# Your Helicone API keyexport HELICONE_API_KEY=<your-helicone-api-key>

Create a .env file in your project:

HELICONE_API_KEY=sk-helicone-...

Install LangChain packages

npm install @langchain/openai @langchain/core dotenv# oryarn add @langchain/openai @langchain/core dotenv

Configure LangChain with Helicone AI Gateway

import { ChatOpenAI } from "@langchain/openai";import { HumanMessage, SystemMessage } from "@langchain/core/messages";import dotenv from 'dotenv';dotenv.config();// Initialize ChatOpenAI with Helicone AI Gatewayconst chat = new ChatOpenAI({    model: 'gpt-4.1-mini',  // 100+ models supported    apiKey: process.env.HELICONE_API_KEY,    configuration: {        baseURL: "https://ai-gateway.helicone.ai/v1",        defaultHeaders: {            // Optional: Add custom tracking headers            "Helicone-Session-Id": "my-session",            "Helicone-User-Id": "user-123",            "Helicone-Property-Environment": "production",        },    },});

Info

The only changes from a standard LangChain setup are the apiKey, baseURL (or base_url in Python), and optional tracking headers. Everything else stays the same!

You can find all 100+ supported models at helicone.ai/models.

Use LangChain normally

Your existing LangChain code continues to work without any changes:

// Simple completionconst response = await chat.invoke([    new SystemMessage("You are a helpful assistant."),    new HumanMessage("What is the capital of France?"),]);console.log(response.content);

View requests in the Helicone dashboard

All your LangChain requests are now visible in your Helicone dashboard.

Request/response bodies
Latency metrics
Token usage and costs
Model performance analytics
Error tracking
Session tracking

Tip

While you're here, why not give us a star on GitHub? It helps us a lot!

Migration Example#

Here's what migrating an existing LangChain application looks like:

Before (Direct OpenAI)#

import { ChatOpenAI } from "@langchain/openai";const chat = new ChatOpenAI({    model: 'gpt-4o-mini',    apiKey: process.env.OPENAI_API_KEY,});

After (Helicone AI Gateway)#

import { ChatOpenAI } from "@langchain/openai";const chat = new ChatOpenAI({    model: 'gpt-4.1-mini',                      // 100+ models supported    apiKey: process.env.HELICONE_API_KEY,      // Your Helicone API key    configuration: {        baseURL: "https://ai-gateway.helicone.ai/v1"  // Add this!    },});

That's it! Just two changes and you're routing through Helicone's AI Gateway.

Complete Working Examples#

Basic Example#

import { ChatOpenAI } from "@langchain/openai";import { HumanMessage, SystemMessage } from "@langchain/core/messages";import dotenv from 'dotenv';dotenv.config();const chat = new ChatOpenAI({    model: 'gpt-4.1-mini',  // 100+ models supported    apiKey: process.env.HELICONE_API_KEY,    configuration: {        baseURL: "https://ai-gateway.helicone.ai/v1",        defaultHeaders: {            "Helicone-Session-Id": "langchain-example",            "Helicone-User-Id": "demo-user",        },    },});async function main() {    console.log('🦜 Starting LangChain + Helicone AI Gateway example...\n');    const response = await chat.invoke([        new SystemMessage("You are a helpful assistant."),        new HumanMessage("Tell me a joke about programming."),    ]);    console.log('🤖 Assistant response:');    console.log(response.content);    console.log('\n✅ Completed successfully!');}main().catch(console.error);

Streaming Example#

async function streamingExample() {    console.log('\n🌊 Streaming example...\n');    const stream = await chat.stream([        new SystemMessage("You are a helpful assistant."),        new HumanMessage("Write a short story about a robot learning to code."),    ]);    console.log('🤖 Assistant (streaming):');    for await (const chunk of stream) {        process.stdout.write(chunk.content as string);    }    console.log('\n\n✅ Streaming completed!');}streamingExample().catch(console.error);

Multiple Models Example#

async function testMultipleModels() {    console.log('🚀 Testing multiple models through Helicone AI Gateway\n');    const models = [        { id: 'gpt-4.1-mini', name: 'OpenAI GPT-4.1 Mini' },        { id: 'claude-opus-4-1', name: 'Anthropic Claude Opus 4.1' },        { id: 'gemini-2.5-flash-lite', name: 'Google Gemini 2.5 Flash Lite' },    ];    for (const model of models) {        try {            const chat = new ChatOpenAI({                model: model.id,                apiKey: process.env.HELICONE_API_KEY,                configuration: {                    baseURL: "https://ai-gateway.helicone.ai/v1",                },            });            console.log(`🤖 Testing ${model.name}... `);            const response = await chat.invoke([                new HumanMessage("Say hello in one sentence."),            ]);            console.log(`   Response: ${response.content}\n`);        } catch (error) {            console.error(`   Error: ${error}\n`);        }    }    console.log('✅ All models tested!');    console.log('🔍 Check your dashboard: https://us.helicone.ai/dashboard');}testMultipleModels().catch(console.error);

Batch Processing Example (Python)#

Python

def batch_example():    print('\n📦 Batch processing example...\n')    message_batches = [        [HumanMessage(content="What is Python?")],        [HumanMessage(content="What is JavaScript?")],        [HumanMessage(content="What is TypeScript?")],    ]    responses = chat.batch(message_batches)    print('🤖 Batch responses:')    for i, response in enumerate(responses, 1):        print(f'\nResponse {i}: {response.content}')    print('\n✅ Batch processing completed!')batch_example()

Helicone Prompts Integration#

You can use Helicone Prompts for centralized prompt management and versioning by passing parameters through modelKwargs:

const chat = new ChatOpenAI({    model: 'gpt-4.1-mini',    apiKey: process.env.HELICONE_API_KEY,    modelKwargs: {        prompt_id: 'customer-support-prompt',        version_id: 'version-uuid',        environment: 'production',        inputs: { customer_name: 'John', issue_type: 'billing' },    },    configuration: {        baseURL: "https://ai-gateway.helicone.ai/v1",    },});

Note

All prompt parameters (prompt_id, version_id, environment, inputs) are optional. Learn more about Prompts with AI Gateway.

Custom Headers and Properties#

You can add custom properties to track and filter your requests:

const chat = new ChatOpenAI({    model: 'gpt-4.1-mini',    apiKey: process.env.HELICONE_API_KEY,    configuration: {        baseURL: "https://ai-gateway.helicone.ai/v1",        defaultHeaders: {            // Session tracking            "Helicone-Session-Id": "session-abc-123",            "Helicone-Session-Name": "Customer Support Chat",            "Helicone-Session-Path": "/support/chat/456",            // User tracking            "Helicone-User-Id": "user-789",            // Custom properties for filtering            "Helicone-Property-Environment": "production",            "Helicone-Property-App-Version": "2.1.0",            "Helicone-Property-Feature": "customer-support",            // Rate limiting (optional)            "Helicone-Rate-Limit-Policy": "basic-100",        },    },});