Master Langchain.js Runnable: Build Custom Executable Chains in JavaScript

1. What is Runnable?

Runnable is a core interface in Langchain.js v0.3 that represents an executable operation, allowing developers to encapsulate models, processing logic, or other tasks as reusable objects.

Key characteristics of Runnable include:

Flexible input and output types.

Chainable calls to form execution pipelines.

Asynchronous support for API or model interactions.

In short, Runnable is an abstract concept that helps organize code logic in complex front‑end applications.

2. Basic Usage of the Runnable Interface

Langchain.js provides a basic Runnable interface with a single invoke method that receives input data and returns a result.

interface Runnable { invoke(input: any): Promise; }

Implementing this interface lets you wrap custom logic into a Runnable.

3. Implementing a Custom Runnable

Example: a Runnable that converts input text to uppercase.

import { Runnable } from 'langchain';
class UppercaseRunnable implements Runnable {
  async invoke(input: string): Promise {
    // Convert the input string to uppercase
    return input.toUpperCase();
  }
}

The UppercaseRunnable class implements Runnable and transforms the input string to uppercase in its invoke method.

4. Integrating Custom Models with Runnable

You can also wrap third‑party models or APIs. The following example shows a Runnable that sends text to a classification API and returns the predicted category.

import { Runnable } from "langchain";
class TextClassificationRunnable implements Runnable {
  private apiUrl: string;
  constructor(apiUrl: string) {
    this.apiUrl = apiUrl;
  }
  async invoke(input: string): Promise {
    const response = await fetch(this.apiUrl, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ text: input }),
    });
    const data = await response.json();
    return data.category;
  }
}

This class sends the input text to the specified API and returns the classification result, making model integration straightforward in front‑end code.

5. Using Custom Runnables Together

By combining the two Runnables, you can build a simple execution chain: first convert text to uppercase, then classify it.

async function main() {
  const uppercaseRunnable = new UppercaseRunnable();
  const textClassificationRunnable = new TextClassificationRunnable("https://api.com/v1");
  const input = "hello world"; // Convert to uppercase first
  const uppercasedInput = await uppercaseRunnable.invoke(input);
  const category = await textClassificationRunnable.invoke(uppercasedInput);
  console.log(`Classification result: ${category}`);
}
main();

This demonstrates how the Runnable interface enables clear, reusable, and composable logic for front‑end AI applications.

6. Summary

The Runnable interface in Langchain.js v0.3 offers front‑end developers a concise and powerful way to encapsulate and manage complex logic, whether for simple text processing or integrating third‑party AI models, providing flexibility and reusability.