上一篇介绍了 LangGraph、Agent 和 Workflow 的区别。本篇开始搭建第一个 LangGraph 项目：安装 CLI，认识项目配置，再使用本地 Qwen3 和一个模拟天气工具创建最小 Agent。
这一步只完成项目和 Graph，不启动 Agent Server。服务启动和调试放到下一篇。
1. 为什么单独创建虚拟环境
前面的 LangChain 示例使用 langchain==1.0.3 和 langgraph==1.0.2。本篇使用的 LangGraph CLI 会安装本地 Agent Server 需要的运行组件，如果直接装进主环境，可能升级已有依赖并影响前面的代码。
因此在 llm_learning 根目录创建独立的 Python 3.12 环境：
cd source/_posts/llm_learning
python3.12 -m venv \
--prompt llm_learning_langgraph \
.venv_langgraph
source .venv_langgraph/bin/activate激活后检查 Python：
python --version输出：
Python 3.12.112. 准备固定版本依赖
项目中的 requirements.txt 只记录直接依赖：
langgraph==1.1.3
langgraph-cli[inmem]==0.4.19
langchain==1.2.13
langchain-core==1.2.22
langchain-openai==1.1.12
openai==2.30.0
httpx==0.28.1[inmem] 会安装 langgraph dev 所需的内存运行时。本地开发不需要先启动 Docker 或数据库。
为了避免后续安装时解析到不同的间接依赖，项目还提供了由这些直接依赖生成的 requirements-lock.txt。安装时使用锁文件：
python -m pip install \
-r langgraph/p02_local_agent_project/requirements-lock.txt检查依赖：
python -m pip check
langgraph --version真实输出：
No broken requirements found.
LangGraph CLI, version 0.4.193. 使用 CLI 创建模板项目
LangGraph CLI 提供 new 命令，可以从官方模板创建项目：
langgraph new \
/tmp/langgraph-template-check \
--template new-langgraph-project-python真实执行结果：
Attempting to download repository as a ZIP archive...
Downloaded and extracted repository to /tmp/langgraph-template-check
New project created at /tmp/langgraph-template-check如果不指定 –template，CLI 会显示交互菜单，让用户选择 Python 或 JavaScript 模板。
官方模板包含示例 Agent、单元测试、集成测试、GitHub Actions 和锁文件，适合新项目直接起步。本文为了让代码更容易理解，没有把全部模板文件复制进学习项目，而是保留本次运行真正需要的最小结构。
4. 项目目录结构
本篇代码位于：
llm_learning/
langgraph/
p02_local_agent_project/
.env.example
langgraph.json
pyproject.toml
requirements.txt
requirements-lock.txt
README.md
src/
weather_agent/
__init__.py
graph.py下面这张图只展示本篇完成的项目创建、配置、可编辑安装和 Graph 导入验证。Agent Server 的启动属于下一篇，不放进当前流程。
这几个文件各自负责不同工作：
- graph.py：真正的 Agent 代码。
- langgraph.json：告诉 Agent Server 应该加载哪张图。
- pyproject.toml：声明 Python 项目和运行依赖。
- .env.example：运行环境变量模板，复制为 .env 后由 langgraph.json 加载。
- requirements.txt：记录需要主动维护的直接依赖。
- requirements-lock.txt：固定包含间接依赖在内的完整安装结果。
- README.md：记录环境安装、配置复制和后续服务启动顺序。
这种结构将 Graph、项目配置、依赖和环境变量分开管理，也符合 LangGraph 对本地应用结构的基本要求。LangGraph Application structure
5. 编写 pyproject.toml
完整配置如下：
[build-system]
requires = ["setuptools==82.0.1"]
build-backend = "setuptools.build_meta"
[project]
name = "local-weather-agent"
version = "0.1.0"
description = "使用本地 Qwen3 的 LangGraph 天气 Agent 教学项目"
requires-python = ">=3.12,<3.13"
dependencies = [
"httpx==0.28.1",
"langchain==1.2.13",
"langchain-core==1.2.22",
"langchain-openai==1.1.12",
"langgraph==1.1.3",
"openai==2.30.0",
]
[tool.setuptools.packages.find]
where = ["src"]where = [“src”] 表示 Python 包放在 src 目录中。安装项目后，无论从哪个工作目录执行 Python，都可以导入 weather_agent。
执行可编辑安装：
python -m pip install -e langgraph/p02_local_agent_project-e 表示 editable。修改 src/weather_agent/graph.py 后不需要重复打包安装，适合本地开发。
6. 编写 langgraph.json
Agent Server 启动时会读取项目根目录下的 langgraph.json：
{
"dependencies": ["."],
"graphs": {
"weather_agent": "./src/weather_agent/graph.py:graph"
},
"env": ".env",
"python_version": "3.12"
}几个字段的作用如下：
- dependencies：项目运行时需要安装的本地依赖，. 表示项目自身。
- graphs：注册可以由 Agent Server 加载的图。
- weather_agent：图在服务中的名称。
- ./src/weather_agent/graph.py:graph：文件路径和导出的 Python 变量。
- env：启动服务时加载的环境变量文件。
- python_version：项目使用的 Python 版本。
如果 graph.py 中没有名为 graph 的变量，或者路径拼写错误，服务启动时会直接导入失败。
7. 关闭 LangSmith 追踪
本文只在本机测试，不向 LangSmith 上传追踪信息。.env.example 内容如下：
# 本文只在本地运行，不向 LangSmith 上传追踪数据。
LANGSMITH_TRACING=false复制为本地 .env：
cd langgraph/p02_local_agent_project
cp .env.example .env.env 已被 .gitignore 排除，避免将后续可能加入的密钥提交到仓库。
8. 编写天气 Agent
src/weather_agent/graph.py 的完整代码如下：
"""使用本地 Qwen3 和一个模拟天气工具创建最小 LangGraph Agent。"""
import httpx
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
# ChatOpenAI 只负责按 OpenAI 兼容协议连接本地 Qwen3 服务。
model = ChatOpenAI(
model="default_model",
base_url="http://127.0.0.1:18080/v1",
api_key="not-needed",
temperature=0,
max_tokens=256,
http_client=httpx.Client(trust_env=False),
)
def get_weather(city: str) -> str:
"""查询指定城市的天气。"""
# 这是教学用的模拟工具，不会请求真实天气接口。
return f"{city}今天的天气晴朗，气温是 28 摄氏度。"
# create_agent() 返回一个由 LangGraph 驱动的已编译状态图。
graph = create_agent(
model=model,
tools=[get_weather],
system_prompt="你是一个中文智能助手。用户询问天气时，必须调用天气工具。",
)8.1 ChatOpenAI 在这里做什么
ChatOpenAI 并不表示必须使用 OpenAI 官方模型。它按照 OpenAI 兼容协议向 base_url 发送请求，因此可以连接前面部署的 MLX-LM 服务。
trust_env=False 可以避免系统代理或 VPN 把 127.0.0.1 请求转发到外部代理。
8.2 为什么工具必须写说明
模型需要根据工具名称、参数类型和文档字符串判断工具用途。这里的 city: str 告诉模型参数名称和类型，文档字符串说明这是天气查询工具。
这里的 get_weather 仍然是普通 Python 函数。create_agent() 接受函数、LangChain Tool 或工具 Schema，因此可以在创建 Agent 时把这个函数转换成模型可调用的工具。这属于“从 Python 函数创建工具”这一类，也是最直接的写法。LangGraph 系列 5 会继续说明 @tool、StructuredTool.from_function()、Runnable 和 BaseTool 的区别。
本例返回固定天气，只用于验证 Agent 的工具调用流程，不应被理解为真实天气数据。
8.3 create_agent() 做了什么
create_agent() 会创建一张由 LangGraph 驱动的图，其中包含模型节点、工具节点和决定是否继续调用工具的条件路径。
较早的示例经常使用 langgraph.prebuilt.create_react_agent()。在本文使用的版本中，推荐从 LangChain 导入 create_agent()；它返回的仍然是 LangGraph 编译图。LangChain Agent 文档
9. 检查 Graph 是否能够导入
不启动模型也可以先检查项目配置和 Python 导入是否正确：
python -c '
from weather_agent.graph import graph
print(f"graph_type={type(graph).__name__}")
print(f"graph_name={graph.name}")
'真实结果：
graph_type=CompiledStateGraph
graph_name=LangGraph这说明 create_agent() 已经生成编译图，项目安装和导入路径也没有问题。
10. 常见问题
10.1 langgraph 命令不存在
先确认激活的是 .venv_langgraph：
which python
which langgraph两个路径都应该位于 llm_learning/.venv_langgraph/。
10.2 pip check 出现版本冲突
不要在主 .venv 中继续升级。删除并重新创建 .venv_langgraph，然后从锁文件安装。
10.3 无法导入 weather_agent
确认已经执行：
python -m pip install -e langgraph/p02_local_agent_project同时检查 pyproject.toml 中是否配置了 where = [“src”]。
10.4 导入 Graph 时不需要模型服务吗
导入只创建模型客户端和编译图，不会立即发送聊天请求。真正调用 graph.invoke() 或启动一次 Agent Run 时，Qwen3 服务才必须可用。
11. 小结
本篇已经完成 LangGraph CLI 安装、模板命令验证、最小项目配置和天气 Agent 编译。下一篇会启动 Qwen3 和 Agent Server，检查 HTTP 接口，并观察 Agent 如何产生工具调用和最终回答。
| 检查项 | 实际结果 |
|---|---|
| Python | 3.12.11 |
| LangGraph CLI | 0.4.19 |
| pip check | 无依赖冲突 |
| 官方模板命令 | 创建成功 |
| 本地项目安装 | editable 安装成功 |
| Graph 类型 | CompiledStateGraph |
| Graph 名称 | LangGraph |
