老实说，

从「调一次 API」到「可编排的有状态 Agent」——痛点剖析

Pain Point 1：一次性调用只能得到孤立答案。 在 PoC 阶段，把 API Key 塞进环境变量、挑一家服务商、扔一段 Prompt。得到一段字符串回答，这在验证模型能否听懂指令时毫无问题。说到但当业务需要，

• 保留上一轮对话上下文；
• 把模型输出强制为结构化 JSON；
• 调用实时汇率、执行计算或进行人工兜底等工具；
• 走不同分支…，

时单次调用的范式就彻底失效，开发者会陷入「上下文去哪了？」、「怎么把自由文本转成可直接入库的对象？」、「工具调用后怎么把结果塞回去？」等困惑，

LangChain 与 LangGraph 的职责划分——解决实际问题的根本思路

LangChain

• 统一接入各种 LLM：ChatModel 抽象屏蔽供应商差异；init_chat_model
• 标准化输入输出：SystemMessage / HumanMessage / AIMessage / ToolMessage
• 结构化输出：.with_structured_output
• 工具绑定：.bind_tools

LangGraph

• Status Graph：StateGraph/AddNode / AddEdge / ConditionalEdge
• 状态归约： @add_messages、@add_state …
• MULTI‑STEP & CONDITIONAL: 支持任意复杂的有向图拓扑，跨轮记忆自动持久化。

一句话这方面，LangChain 提供积木。LangGraph 提供骨架，两者组合即可把“调一次 API”升级为“可编排、有状态、可观测”的 Agent 程序。

说到环境基座，用 uv 快速搭建可复现的 Python Agent 项目

为什么选择 uv 而不是 pip/conda？

🔥 Pain Point 2：依赖漂移导致项目在同事机器上跑不通。话说回来，

• • Pip： 解析慢、冲突难解决；
• • Anaconda： 管理程序 Python 与环境隔离成本高；
• • UV： Rust 实现、速度快、一键生成 lock 文件，保证跨网站复现。

五分钟创建项目骨架

# 初始化项目
uv init my-agent
# 进入目录并创建虚拟环境
cd my-agent
uv venv
# 激活虚拟环境
source .venv/bin/activate # Windows 使用 .venv\Scripts\activate
# 安装依赖
uv add -r requirements.txt
# 验证安装
uv run python -c "import langchain,langgraph;
print"

Pain Point 3：不同机器 Python 小版本不一致导致二进制 wheel 缺失。

.python-version 文件锁定到具体补丁号（如 .11.6+)，pyproject.toml 中也写明 "requires-python = ">=...,<""

说到安全管理密钥。.env 与 python-dotenv

# .env
GROQ_API_KEY=gsk_xxx...

# app.py
from dotenv import load_dotenv
import os
load_dotenv
api_key = os.getenv
assert api_key,"请在 .env 中配置 GROQ_API_KEY"

Pain Point 4：密钥误提交导致泄漏风险。

再看统一模型接入，init_chat_model 与 provider:model 的工程语义

init_chat_model 的设计动机

The old way required importing a concrete class for each provider;switching from Groq to Anthropic meant changing dozens of import lines.

Now a single call does it all:

models import initchat_model

model = initchatmodel( "groq的观点是，qwen--family",api_key=os.getenv,temperature=0.0。)

provider:model 字符串三层含义

使用示例这方面，

# 初始化
model = init_chat_model(
说到f"groq，{os.getenv}",api_key=os.getenv
)

说到常见踩坑清单，


"provider" 拼写错误： 在第一次 invoke 时才抛异常，请在初始化后立即做一次冒烟测试。.

"temperature" 默认值差异：结构化输出场景尤其要显式指定。.

..

从结构化输出来看，用 Pydantic 把自由文本变成可解析对象  — Pain Point 5：“正则抽取不可靠”。Pydantic 的角色——既是契约也是校验器
python
from pydantic import BaseModel,Field
class MovieReview:
title : str = Field
rating : float = Field
summary : str = Field
说到使用方式。python
structured = model.with_structured_output
result = structured.invoke
print
LLM 会收到完整的 JSON Schema，所以可以直接返回符合类型约束的数据。'Field description' 并非注释。而是字段级 Prompt
`description` 会被注入到程序 Prompt 中，对齐模型理解。例如把 “日期” 改为 “ISO8601 日期。如 `2024‑04‑08T08:00Z`”，填充准确率会明显提高。类型即契约——声明 → 提示 → 校验三层闭环