LangChain 快速上手：安装与第一个智能体

这篇适合谁，读完能做到什么

适合会一点 Python 或 JavaScript、想第一次做出能调用工具的 AI 智能体的读者。读完你能在本地装好 LangChain，配置一个模型的密钥，写出一个会调用天气函数的智能体，并打开追踪看清它每一步做了什么。

LangChain 是什么

LangChain 为数百种大模型和数千种其他集成提供统一接口。这些集成不打包在一起，而是各自作为独立的提供方包安装，例如 OpenAI 对应 langchain-openai，Anthropic 对应 langchain-anthropic^[1]。换模型时通常只需要改模型名，并配置对应的 API 密钥^[2]，这是用它做第一个智能体时最直接的好处。

准备工作

• 运行环境：Python 需要 3.10 及以上，快速上手的示例固定使用 Python 3.11^[1][2]。JavaScript 需要 Node.js 22 及以上，Bun 需要 1.0.0 及以上^[1]。
• 一个模型的 API 密钥。LangChain 支持的提供方包括 OpenAI、Google Gemini、Claude（Anthropic）、OpenRouter、Fireworks、Baseten、Ollama、Azure OpenAI、AWS Bedrock 和 HuggingFace^[2]。
• 调用费用由你选择的提供方计算，本文不涉及价格。

第一步：安装

用 uv 管理 Python 项目时，下面几条命令会固定 Python 3.11、初始化项目并添加 langchain^[2]：

uv python pin 3.11
uv init
uv add langchain
uv sync

如果习惯用 venv 加 pip，可以按下面的顺序做。Windows 下激活脚本的路径不同，代码块里的注释给出了写法^[2]：

python3.11 -m venv .venv
source .venv/bin/activate
# Windows: .venv\Scripts\activate
pip install -U langchain

需要 OpenAI 或 Anthropic 的模型时，还要单独安装提供方包：pip install -U langchain-openai 或 pip install -U langchain-anthropic^[1]。JavaScript 项目则用 npm install langchain @langchain/core 安装核心包^[1]。

第二步：配置模型密钥

密钥不要写进代码，也不要提交到仓库，放在环境变量里即可。在 shell 中可以执行 export OPENAI_API_KEY="your-api-key"，也可以把 OPENAI_API_KEY=your-api-key 写进 .env 文件^[2]。Python 用 python-dotenv 的 load_dotenv() 读取 .env，JavaScript 则用 import "dotenv/config"^[2]。

不同提供方的变量名不一样：Google Gemini 用 GOOGLE_API_KEY，Claude 用 ANTHROPIC_API_KEY，OpenRouter 用 OPENROUTER_API_KEY，Fireworks 用 FIREWORKS_API_KEY，Baseten 用 BASETEN_API_KEY^[2]。Ollama 在本地运行时需要 Ollama 服务已经启动，走云端推理则要设置 OLLAMA_API_KEY^[2]。Azure 需要 AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT 和 AZURE_OPENAI_DEPLOYMENT_NAME；AWS Bedrock 需要 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_REGION；HuggingFace 使用 HUGGINGFACEHUB_API_TOKEN^[2]。如果请求经由 LangSmith LLM Gateway 转发，就把网关密钥当作 API 密钥填入^[2]。

第三步：写第一个智能体

Python 版本的 create_agent 从 langchain.agents 导入。下面的例子使用 Claude 模型。get_weather 是一个普通的 Python 函数，放进 tools 列表之后，智能体就能调用它^[2]：

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="claude-sonnet-4-6",
    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)

运行后，模型会从问题里识别出城市名，并用它调用 get_weather。最后一行打印最后一条消息的内容块，可以用来确认这一轮确实走完了^[2]。

换模型时，model 参数的写法也会变化。多数提供方使用 提供方:模型名 的形式，例如 google_genai:gemini-2.5-flash-lite；Claude 示例则直接写 claude-sonnet-4-6^[2]。JavaScript 版本从 langchain 导入 createAgent 和 tool，参数结构用 zod 描述^[2]。

第四步：打开追踪（可选）

智能体通常会多次调用模型，中间过程一多就很难看清。LangChain 推荐接入 LangSmith 追踪^[2]。先设置下面的环境变量，再重新运行脚本：

export LANGSMITH_AGENT_ID="<your-agent-id>"
export LANGSMITH_AGENT_ENVIRONMENT="local"
export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."

之后在 LangSmith 上就能看到智能体的每一次调用^[2]。

第二个示例：读文本的研究智能体

快速上手的第二个示例是一个能回答文本文件问题的研究智能体。它涵盖详细的系统提示词、从 URL 加载文本的工具（工具用 langchain.tools 里的 @tool 定义）、模型配置、对话记忆、Deep Agents 和测试^[2]。

一次调用是怎么走完的

智能体收到问题后，模型先判断是否需要外部信息。问题里提到了城市，模型就会调用 get_weather，并把城市名作为参数传进去。工具返回一句固定的话，模型再把这段结果组织成最终回答^[2]。这一轮的消息都保存在 messages 列表里，所以打印最后一条消息，就能看到模型最终给出的内容^[2]。

这个过程看起来简单，却正是智能体和普通问答的区别：模型不只生成文字，还会决定何时调用外部函数。第一个示例把工具写得尽量简单，目的是先看清流程，之后再替换成真实的数据来源。

密钥与代码分开

把密钥写进环境变量或 .env 文件，可以避免它出现在源代码里。.env 文件通常不应提交到代码仓库。换模型时，通常只需修改模型名和对应的密钥，业务代码的其余部分可以保持不变^[2]。

读完以后可以检查的几件事

• Python 版本和 langchain 包是否已经装好，见第一步^[1][2]。
• 对应模型的密钥变量名是否与提供方一致，见第二步^[2]。
• 最后一条消息里是否出现了天气信息，见第三步^[2]。
• 如果开启了追踪，LangSmith 上能否看到智能体的调用记录，见第四步^[2]。

为什么示例里的工具返回固定句子

get_weather 返回的是固定句子「It's always sunny in」加上城市名，并不查询真实天气。这样做是为了让第一次运行的人把注意力放在智能体的调用流程上，而不是数据接口。确认流程跑通之后，再换成真实的数据来源^[2]。

JavaScript 版要注意的地方

JavaScript 版的入口是 createAgent，工具仍然用 tool 定义，参数结构用 zod 描述。Node.js 需要 22 及以上版本，Bun 需要 1.0.0 及以上版本^[1][2]。

用哪个模型开始

第一次运行时，选一个你已经有密钥的提供方即可。示例里列出了多个提供方，写法基本一致，换提供方时主要改的是模型字符串和环境变量^[2]。如果只是想验证流程，选择一个成本可控的模型就够了，本文不讨论具体价格。

常见问题

• 运行时报密钥相关错误：先检查变量名是否与所用提供方匹配。例如 OpenRouter 读取的是 OPENROUTER_API_KEY，不是 OPENAI_API_KEY^[2]。
• 模型名写法不对：字符串要符合提供方的格式，见上一节的例子^[2]。
• 本文只覆盖最简单的单轮问答智能体。要加入记忆或部署到生产环境，可以继续看 LangGraph 与 Deep Agents 的相关内容^[2]。

下一步

可以把 get_weather 换成真实的天气数据接口，再读本系列关于工具调用的文章。LangChain 关于记忆和部署的更多内容见其官方文档^[2]。

本文改编自 LangChain 开源文档中的 Install 与 Quickstart 页面^[1][2]，原文以 MIT 许可证发布。