🧭 快速定位 / 一眼入口 >>>

• create_agent(...)：最高频入口，适合先跑通 Agent 再加能力
• tools=[...]：给 Agent 外部动作，适合查天气、检索、调业务接口
• response_format=Schema：直接拿结构化结果，适合抽取、分类、路由
• middleware=[...]：动态模型、动态工具、安全护栏、审计都从这里插
• stream()：前者优化交互，后者定位链路问题

🚀 最小工作流 >>>

• pip install -U langchain "langchain[openai]"：安装核心包与 OpenAI 集成
• from langchain.agents import create_agent：创建生产可用 Agent
• agent.invoke({"messages": [...]})：同步执行单轮对话
• Agent 基于 LangGraph 运行时 : 默认带消息状态、工具循环、可流式输出

# 安装核心包与 OpenAI 集成
pip install -U langchain "langchain[openai]"

# 最小 Agent：先不要急着上工具，先跑通主链路
from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[],
    system_prompt="你是一个简洁的中文助手"
)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "用一句话解释 LangChain"}
        ]
    }
)

print(result["messages"][-1].content)

Quick Ref

• {"messages": [{"role": "...", "content": "..."}]}
• 没有工具时 : Agent 会退化成单模型节点
• 升级顺序建议 : 最小 Agent -> 工具 -> 结构化输出 -> 检索 / 中间件 -> 观测

🛠️ 高频场景 Recipe：工具 + 结构化输出 >>>

• @tool：把 Python 函数暴露成工具
• tools=[get_weather]：把工具挂到 Agent
• response_format=MySchema：让结果直接落到结构化对象
• ProviderStrategy：若模型支持原生结构化输出，会自动优先走

# 工具 + 结构化输出，一次把“会做事”和“结果可解析”打通
from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
    """查询天气（示例）"""
    return f"{city}：晴，25C"

class Answer(BaseModel):
    city: str = Field(description="城市")
    summary: str = Field(description="天气摘要")

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[get_weather],
    response_format=Answer,
    system_prompt="必要时先调用工具，再返回结构化结果"
)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "帮我查询北京天气，并按结构化格式返回"}
        ]
    }
)

print(result["structured_response"])

Quick Ref

• 工具函数签名要清晰 : 类型注解越明确，模型越容易正确选工具
• 工具描述别写空 : docstring 就像前端组件 prop 的说明文档
• 结构化输出常见用途 : 抽取、分类、路由、审核结果

🔎 高频场景 Recipe：RAG / 检索增强 >>>

• 基本链路 : 切分 -> 向量化 -> 检索 -> 重排 -> 生成
• 先保证召回质量，再谈提示词打磨 : 检索差时，Prompt 再花也救不回来
• LangChain 负责把检索和 Agent 主循环拼起来 : 不是替你省略索引设计

# 最小 RAG 思路：先拿到上下文，再交给模型回答
from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-4o-mini")

context = """
LangChain agents are built on top of LangGraph.
This gives agents durable execution, streaming, persistence, and human-in-the-loop support.
""".strip()

question = "LangChain Agent 的底层能力来自哪里？"

answer = model.invoke(
    f"仅基于上下文回答。\n上下文：{context}\n问题：{question}"
)

print(answer.content)

Quick Ref

• 适合 RAG 的内容 : FAQ、产品文档、知识库、规范
• 不适合只靠 RAG 的内容 : 必须执行动作的任务，仍要配工具
• 排障顺序 : 数据切分 -> 检索结果 -> 重排 -> 最终提示词

🧠 高频场景 Recipe：上下文、记忆与中间件 >>>

• state：当前会话内的消息与临时状态，适合短期记忆
• store：跨会话持久信息，适合偏好、权限、历史事实
• context_schema：每次调用传入环境信息，如租户、预算、地区
• 中间件优先于把逻辑写死在 prompt : 更像在请求管线里做控制，而不是堆大字符串

# 用中间件按会话长度动态切模型
from typing import Callable
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from langchain.chat_models import init_chat_model

simple_model = init_chat_model("openai:gpt-4o-mini")
complex_model = init_chat_model("openai:gpt-4.1")

@wrap_model_call
def choose_model(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    model = complex_model if len(request.messages) > 10 else simple_model
    return handler(request.override(model=model))

agent = create_agent(
    model=simple_model,
    tools=[],
    middleware=[choose_model]
)

Quick Ref

• state_schema：比直接塞 更聚焦
• 动态工具选择 : 工具多时优先做，能同时降成本和降误调用
• wrap_model_call wrap_tool_call：选模型 + 记日志 / 包错误

🛡️ 高频场景 Recipe：护栏、人工介入、流式与观测 >>>

• HumanInTheLoopMiddleware：高风险动作前暂停，等待人工确认
• Guardrails / 过滤中间件 : 输入前拦、输出后审、工具前校验都能做
• stream()：用事件流把模型输出和工具轨迹逐步推给前端
• LangSmith tracing : 排查 prompt、模型、工具链路的第一现场

# 打开 LangSmith tracing
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="<your_api_key>"
export LANGSMITH_PROJECT="langchain-cheatsheet"

Quick Ref

• 高风险动作三件套 : 审批、审计、回滚
• 工具调用日志至少留 : 工具名、参数、结果摘要、耗时
• 流式适合 : 聊天 UI、长任务、工具轨迹可视化

📚 模块速查 >>>

• langchain.agents.create_agent：高层 Agent 入口
• langchain.chat_models.init_chat_model：标准化初始化聊天模型
• langchain.tools.tool：把函数暴露为工具
• response_format=Schema：结构化输出
• langchain.agents.middleware.*：动态模型、动态工具、日志、护栏
• stream()：流式输出

⚠️ 决策点与升级提示 >>>

• langchain==1.2.13
• 2026-03-19
• 先核对官方 changelog，再动代码 : 尤其是 Agent、middleware、structured output
• langchain：避免 升了，集成包没跟上