DeepSeek LangChain Integration: Python, TypeScript, RAG, Tools, and Structured Output

Last verified: April 27, 2026.

DeepSeek LangChain Integration lets developers connect DeepSeek models to LangChain through ChatDeepSeek. Use langchain-deepseek in Python or @langchain/deepseek in TypeScript, set DEEPSEEK_API_KEY on the server, and use the current DeepSeek model IDs: deepseek-v4-flash and deepseek-v4-pro.

This guide covers Python, TypeScript, RAG, tools, agents, streaming, structured output, wrapper compatibility, and production checks. It is focused on LangChain implementation, not a broad overview of DeepSeek AI.

Independent site disclosure: Chat-Deep.ai is an independent DeepSeek guide and browser access site. It is not the official DeepSeek website, not the official DeepSeek app, not the official DeepSeek developer platform, not affiliated with DeepSeek, and not affiliated with LangChain or LangSmith. For the broad overview, start with our DeepSeek AI.

Quick Answer: DeepSeek with LangChain

The practical DeepSeek LangChain path is to use LangChain’s dedicated ChatDeepSeek integration, not a generic wrapper as your default. Use Python when your stack is Python-first, TypeScript when your backend is Node.js or full-stack JavaScript, and keep all API keys server-side.

1. Install langchain-deepseek for Python or @langchain/deepseek for TypeScript.
2. Set DEEPSEEK_API_KEY as a server-side environment variable.
3. Import ChatDeepSeek.
4. Use deepseek-v4-flash for routine workflows.
5. Use deepseek-v4-pro for harder reasoning and agentic workflows.
6. Use a separate embedding model and vector store for RAG.
7. Validate structured output and tool arguments.
8. Test your exact LangChain package version before relying on advanced provider-specific behavior.

For the general DeepSeek API setup, read the DeepSeek API guide. For a direct API call without LangChain, start with create a DeepSeek chat completion.

What DeepSeek LangChain Integration Actually Means

DeepSeek is the model provider. LangChain is the orchestration framework. A DeepSeek LangChain integration connects a DeepSeek chat model to LangChain abstractions such as prompts, chains, tools, agents, retrievers, RAG pipelines, structured output helpers, streaming, and tracing.

In practice, this means you instantiate ChatDeepSeek, pass messages into LangChain’s model interface, and then compose that model with other LangChain components when you need orchestration.

You may not need LangChain for every use case. If your app only sends one prompt and receives one answer, a direct DeepSeek API call may be simpler. LangChain becomes more useful when your workflow needs retrieval, tools, agents, multiple steps, reusable chains, structured outputs, or observability.

If your goal is to call DeepSeek directly through OpenAI-compatible SDKs, read OpenAI SDK with DeepSeek.

When You Need LangChain—and When You Don’t

LangChain is valuable when orchestration is more important than a single model call. Keep the architecture as simple as possible for your actual workflow.

Use LangChain when	Use the direct DeepSeek API when
You need RAG orchestration with retrievers, documents, prompts, and generation.	You need one simple chat completion.
You are building tool or agent workflows.	You are sending a single prompt-response request.
You want reusable chains and components.	You want a minimal backend route.
You need a structured output pipeline with validation.	Strict direct JSON Output is easier for the route.
You want LangSmith tracing or LangChain ecosystem integrations.	No orchestration or tracing is needed.

Current Model Selection for LangChain

For new examples, use the current official DeepSeek model IDs. Older names should appear only in migration notes, not as the primary examples for new code.

Model	Best for	LangChain use
deepseek-v4-flash	Fast routine workflows	Chat, RAG answers, classification, extraction, summaries, support bots, metadata generation, and routine structured output.
deepseek-v4-pro	Harder reasoning	Tool planning, agents, complex coding, long-context synthesis, multi-step debugging, and higher-value production tasks.
deepseek-chat	Migration notes only	Legacy alias. Do not use as the primary model name in new examples.
deepseek-reasoner	Migration notes only	Legacy alias. Do not use as the primary model name in new examples.

For current API rates, check the official DeepSeek Models & Pricing page before production use. Use the official DeepSeek Models & Pricing page and, for independent context, the DeepSeek API pricing guide. This article does not include fixed prices because pricing can change.

For broader model context, read DeepSeek models.

LangChain Package Names

Use LangChain’s dedicated DeepSeek packages where possible. Package documentation can lag provider model launches, so separate package/import guidance from current DeepSeek model-name guidance.

Language	Package	Import	Use case
Python	langchain-deepseek	from langchain_deepseek import ChatDeepSeek	Python LangChain apps, RAG, tools, structured output, and agent workflows.
JavaScript / TypeScript	@langchain/deepseek with @langchain/core	import { ChatDeepSeek } from "@langchain/deepseek";	Node.js, TypeScript, LangChain JS apps, backend routes, and server-side agent workflows.

Do not make ChatOpenAI the default path for this article. It may be useful in special compatibility cases, but ChatDeepSeek is the documented LangChain integration path for DeepSeek.

Python Setup

Install LangChain and the dedicated DeepSeek package:

pip install -U langchain langchain-core langchain-deepseek python-dotenv

Store the DeepSeek API key in a server-side environment file:

DEEPSEEK_API_KEY=your_deepseek_api_key_here

Load it safely in Python:

import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.environ["DEEPSEEK_API_KEY"]

Do not hard-code API keys in source files, notebooks, frontend bundles, Git commits, or logs. For broader Python setup guidance, read the DeepSeek Python SDK guide.

Minimal Python ChatDeepSeek Example

This example uses deepseek-v4-flash for a simple routine request.

import os
from dotenv import load_dotenv
from langchain_deepseek import ChatDeepSeek

load_dotenv()

if not os.environ.get("DEEPSEEK_API_KEY"):
    raise RuntimeError("Missing DEEPSEEK_API_KEY")

llm = ChatDeepSeek(
    model="deepseek-v4-flash",
    temperature=0,
    max_retries=2,
)

messages = [
    ("system", "You are a concise assistant for backend developers."),
    ("human", "Explain when I should use LangChain instead of a direct API call."),
]

ai_msg = llm.invoke(messages)

print(ai_msg.content)

Keep the first test minimal. Once this works, add streaming, structured output, tools, or RAG one layer at a time.

Python Example with deepseek-v4-pro

Use deepseek-v4-pro for harder reasoning, tool planning, complex code review, long-context synthesis, and agentic workflows. LangChain wrapper behavior for provider-specific fields can vary by version, so test metadata handling in your installed package before depending on it.

import os
from dotenv import load_dotenv
from langchain_deepseek import ChatDeepSeek

load_dotenv()

if not os.environ.get("DEEPSEEK_API_KEY"):
    raise RuntimeError("Missing DEEPSEEK_API_KEY")

llm = ChatDeepSeek(
    model="deepseek-v4-pro",
    temperature=0,
    max_retries=2,
)

messages = [
    (
        "system",
        "You are a senior software architect. Give practical, implementation-focused advice.",
    ),
    (
        "human",
        "Review the architecture of a multi-tenant RAG support assistant. List the main failure modes and mitigations.",
    ),
]

ai_msg = llm.invoke(messages)

print(ai_msg.content)

# Depending on the installed package version, provider-specific fields may appear
# in additional_kwargs, response_metadata, or another wrapper-specific location.
print(ai_msg.additional_kwargs)
print(ai_msg.response_metadata)

Do not expose raw reasoning-related fields to users by default. Show the final answer content, and treat provider metadata as an internal diagnostic surface unless your application has a clear reason to display it.

TypeScript / JavaScript Setup

Install the LangChain DeepSeek integration for Node.js or TypeScript:

npm install @langchain/deepseek @langchain/core dotenv zod

For a TypeScript development project, you may also install:

npm install -D typescript tsx @types/node

Add your API key to a server-side environment file:

DEEPSEEK_API_KEY=your_deepseek_api_key_here

Never expose DEEPSEEK_API_KEY in browser JavaScript. If you build a browser app, call a backend route, serverless function, or private API endpoint that uses the key server-side.

For a full Node.js implementation path, read DeepSeek Node.js TypeScript.

Minimal TypeScript ChatDeepSeek Example

This example uses deepseek-v4-flash for a simple server-side TypeScript request.

import "dotenv/config";
import { ChatDeepSeek } from "@langchain/deepseek";

function getEnv(name: string): string {
  const value = process.env[name];

  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }

  return value;
}

getEnv("DEEPSEEK_API_KEY");

const llm = new ChatDeepSeek({
  model: "deepseek-v4-flash",
  temperature: 0,
  maxRetries: 2,
});

async function main() {
  const aiMsg = await llm.invoke([
    ["system", "You are a concise assistant for TypeScript developers."],
    ["human", "Explain how ChatDeepSeek fits into a LangChain app."],
  ]);

  console.log(aiMsg.content);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Keep this request server-side. A frontend should call your own backend route, not DeepSeek directly with a secret key.

TypeScript Example with deepseek-v4-pro

Use deepseek-v4-pro when the LangChain workflow needs stronger reasoning, such as tool planning, complex code review, multi-step debugging, or long-context synthesis.

import "dotenv/config";
import { ChatDeepSeek } from "@langchain/deepseek";

const llm = new ChatDeepSeek({
  model: "deepseek-v4-pro",
  temperature: 0,
  maxRetries: 2,
});

async function main() {
  const aiMsg = await llm.invoke([
    [
      "system",
      "You are a senior TypeScript architect. Focus on practical tradeoffs.",
    ],
    [
      "human",
      "Review a LangChain RAG support assistant architecture. Identify major risks and mitigations.",
    ],
  ]);

  console.log(aiMsg.content);

  // Provider-specific metadata location may vary by package version.
  console.log(aiMsg.additional_kwargs);
  console.log(aiMsg.response_metadata);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Before depending on advanced metadata, test your exact installed version of @langchain/deepseek and document the behavior in your codebase.

LangChain Doc Drift and Wrapper Compatibility

Treat DeepSeek and LangChain as two separate documentation layers:

1. DeepSeek official API facts: model names, feature support, alias retirement, endpoint behavior, thinking mode, output limits, and pricing source.
2. LangChain wrapper behavior: package names, imports, helper methods, metadata exposure, structured output helpers, tools, streaming, and tracing.

DeepSeek official documentation is the source of truth for current model IDs and alias retirement. LangChain official documentation is the source of truth for package names, imports, wrapper usage, and framework-level abstractions.

Some older LangChain examples may still show deepseek-chat or deepseek-reasoner. Treat those as legacy examples. In new ChatDeepSeek examples, use deepseek-v4-flash and deepseek-v4-pro.

If your route requires exact DeepSeek-specific parameter control and the LangChain wrapper does not forward a field correctly, use a direct DeepSeek API call for that route.

Streaming DeepSeek Responses with LangChain

Streaming is useful for chat UIs because users can see partial output while the model is still generating. Exact chunk metadata may vary by LangChain package version, so test your wrapper before building UI assumptions around provider-specific fields.

Python streaming example

from langchain_deepseek import ChatDeepSeek

llm = ChatDeepSeek(
    model="deepseek-v4-flash",
    temperature=0,
    max_retries=2,
)

messages = [
    ("system", "You are a concise assistant."),
    ("human", "Explain retrieval-augmented generation in simple terms."),
]

for chunk in llm.stream(messages):
    if chunk.content:
        print(chunk.content, end="", flush=True)

TypeScript streaming example

import "dotenv/config";
import { ChatDeepSeek } from "@langchain/deepseek";

const llm = new ChatDeepSeek({
  model: "deepseek-v4-flash",
  temperature: 0,
  maxRetries: 2,
});

async function main() {
  const stream = await llm.stream([
    ["system", "You are a concise assistant."],
    ["human", "Explain retrieval-augmented generation in simple terms."],
  ]);

  for await (const chunk of stream) {
    if (chunk.content) {
      process.stdout.write(String(chunk.content));
    }
  }
}

main().catch(console.error);

For production chat UIs, add cancellation, timeouts, retry limits, and safe handling for partial output.

Structured Output with DeepSeek and LangChain

LangChain structured output helps convert model responses into predictable objects. DeepSeek API-level JSON Output uses response_format: { "type": "json_object" }, while LangChain structured-output helpers may use wrapper features, tool-based strategies, provider-native strategies, or schema helpers depending on the installed package version.

Always validate outputs. Valid structure does not automatically mean the values are correct, safe, or allowed by your business rules. For a dedicated DeepSeek API-level explanation, read DeepSeek JSON Output.

Python Pydantic example

from typing import Literal
from pydantic import BaseModel, Field
from langchain_deepseek import ChatDeepSeek

class SupportLabel(BaseModel):
    category: Literal["billing", "technical", "account", "other"] = Field(
        description="Support ticket category"
    )
    priority: Literal["low", "medium", "high"] = Field(
        description="Ticket urgency"
    )
    summary: str = Field(description="Short plain-English summary")
    human_review_required: bool = Field(
        description="True if the input is ambiguous or risky"
    )

llm = ChatDeepSeek(
    model="deepseek-v4-flash",
    temperature=0,
    max_retries=2,
)

structured_llm = llm.with_structured_output(SupportLabel)

result = structured_llm.invoke(
    "The customer cannot log in after resetting their password twice."
)

print(result)

TypeScript Zod example

import "dotenv/config";
import { z } from "zod";
import { ChatDeepSeek } from "@langchain/deepseek";

const SupportLabel = z.object({
  category: z.enum(["billing", "technical", "account", "other"]),
  priority: z.enum(["low", "medium", "high"]),
  summary: z.string().min(1),
  human_review_required: z.boolean(),
});

const llm = new ChatDeepSeek({
  model: "deepseek-v4-flash",
  temperature: 0,
  maxRetries: 2,
});

async function main() {
  const structuredLlm = llm.withStructuredOutput(SupportLabel);

  const result = await structuredLlm.invoke(
    "The customer cannot log in after resetting their password twice."
  );

  console.log(result);
}

main().catch(console.error);

If with_structured_output or withStructuredOutput fails in your exact package version, use a fallback:

1. Use an explicit JSON-only prompt.
2. Use DeepSeek API-level JSON Output where the wrapper supports forwarding it.
3. Call the DeepSeek API directly for strict JSON routes.

Tool Calling and Agents with ChatDeepSeek

Tools are for external actions. A model may propose tool use, but your application controls the actual execution. Validate every argument before calling databases, external APIs, account systems, file operations, shell commands, or workflow automation.

For direct DeepSeek function-calling details, read DeepSeek Tool Calls.

Python tool example

from langchain.tools import tool
from langchain_deepseek import ChatDeepSeek

@tool
def get_order_status(order_id: str) -> str:
    """Return the status of an order by order ID."""
    if not order_id.startswith("ORD-"):
        raise ValueError("Invalid order ID format")

    # Replace this with a safe database or API lookup.
    return "processing"

llm = ChatDeepSeek(
    model="deepseek-v4-flash",
    temperature=0,
    max_retries=2,
)

llm_with_tools = llm.bind_tools([get_order_status])

response = llm_with_tools.invoke(
    "Can you check the status of order ORD-ABC123?"
)

print(response)

TypeScript tool example

import "dotenv/config";
import { z } from "zod";
import { tool } from "@langchain/core/tools";
import { ChatDeepSeek } from "@langchain/deepseek";

const getOrderStatus = tool(
  async ({ orderId }) => {
    if (!/^ORD-[A-Z0-9]{6,20}$/.test(orderId)) {
      throw new Error("Invalid order ID format");
    }

    // Replace this with a safe database or API lookup.
    return "processing";
  },
  {
    name: "get_order_status",
    description: "Return the status of an order by order ID.",
    schema: z.object({
      orderId: z.string().describe("Order ID, for example ORD-ABC123"),
    }),
  }
);

const llm = new ChatDeepSeek({
  model: "deepseek-v4-flash",
  temperature: 0,
  maxRetries: 2,
});

async function main() {
  const llmWithTools = llm.bindTools([getOrderStatus]);

  const response = await llmWithTools.invoke(
    "Can you check the status of order ORD-ABC123?"
  );

  console.log(response);
}

main().catch(console.error);

Do not let tools execute unsafe actions automatically. Payments, deletes, database writes, account changes, file operations, shell commands, and outbound messages should require strict validation, permissions, logging, and often human review.

RAG with DeepSeek and LangChain

RAG means retrieval-augmented generation. In a RAG workflow, the application retrieves relevant context from your data and sends that context to the LLM so the model can answer with grounded information.

In DeepSeek RAG LangChain workflows, DeepSeek is the LLM or generator. Embeddings and vector stores are separate. Do not assume DeepSeek is your embedding provider unless official DeepSeek documentation explicitly confirms the embedding feature you plan to use.

A typical DeepSeek LangChain RAG architecture looks like this:

1. Load documents.
2. Split documents into chunks.
3. Embed chunks with a separate embedding model.
4. Store vectors in a vector database.
5. Retrieve relevant chunks for the user query.
6. Send retrieved context to ChatDeepSeek.
7. Generate an answer with deepseek-v4-flash or deepseek-v4-pro.

Simplified Python RAG skeleton

from langchain_core.documents import Document
from langchain_deepseek import ChatDeepSeek

class PlaceholderRetriever:
    def invoke(self, query: str) -> list[Document]:
        # Replace this with your real vector-store retriever.
        return [
            Document(
                page_content="Refund requests must be reviewed by support before approval.",
                metadata={"source": "support-policy"}
            )
        ]

retriever = PlaceholderRetriever()

llm = ChatDeepSeek(
    model="deepseek-v4-flash",
    temperature=0,
    max_retries=2,
)

def answer_question(question: str) -> str:
    docs = retriever.invoke(question)

    context = "\n\n".join(
        f"Source: {doc.metadata.get('source', 'unknown')}\n{doc.page_content}"
        for doc in docs
    )

    messages = [
        (
            "system",
            "Answer using the provided context. If the context is insufficient, say you do not know."
        ),
        (
            "human",
            f"Context:\n{context}\n\nQuestion:\n{question}"
        ),
    ]

    result = llm.invoke(messages)
    return str(result.content)

print(answer_question("Can refunds be approved automatically?"))

RAG quality usually depends more on retrieval quality than on the final generation step. Evaluate chunking, embedding choice, metadata, retriever settings, and source filtering before blaming the LLM.

For a related orchestration framework comparison, read DeepSeek LlamaIndex Integration.

Thinking Mode in LangChain

DeepSeek thinking mode is controlled at the API level with thinking: { "type": "enabled" } or thinking: { "type": "disabled" }. Use non-thinking flows for routine tasks and consider thinking mode for harder reasoning, tool planning, long-context synthesis, and agentic workflows.

In LangChain, exact provider-specific parameter forwarding may depend on the wrapper version. If the thinking toggle is critical for your route, test wrapper pass-through carefully or use a direct DeepSeek API call for that route.

The final user-facing answer should be in content. Reasoning-related fields may be separate and should not be exposed by default. For a dedicated explanation, read DeepSeek Thinking Mode.

from langchain_deepseek import ChatDeepSeek

llm = ChatDeepSeek(
    model="deepseek-v4-pro",
    temperature=0,
    max_retries=2,
)

response = llm.invoke([
    ("system", "You are a careful technical planner."),
    ("human", "Plan a safe tool-based workflow for account support automation."),
])

print(response.content)
print(response.additional_kwargs)

For routine LangChain chat, RAG answers, extraction, classification, and support bots, start with deepseek-v4-flash. For harder reasoning and agentic workflows, evaluate deepseek-v4-pro.

LangSmith Tracing and Observability

LangSmith tracing is optional. It can help inspect multi-step chains, tools, agents, RAG retrieval, and prompt behavior. It is not required to use DeepSeek with LangChain.

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your_langsmith_key_here

Do not log sensitive prompts, private user content, customer records, secrets, or confidential outputs unless your privacy and security policy explicitly permits it.

Token Usage and Context Caching

Use token and usage metadata for monitoring, debugging, and capacity planning. Depending on the wrapper version and response path, you may see usage fields such as prompt_tokens, completion_tokens, total_tokens, prompt_cache_hit_tokens, and prompt_cache_miss_tokens.

{
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 0
  }
}

DeepSeek context caching is enabled by default. It can matter when your LangChain workflow repeats the same system prompts, JSON schemas, RAG templates, or long shared prefixes. Monitor cache-related fields where available.

Do not hard-code pricing assumptions into LangChain prompts, dashboards, or production estimates.

For more detail, read DeepSeek Context Caching. For current API rates, check the official DeepSeek Models & Pricing page or the independent DeepSeek API pricing guide.

Error Handling and Debugging

Debug DeepSeek LangChain issues by separating direct API behavior from wrapper behavior. First test a minimal direct DeepSeek API request. Then test a minimal ChatDeepSeek request. Add tools, RAG, structured output, and streaming one layer at a time.

Error / Symptom	Likely cause	Fix
401	Missing or invalid key.	Check DEEPSEEK_API_KEY and server environment loading.
400	Invalid request body.	Test a minimal direct API request and compare your request shape.
422	Unsupported parameter or bad model name.	Use current model IDs and remove unsupported parameters.
429	Rate or concurrency pressure.	Queue requests, reduce concurrency, and retry with backoff.
Wrapper rejects model ID	Old package version or wrapper validation issue.	Upgrade the package or use a direct API fallback for that route.
Structured output fails	Wrapper behavior, schema issue, or version mismatch.	Validate output, use explicit JSON Output, or call the API directly.
Tool calls are malformed	Weak schema or invalid arguments.	Strengthen schemas and validate tool inputs before execution.
RAG answers are weak	Retrieval issue.	Improve chunking, embeddings, retriever settings, source filtering, and metadata.

For direct API status codes, read the official DeepSeek Error Codes.

Legacy Migration: deepseek-chat and deepseek-reasoner

deepseek-chat and deepseek-reasoner are legacy compatibility aliases. Use them only in migration notes, not as the primary model names for new LangChain examples.

For new LangChain examples, replace older code like this:

# Old:
ChatDeepSeek(model="deepseek-chat")

# New:
ChatDeepSeek(model="deepseek-v4-flash")

# Old:
ChatDeepSeek(model="deepseek-reasoner")

# New:
ChatDeepSeek(model="deepseek-v4-pro")

The legacy aliases are scheduled to be retired after July 24, 2026, 15:59 UTC. Update old tutorials, code snippets, and internal documentation before relying on them in production.

Common Mistakes

• Copying old LangChain examples that use deepseek-chat.
• Copying old reasoning examples that use deepseek-reasoner.
• Using ChatOpenAI as the default path instead of ChatDeepSeek.
• Exposing API keys in browser JavaScript.
• Assuming DeepSeek is an embedding provider in RAG.
• Trusting structured output without validation.
• Letting tools execute unsafe actions automatically.
• Assuming wrapper metadata is identical across package versions.
• Ignoring package version drift.
• Treating web or app behavior as identical to API behavior.
• Including static prices in technical content.
• Building RAG without evaluating retrieval quality.

Production Checklist

• API key is stored server-side.
• Current model IDs are used.
• Package versions are pinned or documented.
• A minimal direct API test passes.
• A minimal LangChain wrapper test passes.
• Prompt templates are reviewed.
• Structured output is validated.
• Tool arguments are validated.
• Tool permissions are restricted.
• RAG retrieval quality is evaluated.
• Embeddings are configured separately.
• Streaming is tested before UI launch.
• Wrapper-specific metadata behavior is tested.
• Token usage is monitored.
• Context caching fields are reviewed where available.
• No static pricing assumptions are embedded.
• Official DeepSeek and LangChain docs are verified before launch.

FAQ

Related Chat-Deep.ai guides: DeepSeek AI guide, DeepSeek API guide, create a DeepSeek chat completion, OpenAI SDK with DeepSeek, DeepSeek Python SDK, DeepSeek Node.js TypeScript, DeepSeek JSON Output, DeepSeek Tool Calls, DeepSeek Thinking Mode, DeepSeek Context Caching, DeepSeek LlamaIndex Integration, DeepSeek models, and DeepSeek API pricing guide.