/ai-orchestration-langchain

name: ai-orchestration-langchain
description: LangChain.js patterns for building LLM applications — chat models, LCEL chains, prompt templates, structured output, agents, tools, RAG, streaming, and LangSmith tracing

LangChain.js Patterns

> **Quick Guide:** Use LangChain.js (v1.x) to build composable LLM applications. Use LCEL (`prompt.pipe(model).pipe(parser)`) for all chain composition -- never use legacy `LLMChain`. Use `withStructuredOutput(zodSchema)` for typed responses. Use `createAgent()` (LangGraph-backed) for agentic workflows -- `AgentExecutor` is legacy. All `@langchain/*` packages must share the same `@langchain/core` version or you get cryptic type errors at runtime.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use LCEL pipe composition (`prompt.pipe(model).pipe(parser)`) for all chains -- never use legacy `LLMChain`, `ConversationChain`, or `SequentialChain`)**

**(You MUST ensure all `@langchain/*` packages depend on the same version of `@langchain/core` -- version mismatches cause cryptic runtime errors)**

**(You MUST use `withStructuredOutput(zodSchema)` for structured LLM responses -- never manually parse JSON from completion text)**

**(You MUST use `createAgent()` from `langchain` for new agent code -- `AgentExecutor` and `createToolCallingAgent` are legacy patterns)**

**(You MUST never hardcode API keys -- use environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.))**

</critical_requirements>

---

**Auto-detection:** LangChain, langchain, @langchain/core, @langchain/openai, @langchain/anthropic, @langchain/google-genai, ChatOpenAI, ChatAnthropic, ChatPromptTemplate, StringOutputParser, RunnableSequence, pipe, withStructuredOutput, createAgent, createToolCallingAgent, AgentExecutor, tool, DynamicStructuredTool, RecursiveCharacterTextSplitter, MemoryVectorStore, OpenAIEmbeddings, LCEL, LangSmith, LANGCHAIN_TRACING_V2

**When to use:**

• Building LLM applications that compose prompts, models, and output parsers into chains
• Creating agentic workflows where models decide which tools to call
• Implementing RAG pipelines with document loading, splitting, embedding, and retrieval
• Needing structured output from LLMs with type-safe Zod schema validation
• Streaming LLM responses token-by-token to users
• Switching between LLM providers (OpenAI, Anthropic, Google) with a unified interface
• Tracing and debugging LLM applications with LangSmith

**Key patterns covered:**

• Chat model initialization and provider switching (ChatOpenAI, ChatAnthropic, ChatGoogleGenerativeAI)
• LCEL chain composition with `.pipe()` and `RunnableSequence`
• Prompt templates (`ChatPromptTemplate`, `MessagesPlaceholder`)
• Structured output with `withStructuredOutput()` and Zod schemas
• Tool definition with `tool()` function and Zod schemas
• Agent creation with `createAgent()` (LangGraph-backed)
• RAG pipelines: document loaders, text splitters, vector stores, retrievers
• Streaming from chains, models, and agents
• LangSmith tracing setup

**When NOT to use:**

• You only call one LLM provider and want the thinnest wrapper -- use the provider's SDK directly
• You need React-specific chat UI hooks (`useChat`, `useCompletion`) -- use a framework-integrated AI SDK
• You want a simple single-call completion with no chaining -- a direct SDK call is simpler
• You need real-time bidirectional communication -- LangChain does not cover WebSocket/Realtime APIs

---

Examples Index

• [Core: Setup, LCEL & Chat Models](examples/core.md) -- Package installation, chat model init, LCEL chains, prompt templates, output parsers
• [Structured Output & Tools](examples/structured-output-tools.md) -- `withStructuredOutput`, tool definition, binding tools to models
• [Agents](examples/agents.md) -- `createAgent`, tool-calling agents, chat history, streaming agents
• [RAG Pipelines](examples/rag.md) -- Document loaders, text splitters, vector stores, retrieval chains
• [Streaming](examples/streaming.md) -- Model streaming, chain streaming, agent streaming
• [Quick API Reference](reference.md) -- Package map, import paths, environment variables, model IDs

---

<philosophy>

Philosophy

LangChain.js provides a **composable framework** for building LLM-powered applications. Its core abstraction is the **Runnable** -- any component that takes an input and produces an output. Runnables compose via LCEL (`.pipe()`) to form chains, and every Runnable supports `.invoke()`, `.stream()`, `.batch()` uniformly.

**Core principles:**

1. **Composability via LCEL** -- Chains are built by piping Runnables: `prompt.pipe(model).pipe(parser)`. Each step is independently testable and replaceable. Legacy chain classes (`LLMChain`, `ConversationChain`) are deprecated. 2. **Provider-agnostic models** -- Chat models (`ChatOpenAI`, `ChatAnthropic`, `ChatGoogleGenerativeAI`) share a common interface. Swap providers by changing one import and model name. Use `initChatModel()` for runtime provider selection. 3. **Type-safe structured output** -- `model.withStructuredOutput(zodSchema)` constrains LLM responses to your schema. No manual JSON parsing. 4. **Split package architecture** -- `@langchain/core` holds abstractions, provider packages (`@langchain/openai`, `@langchain/anthropic`) hold implementations, `langchain` holds higher-level composables. All must share the same `@langchain/core` version. 5. **Observability built in** -- Set `LANGCHAIN_TRACING_V2=true` and every chain/agent/tool call is traced to LangSmith automatically.

**When to use LangChain:**

• You need to compose multi-step LLM workflows (prompt -> model -> parser -> next step)
• You want to swap LLM providers without rewriting business logic
• You need agent-style tool calling with automatic routing
• You need RAG with document loading, chunking, embedding, and retrie