mdc-langchain-js

langchain-js Best Practices

Building LLM-powered applications with langchain-js requires a disciplined approach to ensure maintainability, performance, and reliability. This guide outlines our team's definitive best practices.

1. Code Organization and Structure

Always prioritize modularity and explicit typing. Break down complex logic into small, reusable components.

1.1. Modular Components & Single Responsibility

Each LangChain component (Agent, Tool, Chain, Model) should reside in its own file or a dedicated module, adhering to the Single Responsibility Principle.

❌ BAD: Monolithic file

// src/agent.js
import { ChatOpenAI } from "@langchain/openai";
import { createAgent, tool } from "langchain";
import { z } from "zod";

const getStockPrice = tool(async ({ ticker }) => { /* ... */ }, { /* ... */ });
const getNews = tool(async ({ query }) => { /* ... */ }, { /* ... */ });

const model = new ChatOpenAI({ temperature: 0.7 });
const agent = createAgent({
  model,
  tools: [getStockPrice, getNews],
});

export async function runFinancialAgent(input) {
  return agent.invoke(input);
}

✅ GOOD: Modular, reusable components

// src/tools/getStockPrice.ts
import { tool } from "langchain";
import { z } from "zod";

export const getStockPriceTool = tool(
  async ({ ticker }: { ticker: string }) => {
    // Simulate API call
    if (ticker === "AAPL") return "$170.00";
    return "Price not found.";
  },
  {
    name: "get_stock_price",
    description: "Get the current stock price for a given ticker symbol.",
    schema: z.object({
      ticker: z.string().describe("The stock ticker symbol (e.g., AAPL)"),
    }),
  }
);

// src/tools/getNews.ts
import { tool } from "langchain";
import { z } from "zod";

export const getNewsTool = tool(
  async ({ query }: { query: string }) => {
    // Simulate API call
    return `Latest news for ${query}: Market is up!`;
  },
  {
    name: "get_news",
    description: "Get the latest news for a given query.",
    schema: z.object({
      query: z.string().describe("The news query"),
    }),
  }
);

// src/agents/financialAgent.ts
import { ChatOpenAI } from "@langchain/openai";
import { createAgent } from "langchain";
import { getStockPriceTool } from "tools/getStockPrice";
import { getNewsTool } from "tools/getNews";

const model = new ChatOpenAI({ temperature: 0.7 });

export const financialAgent = createAgent({
  model,
  tools: [getStockPriceTool, getNewsTool],
});

// src/index.ts (or wherever the agent is invoked)
import { financialAgent } from "./agents/financialAgent";

async function main() {
  const result = await financialAgent.invoke({
    messages: [{ role: "user", content: "What's the price of AAPL and the latest market news?" }],
  });
  console.log(result);
}

main();