Build LangChain TypeScript App
Build LangChain.js v1 and LangGraph.js applications in TypeScript. Choose one implementation path before coding, keep the spine small, and load only the bundled references the chosen path needs.
When to use this skill
- Building a tool-calling assistant with
createAgent from langchain and Zod-typed tools.
- Wiring a RAG pipeline with a
Document loader, splitter, embeddings, vector store, and retriever.
- Authoring a raw
StateGraph from @langchain/langgraph with explicit state, routing, fan-out/fan-in, or interrupts.
- Adding structured output via
withStructuredOutput, responseFormat, toolStrategy, or providerStrategy.
- Streaming tokens, events, or graph updates back to a UI/API and handling cancellation.
- Persisting agent/graph state with checkpointers, stores, or
thread_id-keyed memory.
- Connecting MCP servers as namespaced tools through
@langchain/mcp-adapters.
- Composing supervisor/router/handoff multi-agent or knowledge-domain agents in TypeScript.
Do not use this skill when:
- The codebase is Python LangChain / LangGraph — TypeScript-only patterns here will mislead.
- A simple single-provider chat call (e.g.,
openai.chat.completions.create) is enough — pull in the provider SDK directly.
- The agent runtime is
mcp-use MCPAgent — use build-mcp-use-agent.
- The core runtime is Effect /
@effect/* even if it calls LLMs — use build-effect-ts-v3.
Trigger signals (imports and idioms)
Treat these as the strong-positive signals for this skill:
| Signal |
Example |
langchain package import |
import { createAgent } from "langchain" |
@langchain/core/* |
import { tool } from "@langchain/core/tools" |
@langchain/langgraph |
import { StateGraph, MemorySaver, Annotation } from "@langchain/langgraph" |
| Provider packages |
@langchain/openai, @langchain/anthropic, @langchain/google-genai, @langchain/azure-openai |
| Retrieval stack |
@langchain/textsplitters, RecursiveCharacterTextSplitter, OpenAIEmbeddings, InMemoryVectorStore, *.asRetriever() |
| MCP adapters |
import { MultiServerMCPClient } from "@langchain/mcp-adapters" |
| Structured output / streaming |
model.withStructuredOutput(schema), responseFormat, toolStrategy, providerStrategy, agent.stream(..., { streamMode: "updates" }) |
| Persistence |
MemorySaver, checkpointer, thread_id, store |
| LangSmith |
langsmith, LANGSMITH_API_KEY, traceable, openevals |
If none of these appear and the task is plain chat completion, route away from this skill.
Preflight
Before coding, inspect the target repo and record:
package.json: module type, scripts, framework, existing LangChain packages, and test command.- Runtime: Node.js 20+ and TypeScript 5+; stop and fix lower versions before debugging LangChain behavior.
- Installed versions:
npm ls langchain @langchain/core @langchain/langgraph @langchain/openai when dependencies are installed; for drift checks use references/start/version-discipline.md.
- Version script: run
scripts/check-langchain-versions.sh for a read-only package report; docs live in scripts/check-langchain-versions.sh.md.
- Provider environment:
OPENAI_API_KEY, OPENROUTER_API_KEY, Anthropic/Google/Azure keys, LangSmith keys, MCP credentials.
- Work mode: greenfield scaffold vs existing app integration; for existing apps, follow local file layout and test conventions.
- Greenfield utility: use
scripts/scaffold-createagent-app.sh only for a minimal createAgent app; docs live in scripts/scaffold-createagent-app.sh.md.
For first-runnable apps and recovery from common failures, consult references/start/getting-started.md and references/start/common-errors.md.
Choose the path (load-bearing)
Force the architecture choice before writing code:
- Tool-calling assistant: choose
createAgent when external actions or business functions are needed and graph state/routing is not explicit.
- 2-step RAG: choose deterministic retrieval plus answer generation when every query requires retrieval and predictable latency matters.
- Agentic RAG: expose the retriever as a tool when retrieval is one possible action among several.
- Raw LangGraph: use
StateGraph only when the app needs explicit state, routing, interrupts, fan-out/fan-in, or durable graph execution.
| Path |
Output shape |
First reference |
Verification |
createAgent tool-calling assistant |
Messages state plus optional structuredResponse; tools call real project functions. |
references/agents/agents.md, then references/agents/tools.md |
Assert tool call/result behavior, final message, max-step limit, optional structured response. |
| RAG pipeline |
Answer plus retrieved/source Document[], citations, grounding metadata. |
references/rag/rag.md |
Assert retrieval count, source IDs, answer contract, no-answer behavior. |
Raw StateGraph |
Typed graph state returned from invoke/stream; transitions are explicit. |
references/langgraph/langgraph.md, then references/langgraph/langgraph-execution.md |
Assert node outputs, conditional routes, recursion limit, persisted state when enabled. |
| Structured output |
Validated schema object or explicit parse/retry failure path. |
references/agents/structured-output.md |
Assert schema success, invalid-output handling, provider/tool strategy behavior. |
| Streaming UI/API |
Chosen token/event/update contract with cancellation and error events. |
references/agents/streaming.md |
Assert event order, chunk shape, completion signal, abort behavior. |
| Human-in-the-loop |
Interrupted graph paused on review/edit/approve nodes. |
references/langgraph/human-in-the-loop.md |
Assert interrupt payload, resume path, replay behavior. |
| MCP integration |
Namespaced MCP tools, lifecycle management, explicit auth/transport config. |
references/providers/mcp.md |
Assert server connection, tool discovery/filtering, timeout, cleanup, credential failure. |
| Memory / persistence |
Stable thread_id, selected checkpointer/store, retention rules, replay. |
references/langgraph/memory-checkpointers.md plus references/langgraph/memory-stores.md |
Assert multi-turn continuity, isolation between threads, persistence across restart if durable. |
| Multi-agent / knowledge-domain |
Supervisor/router/handoff state plus domain safety constraints. |
references/agents/multi-agent.md or references/agents/knowledge-agents.md |
Assert route selection, handoff messages, domain guardrails, failure fallback. |
Implementation contracts
- Match tests to the selected output contract. Do not claim the path works if tests only assert an LLM text substring.
- Keep real side effects behind tools with Zod schemas and deterministic unit tests.
- Use
toolStrategy as the portable structured-output default; choose providerStrategy only when the selected provider is known to support it.
- Token-level streaming and strictly validated structured output often need different contracts. Choose raw-token streaming with parse-on-completion, event streaming, or non-streaming structured output deliberately.
- Start with one path end-to-end, then layer memory, streaming, middleware, or observability.
Version and package discipline
Use path-specific package subsets and pin compatible versions in real apps:
| Path |
Baseline packages |
createAgent |
langchain @langchain/core zod plus a provider package such as @langchain/openai |
| RAG |
langchain @langchain/core @langchain/openai @langchain/textsplitters zod plus the chosen vector-store package |
| Raw LangGraph |
@langchain/langgraph @langchain/core zod plus provider/checkpointer packages as needed |
| MCP |
langchain @langchain/core @langchain/mcp-adapters @modelcontextprotocol/sdk zod |
| LangSmith eval/tracing |
langsmith plus openevals only when evaluation workflows need it |
Use @latest only in update commands or exploratory refreshes, not as the documented tested state. When package APIs matter, verify the current package matrix before editing examples and record the research date. See references/start/version-discipline.md.
For existing apps, run scripts/check-langchain-versions.sh before diagnosing API drift or changing package pins. The paired docs are scripts/check-langchain-versions.sh.md.
For greenfield createAgent demos, run scripts/scaffold-createagent-app.sh to generate the smallest pinned TypeScript app. The paired docs are scripts/scaffold-createagent-app.sh.md.
RAG reliability defaults
For RAG, make these decisions before implementation:
| Decision |
Local default |
Production requirement |
| Corpus size / update cadence |
Small static fixture |
Ingestion and re-indexing plan |
| Embedding model / dimension |
OpenAIEmbeddings, text-embedding-3-small |
Stable model, recorded dimension, migration plan |
| Vector store |
InMemoryVectorStore |
Persistent store with backups and filters |
| Metadata filtering |
Source ID only |
Typed metadata schema and filter tests |
| Retriever type |
Similarity retriever |
Chosen retriever/reranker based on eval results |
| Grounding contract |
Return source documents |
Citations, refusal/no-answer policy, regression eval |
| Evaluation metric |
Manual smoke test |
Retrieval recall, faithfulness, answer relevance |
Production guardrails
Before productionizing any path, define max steps or recursion limits, token budget, retry/fallback policy, rate-limit strategy, and failure surface. Route details to references/middleware/middleware-catalog.md, references/middleware/middleware-patterns.md, references/ops/observability-tracing.md, and references/ops/observability-evaluation.md.
For deployment shape and platform constraints (Node version, edge runtimes, container/cloud targets), read references/ops/deployment-local.md and references/ops/deployment-production.md.
For provider/model selection, capability differences, and key wiring, read references/providers/models.md and references/providers/providers.md.
Use LangSmith/observability for development debugging, production traces, cost/token tracking, RAG evaluation, and user feedback or online evals. Verify current pricing before quoting costs.
Reference routing
Load only the files needed for the selected path.
| Intent |
Read |
| First runnable app, baseline commands, version drift |
references/start/getting-started.md, references/start/common-errors.md, references/start/version-discipline.md |
| Agent orchestration and tool contracts |
references/agents/agents.md, references/agents/tools.md |
| Structured output and streaming |
references/agents/structured-output.md, references/agents/streaming.md |
| Multi-agent and knowledge-domain agents |
references/agents/multi-agent.md, references/agents/knowledge-agents.md |
| Raw LangGraph execution |
references/langgraph/langgraph.md, references/langgraph/langgraph-execution.md, references/langgraph/human-in-the-loop.md |
| Memory and persistence |
references/langgraph/memory-checkpointers.md, references/langgraph/memory-stores.md |
| RAG |
references/rag/rag.md |
| Middleware and guardrails |
references/middleware/middleware-catalog.md, references/middleware/middleware-patterns.md |
| Models, providers, and MCP |
references/providers/models.md, references/providers/providers.md, references/providers/mcp.md |
| Local and production deployment |
references/ops/deployment-local.md, references/ops/deployment-production.md |
| Tracing, evaluation, and online feedback |
references/ops/observability-tracing.md, references/ops/observability-evaluation.md |
| Deterministic utilities |
scripts/check-langchain-versions.sh.md, scripts/scaffold-createagent-app.sh.md |
Scope boundaries
- Use LangChain.js and LangGraph.js v1 TypeScript APIs only.
- Keep Python-only guidance out of TypeScript implementations.
- Keep legacy v0 imports such as
langchain/chains only when documenting migrations or anti-patterns.
- Do not rely on in-memory checkpointers, stores, vector stores, or caches for production persistence.
- Do not assume provider feature parity; verify model/tool/structured-output/streaming support before coding against it.
1---2name: build-langchain-ts-app-23description: Use if building TypeScript apps with langchain/@langchain — agents, RAG, structured output.4---56# Build LangChain TypeScript App78Build LangChain.js v1 and LangGraph.js applications in TypeScript. Choose one implementation path before coding, keep the spine small, and load only the bundled references the chosen path needs.910## When to use this skill1112- *Building a tool-calling assistant with `createAgent` from `langchain` and Zod-typed tools.*13- *Wiring a RAG pipeline with a `Document` loader, splitter, embeddings, vector store, and retriever.*14- *Authoring a raw `StateGraph` from `@langchain/langgraph` with explicit state, routing, fan-out/fan-in, or interrupts.*15- *Adding structured output via `withStructuredOutput`, `responseFormat`, `toolStrategy`, or `providerStrategy`.*16- *Streaming tokens, events, or graph updates back to a UI/API and handling cancellation.*17- *Persisting agent/graph state with checkpointers, stores, or `thread_id`-keyed memory.*18- *Connecting MCP servers as namespaced tools through `@langchain/mcp-adapters`.*19- *Composing supervisor/router/handoff multi-agent or knowledge-domain agents in TypeScript.*2021Do **not** use this skill when:2223- The codebase is **Python LangChain / LangGraph** — TypeScript-only patterns here will mislead.24- A simple **single-provider chat** call (e.g., `openai.chat.completions.create`) is enough — pull in the provider SDK directly.25- The agent runtime is **`mcp-use` `MCPAgent`** — use `build-mcp-use-agent`.26- The core runtime is **Effect / `@effect/*`** even if it calls LLMs — use `build-effect-ts-v3`.2728## Trigger signals (imports and idioms)2930Treat these as the strong-positive signals for this skill:3132| Signal | Example |33|---|---|34| `langchain` package import | `import { createAgent } from "langchain"` |35| `@langchain/core/*` | `import { tool } from "@langchain/core/tools"` |36| `@langchain/langgraph` | `import { StateGraph, MemorySaver, Annotation } from "@langchain/langgraph"` |37| Provider packages | `@langchain/openai`, `@langchain/anthropic`, `@langchain/google-genai`, `@langchain/azure-openai` |38| Retrieval stack | `@langchain/textsplitters`, `RecursiveCharacterTextSplitter`, `OpenAIEmbeddings`, `InMemoryVectorStore`, `*.asRetriever()` |39| MCP adapters | `import { MultiServerMCPClient } from "@langchain/mcp-adapters"` |40| Structured output / streaming | `model.withStructuredOutput(schema)`, `responseFormat`, `toolStrategy`, `providerStrategy`, `agent.stream(..., { streamMode: "updates" })` |41| Persistence | `MemorySaver`, `checkpointer`, `thread_id`, `store` |42| LangSmith | `langsmith`, `LANGSMITH_API_KEY`, `traceable`, `openevals` |4344If none of these appear and the task is plain chat completion, route away from this skill.4546## Preflight4748Before coding, inspect the target repo and record:4950- `package.json`: module type, scripts, framework, existing LangChain packages, and test command.51- Runtime: Node.js 20+ and TypeScript 5+; stop and fix lower versions before debugging LangChain behavior.52- Installed versions: `npm ls langchain @langchain/core @langchain/langgraph @langchain/openai` when dependencies are installed; for drift checks use [references/start/version-discipline.md](references/start/version-discipline.md).53- Version script: run `scripts/check-langchain-versions.sh` for a read-only package report; docs live in `scripts/check-langchain-versions.sh.md`.54- Provider environment: `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, Anthropic/Google/Azure keys, LangSmith keys, MCP credentials.55- Work mode: greenfield scaffold vs existing app integration; for existing apps, follow local file layout and test conventions.56- Greenfield utility: use `scripts/scaffold-createagent-app.sh` only for a minimal `createAgent` app; docs live in `scripts/scaffold-createagent-app.sh.md`.5758For first-runnable apps and recovery from common failures, consult [references/start/getting-started.md](references/start/getting-started.md) and [references/start/common-errors.md](references/start/common-errors.md).5960## Choose the path (load-bearing)6162Force the architecture choice before writing code:6364- **Tool-calling assistant:** choose `createAgent` when external actions or business functions are needed and graph state/routing is not explicit.65- **2-step RAG:** choose deterministic retrieval plus answer generation when every query requires retrieval and predictable latency matters.66- **Agentic RAG:** expose the retriever as a tool when retrieval is one possible action among several.67- **Raw LangGraph:** use `StateGraph` only when the app needs explicit state, routing, interrupts, fan-out/fan-in, or durable graph execution.6869| Path | Output shape | First reference | Verification |70|---|---|---|---|71| `createAgent` tool-calling assistant | Messages state plus optional `structuredResponse`; tools call real project functions. | [references/agents/agents.md](references/agents/agents.md), then [references/agents/tools.md](references/agents/tools.md) | Assert tool call/result behavior, final message, max-step limit, optional structured response. |72| RAG pipeline | Answer plus retrieved/source `Document[]`, citations, grounding metadata. | [references/rag/rag.md](references/rag/rag.md) | Assert retrieval count, source IDs, answer contract, no-answer behavior. |73| Raw `StateGraph` | Typed graph state returned from `invoke`/`stream`; transitions are explicit. | [references/langgraph/langgraph.md](references/langgraph/langgraph.md), then [references/langgraph/langgraph-execution.md](references/langgraph/langgraph-execution.md) | Assert node outputs, conditional routes, recursion limit, persisted state when enabled. |74| Structured output | Validated schema object or explicit parse/retry failure path. | [references/agents/structured-output.md](references/agents/structured-output.md) | Assert schema success, invalid-output handling, provider/tool strategy behavior. |75| Streaming UI/API | Chosen token/event/update contract with cancellation and error events. | [references/agents/streaming.md](references/agents/streaming.md) | Assert event order, chunk shape, completion signal, abort behavior. |76| Human-in-the-loop | Interrupted graph paused on review/edit/approve nodes. | [references/langgraph/human-in-the-loop.md](references/langgraph/human-in-the-loop.md) | Assert interrupt payload, resume path, replay behavior. |77| MCP integration | Namespaced MCP tools, lifecycle management, explicit auth/transport config. | [references/providers/mcp.md](references/providers/mcp.md) | Assert server connection, tool discovery/filtering, timeout, cleanup, credential failure. |78| Memory / persistence | Stable `thread_id`, selected checkpointer/store, retention rules, replay. | [references/langgraph/memory-checkpointers.md](references/langgraph/memory-checkpointers.md) plus [references/langgraph/memory-stores.md](references/langgraph/memory-stores.md) | Assert multi-turn continuity, isolation between threads, persistence across restart if durable. |79| Multi-agent / knowledge-domain | Supervisor/router/handoff state plus domain safety constraints. | [references/agents/multi-agent.md](references/agents/multi-agent.md) or [references/agents/knowledge-agents.md](references/agents/knowledge-agents.md) | Assert route selection, handoff messages, domain guardrails, failure fallback. |8081## Implementation contracts8283- Match tests to the selected output contract. Do not claim the path works if tests only assert an LLM text substring.84- Keep real side effects behind tools with Zod schemas and deterministic unit tests.85- Use `toolStrategy` as the portable structured-output default; choose `providerStrategy` only when the selected provider is known to support it.86- Token-level streaming and strictly validated structured output often need different contracts. Choose raw-token streaming with parse-on-completion, event streaming, or non-streaming structured output deliberately.87- Start with one path end-to-end, then layer memory, streaming, middleware, or observability.8889## Version and package discipline9091Use path-specific package subsets and pin compatible versions in real apps:9293| Path | Baseline packages |94|---|---|95| `createAgent` | `langchain @langchain/core zod` plus a provider package such as `@langchain/openai` |96| RAG | `langchain @langchain/core @langchain/openai @langchain/textsplitters zod` plus the chosen vector-store package |97| Raw LangGraph | `@langchain/langgraph @langchain/core zod` plus provider/checkpointer packages as needed |98| MCP | `langchain @langchain/core @langchain/mcp-adapters @modelcontextprotocol/sdk zod` |99| LangSmith eval/tracing | `langsmith` plus `openevals` only when evaluation workflows need it |100101Use `@latest` only in update commands or exploratory refreshes, not as the documented tested state. When package APIs matter, verify the current package matrix before editing examples and record the research date. See [references/start/version-discipline.md](references/start/version-discipline.md).102103For existing apps, run `scripts/check-langchain-versions.sh` before diagnosing API drift or changing package pins. The paired docs are `scripts/check-langchain-versions.sh.md`.104105For greenfield `createAgent` demos, run `scripts/scaffold-createagent-app.sh` to generate the smallest pinned TypeScript app. The paired docs are `scripts/scaffold-createagent-app.sh.md`.106107## RAG reliability defaults108109For RAG, make these decisions before implementation:110111| Decision | Local default | Production requirement |112|---|---|---|113| Corpus size / update cadence | Small static fixture | Ingestion and re-indexing plan |114| Embedding model / dimension | `OpenAIEmbeddings`, `text-embedding-3-small` | Stable model, recorded dimension, migration plan |115| Vector store | `InMemoryVectorStore` | Persistent store with backups and filters |116| Metadata filtering | Source ID only | Typed metadata schema and filter tests |117| Retriever type | Similarity retriever | Chosen retriever/reranker based on eval results |118| Grounding contract | Return source documents | Citations, refusal/no-answer policy, regression eval |119| Evaluation metric | Manual smoke test | Retrieval recall, faithfulness, answer relevance |120121## Production guardrails122123Before productionizing any path, define max steps or recursion limits, token budget, retry/fallback policy, rate-limit strategy, and failure surface. Route details to [references/middleware/middleware-catalog.md](references/middleware/middleware-catalog.md), [references/middleware/middleware-patterns.md](references/middleware/middleware-patterns.md), [references/ops/observability-tracing.md](references/ops/observability-tracing.md), and [references/ops/observability-evaluation.md](references/ops/observability-evaluation.md).124125For deployment shape and platform constraints (Node version, edge runtimes, container/cloud targets), read [references/ops/deployment-local.md](references/ops/deployment-local.md) and [references/ops/deployment-production.md](references/ops/deployment-production.md).126127For provider/model selection, capability differences, and key wiring, read [references/providers/models.md](references/providers/models.md) and [references/providers/providers.md](references/providers/providers.md).128129Use LangSmith/observability for development debugging, production traces, cost/token tracking, RAG evaluation, and user feedback or online evals. Verify current pricing before quoting costs.130131## Reference routing132133Load only the files needed for the selected path.134135| Intent | Read |136|---|---|137| First runnable app, baseline commands, version drift | [references/start/getting-started.md](references/start/getting-started.md), [references/start/common-errors.md](references/start/common-errors.md), [references/start/version-discipline.md](references/start/version-discipline.md) |138| Agent orchestration and tool contracts | [references/agents/agents.md](references/agents/agents.md), [references/agents/tools.md](references/agents/tools.md) |139| Structured output and streaming | [references/agents/structured-output.md](references/agents/structured-output.md), [references/agents/streaming.md](references/agents/streaming.md) |140| Multi-agent and knowledge-domain agents | [references/agents/multi-agent.md](references/agents/multi-agent.md), [references/agents/knowledge-agents.md](references/agents/knowledge-agents.md) |141| Raw LangGraph execution | [references/langgraph/langgraph.md](references/langgraph/langgraph.md), [references/langgraph/langgraph-execution.md](references/langgraph/langgraph-execution.md), [references/langgraph/human-in-the-loop.md](references/langgraph/human-in-the-loop.md) |142| Memory and persistence | [references/langgraph/memory-checkpointers.md](references/langgraph/memory-checkpointers.md), [references/langgraph/memory-stores.md](references/langgraph/memory-stores.md) |143| RAG | [references/rag/rag.md](references/rag/rag.md) |144| Middleware and guardrails | [references/middleware/middleware-catalog.md](references/middleware/middleware-catalog.md), [references/middleware/middleware-patterns.md](references/middleware/middleware-patterns.md) |145| Models, providers, and MCP | [references/providers/models.md](references/providers/models.md), [references/providers/providers.md](references/providers/providers.md), [references/providers/mcp.md](references/providers/mcp.md) |146| Local and production deployment | [references/ops/deployment-local.md](references/ops/deployment-local.md), [references/ops/deployment-production.md](references/ops/deployment-production.md) |147| Tracing, evaluation, and online feedback | [references/ops/observability-tracing.md](references/ops/observability-tracing.md), [references/ops/observability-evaluation.md](references/ops/observability-evaluation.md) |148| Deterministic utilities | `scripts/check-langchain-versions.sh.md`, `scripts/scaffold-createagent-app.sh.md` |149150## Scope boundaries151152- Use LangChain.js and LangGraph.js v1 TypeScript APIs only.153- Keep Python-only guidance out of TypeScript implementations.154- Keep legacy v0 imports such as `langchain/chains` only when documenting migrations or anti-patterns.155- Do not rely on in-memory checkpointers, stores, vector stores, or caches for production persistence.156- Do not assume provider feature parity; verify model/tool/structured-output/streaming support before coding against it.
