Deep Agent 学习项目

这是一个面向实践的 DeepAgents、LangChain 与 LangGraph 学习仓库。项目通过可独立运行的 Python 示例和配套文档，演示 Agent、Tool、Middleware、Callback、Runtime、Checkpoint、Human-in-the-loop 与底层 Pregel 执行模型等核心能力。

本仓库主要用于学习和实验，不是开箱即用的生产应用。

技术栈

• Python 3.12+
• Deep Agents
• LangChain
• LangGraph
• PostgreSQL（仅部分持久化示例需要）
• uv（推荐的依赖和虚拟环境管理工具）

项目结构

目录	内容
base/	Deep Agent 基础能力、子 Agent、Backend、Middleware 与中断示例
tool/	Tool、ToolNode、ToolRuntime、并行调用、异常处理与重试
middleware/	Agent Middleware 示例
callback/	LangChain/LangGraph Callback 生命周期与事件示例
runtime/	LangGraph Runtime、Context、Store、Streaming 与异步执行
checkpoint/	Checkpoint、回放、分支、恢复与 PostgreSQL 持久化
interrupt/	LangGraph、LangChain 和 DeepAgents 的人工审批对比
pregel/	LangGraph 底层 Pregel、Channel、Super-step 与并行屏障
managed/	LangGraph Managed Values 示例
test/	实验和演示脚本，并非完整的自动化测试套件

各模块目录中的 README.md 和专题 Markdown 文档包含更详细的学习顺序与原理说明。

安装

首先确认本机已经安装 Python 3.12 和 uv，然后在项目根目录执行：

uv sync

uv sync 会根据 pyproject.toml 和 uv.lock 创建虚拟环境并安装依赖。

环境变量

复制示例环境文件：

Copy-Item .env.example .env

然后编辑 .env，填写实际使用的模型服务与 API Key：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-api-endpoint/v1
OPENAI_MODEL=your-model-name
TAVILY_API_KEY=your-tavily-api-key

如果需要启用 LangSmith 追踪，还需要配置 LANGSMITH_API_KEY 等相关变量。

.env 包含敏感信息，已被 Git 忽略。不要把真实 API Key、密码或数据库连接串提交到仓库。

运行示例

许多示例使用本地固定数据，不需要调用大模型，可以直接运行：

uv run python tool/01_tool_decorator_and_schema.py
uv run python runtime/01_context_basics.py
uv run python callback/01_chain_lifecycle.py
uv run python pregel/01_pregel_three_phases.py
uv run python checkpoint/01_super_step_basics.py

需要大模型配置的示例：

uv run python base/deep_agent_01.py
uv run python interrupt/langchain/hitl_demo.py
uv run python interrupt/deepagents/hitl_demo.py

不需要大模型的 Human-in-the-loop 示例：

uv run python interrupt/langgraph/hitl_demo.py

PostgreSQL Checkpoint 示例

checkpoint/08_postgres_persistence.py、checkpoint/09_postgres_inspect_tables.py 和 checkpoint/10_postgres_pending_writes.py 需要可访问的 PostgreSQL 数据库。

可以通过环境变量覆盖默认连接地址：

$env:CHECKPOINT_DB_URI="postgresql://用户名:密码@localhost:5432/postgres?sslmode=disable"
uv run python checkpoint/08_postgres_persistence.py

数据库连接串同样属于敏感信息，不应提交到 Git 仓库。

推荐学习顺序

1. base/：了解 Deep Agent 的基本组成。
2. tool/：理解模型如何生成并执行工具调用。
3. runtime/：理解 State、Context、Config 与 Runtime 的职责。
4. callback/：学习运行过程的观测与事件处理。
5. checkpoint/：学习状态持久化、恢复、回放与分支。
6. interrupt/：学习人工审批和中断恢复。
7. pregel/：深入理解 LangGraph 的底层执行模型。

安全说明

• 不要提交 .env、API Key、访问令牌或数据库密码。
• 运行涉及文件、数据库或工具调用的示例前，请先阅读对应代码。
• 本项目中的示例配置和模拟数据不应直接用于生产环境。

License

本项目暂未指定开源许可证。在添加许可证之前，代码默认不代表允许他人复制、修改或分发。