LangChain 01：全景、原理与学习路线

#1、本篇学完要得到什么

这一篇只解决三个问题：LangChain 到底负责什么；它与 LangGraph、Deep Agents、LangSmith 是什么关系；后面应按什么顺序学习。

贯穿整套课程的项目是“退款政策与订单助手”。它最终能够：回答知识库中的退款规则；查询当前用户的订单；生成结构化答复；对真正的退款操作进行人工审批；断线后恢复；通过评测后发布。

先记住一句话：模型负责理解与生成，应用负责数据、权限、状态和副作用。 如果把后四项也交给模型，演示可能好看，系统却无法验证。

#2、先画清系统，而不是先背 API

复制用户输入
  ↓
应用入口：认证、限流、request_id
  ↓
Agent Harness：系统提示、消息、工具、middleware
  ├─ 模型：判断意图、选择工具、组织回答
  ├─ 知识库：检索退款政策
  ├─ 订单服务：按当前登录用户查订单
  └─ 审批：退款前暂停，等待用户确认
  ↓
结构化结果 / 流式事件
  ↓
前端、日志、Trace、评测

LangChain 的核心是 create_agent：把模型、工具、system prompt 和 middleware 组装成一个 Agent Harness。Agent 内部执行“模型 → 工具 → 模型”的循环，直到模型给出最终答案或流程被限制终止。

它不是模型，也不是向量数据库，更不是权限系统。它帮你编排这些能力，但业务规则仍要写在自己的服务层。

#3、四个产品分别解决哪一层

选择规则：一步模型调用用模型 SDK；少量工具循环用 LangChain；业务流程需要明确节点和恢复时用 LangGraph；开放式长任务需要文件与子 Agent 时用 Deep Agents；无论使用哪一层，都可用 LangSmith 观测和评测。

#4、真正的 Agent 循环在做什么

假设用户问：“订单 A100 还能退款吗？”

1. 应用把用户消息、可信的 user_id、可用工具交给 Agent。
2. 模型只看到工具说明，不会自动执行代码。它生成一个 get_order({order_id:"A100"}) 工具调用。
3. Harness 校验参数并调用工具。
4. 工具服务再次校验当前用户是否拥有该订单，然后返回结构化结果。
5. 结果以 Tool Message 形式回到模型。
6. 模型可能继续调用 search_policy，也可能基于已有证据完成回答。
7. 应用验证最终结构、记录 trace，并把结果流式交给前端。

这里有三种不同的“正确”：模型语言正确；工具数据正确；业务行为正确。结构化输出能改善第一种，工具测试能保证第二种，权限、状态机与审批才能保证第三种。

#5、建立两套最小开发环境

Python：

复制python -m venv .venv
source .venv/bin/activate
pip install -U langchain langgraph pydantic pytest

TypeScript：

复制npm init -y
npm install langchain @langchain/langgraph zod
npm install -D typescript tsx vitest @types/node

模型 provider 包按实际使用的服务安装。密钥只放在环境变量或密钥管理系统，不要写进源码、prompt、Joplin 示例或 Git。

#6、先跑通一个最小 Agent

Python：

复制from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """查询城市天气。"""
    return f"{city}：晴，25℃"

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="你是中文助手；工具有结果时不得编造。",
)
result = agent.invoke({
    "messages": [{"role": "user", "content": "上海天气如何？"}]
})
print(result["messages"][-1].content)

TypeScript：

复制import { createAgent, tool } from "langchain";
import * as z from "zod";

const getWeather = tool(
  ({ city }) => `${city}：晴，25℃`,
  {
    name: "get_weather",
    description: "查询城市天气",
    schema: z.object({ city: z.string().min(1) }),
  },
);

const agent = createAgent({
  model: "openai:gpt-5.5",
  tools: [getWeather],
  systemPrompt: "你是中文助手；工具有结果时不得编造。",
});
const result = await agent.invoke({
  messages: [{ role: "user", content: "上海天气如何？" }],
});
console.log(result.messages.at(-1)?.content);

这段代码只证明四件事：模型可调用；工具 schema 可见；Harness 能执行工具；消息历史保留了执行轨迹。它还没有权限、持久化、可靠错误处理和评测，因此只能算起点。

官方阅读：LangChain Python Overview、LangChain TypeScript Overview。