LangChain 入门教程：20 行代码跑通第一个 AI 智能体

先给结论

LangChain 入门最快的路径是：装 langchain → 设一个模型 API Key → 用 create_agent 写一个带工具的智能体，二十行以内就能跑通。新手最常见的误区是一上来就啃”链（Chain）”的概念，其实现在主推的是智能体（Agent）范式：模型 + 工具 + 系统提示词，循环调用直到任务完成。把这三件套理解清楚，剩下的都是排列组合。

环境准备

官方要求 Python 3.11 及以上。用 uv 最省事：

uv init
uv add langchain
uv sync

# 或者用 pip
pip install -U langchain

然后设置任意一个模型厂商的 Key：

export OPENAI_API_KEY="your-api-key"
# 也可以选 Anthropic / Google Gemini / OpenRouter / Ollama 等

第一个智能体：二十行跑通

from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
)
print(result["messages"][-1].content_blocks)

这段代码里藏着三个关键概念：

• model：用 厂商:模型名 的字符串指定，换模型只改这一行，业务代码不动。
• tools：普通 Python 函数即可，框架自动把函数签名和 docstring 转成模型能理解的工具描述。docstring 不是注释，它会被模型读进去，写得越清楚，调用越准。
• system_prompt：定义角色与行为边界，是性价比最高的调优入口。

进阶：一个能干活的调研智能体

把工具换成真实能力，再加记忆，就接近生产形态了：

from langchain.tools import tool
import urllib.request

@tool
def fetch_text_from_url(url: str) -> str:
    """Fetch the document from a URL."""
    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
    return urllib.request.urlopen(req).read().decode("utf-8", errors="ignore")[:8000]

SYSTEM_PROMPT = """You are a literary data assistant.
Capabilities:
- fetch_text_from_url: loads document text from a URL into the conversation.
Do not guess line counts or positions—ground them in tool results."""

这里有两个值得学的写法：一是用 @tool 装饰器显式声明工具；二是系统提示词里明确”不要猜，基于工具结果作答”——这是抑制幻觉最有效的一句话。

什么时候需要上 LangGraph

LangGraph 把智能体建模成图：节点是处理步骤，边是流转条件。代价是代码量翻倍，好处是流程完全可控。建议先用 create_agent 跑通业务，遇到”控制不了流程”的痛点再迁。

可观测性：别跳过这一步

智能体的难点不在写，在于出问题时知道它为什么这么决策。接上 LangSmith（设置 LANGSMITH_TRACING=true 和 API Key），每一次模型调用、每一次工具调用、每一条消息都会留痕。没有 tracing 的智能体项目，调试基本靠猜。

四个新手常踩的坑

1. 工具 docstring 敷衍：模型不知道什么时候该调用它。
2. 系统提示词太虚：写”你是一个有帮助的助手”等于没写；要写角色、能力清单、禁止事项。
3. 工具返回结果过大：一股脑塞回上下文，几轮就爆窗。截断、摘要、按需返回是基本功。
4. 没有退出条件：模型反复调用工具打转，需要设置最大步数与超时。

和其他方案怎么搭配

工具调用是智能体的地基，原理可以看 OpenAI Function Calling 实战；需要外部知识时接检索，见 RAG 检索增强生成是什么；想知道智能体内部的思考-行动循环是怎么设计的，读 Agent 设计模式 ReAct 实战。

参考来源：LangChain 官方 Quickstart 与 LangGraph 文档。