build-langchain-ts-app（构建 LangChain TS 应用）

Build LangChain TypeScript App

Build with LangChain.js v1 and LangGraph in TypeScript. Prefer the smallest working pattern (createAgent) first, then add complexity only when required.

Trigger boundary

Use this skill when work involves LangChain.js/LangGraph TypeScript design or implementation:

• Tool-calling agents
• RAG pipelines
• Streaming and structured output
• LangGraph stateful workflows
• MCP integration
• Memory/checkpointer design
• Multi-agent orchestration

Do not use this skill for:

• Python LangChain code
• Simple single-provider chatbot work where provider SDK alone is enough

Non-negotiable rules

1. TypeScript-only, LangChain v1 APIs only.
2. Start simple: createAgent before StateGraph.
3. Use real project functions as tools; never use eval-style shortcuts.
4. Choose model/provider explicitly before adding middleware, memory, or RAG.
5. Keep code incremental: get one path working end-to-end, then extend.

Fast decision tree

What are you building?
├── Basic tool-calling assistant (1-5 tools, low state)
│   └─► createAgent path (references/getting-started.md, references/agents.md)
├── Stateful loops, interrupts, custom routing
│   └─► LangGraph StateGraph path (references/langgraph.md, references/langgraph-execution.md)
├── Retrieval over documents
│   └─► RAG path (references/rag.md)
├── Strict JSON output contract
│   └─► Structured output path (references/structured-output.md)
├── UI token/event streaming
│   └─► Streaming path (references/streaming.md)
├── Multi-agent coordinator/swarm
│   └─► Multi-agent path (references/multi-agent.md)
└── External tools via MCP
    └─► MCP path (references/mcp.md)

Baseline setup

npm install langchain @langchain/core @langchain/langgraph zod
npm install @langchain/openai
# Optional:
npm install @langchain/openrouter @langchain/mcp-adapters

Required runtime: Node.js 20+ and TypeScript 5+.

Provider keys:

• OpenAI: OPENAI_API_KEY
• OpenRouter: OPENROUTER_API_KEY

For exact startup scaffolding (file layout + first run command), read references/getting-started.md.

Minimal implementation workflow

1. Pick provider/model

- Use references/models.md and references/providers.md for feature and compatibility checks.

1. Pick agent architecture

- Start with createAgent; move to LangGraph only if you need state graphs/interrupts.

1. Define tools and schemas

- Tool contracts must be explicit and testable (references/tools.md).

1. Add reliability layers

- Middleware, retries, fallbacks, guardrails (references/middleware-catalog.md, references/middleware-patterns.md).

1. Add memory/streaming/structured output as needed

- Use dedicated references instead of ad-hoc patterns.

1. Instrument and test

- Add tracing/evaluation early (references/observability-tracing.md, references/observability-evaluation.md).

Default path (recommended): createAgent

Use this as the initial architecture for most tasks:

• createAgent for orchestration
• Zod schemas for tool input contracts
• checkpointer only when thread persistence is required
• toolStrategy for structured output portability

Deep dive: references/agents.md.

Escalation path: StateGraph

Switch to StateGraph only if one or more are true:

• You need explicit graph nodes/edges and branching
• You need interrupt/resume with human approval
• You need durable/replayable execution semantics
• You need complex multi-step state transitions

Deep dives: references/langgraph.md, references/langgraph-execution.md, references/human-in-the-loop.md.

Common anti-patterns

Reject these and route to fixes:

• Legacy v0 imports (langchain/chains, deprecated APIs)
• providerStrategy with OpenRouter multi-model paths
• In-memory persistence choices for production
• Deeply nested tool schemas without clear constraints
• Streaming assumptions that conflict with structured output behavior

Canonical fixes: references/common-errors.md, references/structured-output.md, references/streaming.md.

Reference routing

Reference routing

Guardrails

• Do not use Python-only guidance in a TypeScript implementation.
• Do not add complexity before a minimal path runs successfully.
• Do not use outdated v0 APIs.
• Do not assume provider feature parity; verify with references/providers.md.
• Do not rely on in-memory persistence components in production workflows.
• Do not ship without tracing/error visibility.

Scope boundaries

This skill covers LangChain.js and LangGraph.js in TypeScript only. It does not cover:

• Python LangChain (different APIs and patterns)
• LangServe (Python-only)
• Embeddings via OpenRouter (use OpenAI directly)
• Database-specific setup beyond connection patterns (PostgresSaver, SqliteSaver need separate install)