🐱 Cat Agents

基于 LangChain & LangGraph 的多智能体学习项目
包含 7 种不同架构模式的 Agent 实现，从入门到进阶

---

📖 项目简介

Cat Agents 是一个 AI Agent 学习项目，基于 LangChain 和 LangGraph 框架构建。项目实现了多种不同架构模式的智能体，涵盖了从简单的线性流水线到复杂的多层级 Agent 系统，适合学习和理解 AI Agent 的设计与实现。

✨ 核心特性

• 🎯 7 种 Agent 架构 — 覆盖主流 Agent 设计模式
• 🔧 LangGraph 驱动 — 基于图的 Agent 编排与状态管理
• 🧩 中间件系统 — 演示三种不同的中间件实现方式
• 📊 LangSmith 集成 — 完整的调用链追踪与可视化
• 🤖 DeepSeek-V3 — 通过 SiliconFlow API 接入国产大模型

---

🏗️ 项目结构

cat_agents/
├── conn/
│   └── llm.py                    # LLM 连接工厂（ChatOpenAI 封装）
├── utils/
│   ├── chat_history.py           # 聊天记录管理（JSON 持久化）
│   └── common_utils.py           # 流程图绘制工具（matplotlib）
├── agents/                       # 🎯 核心 Agent 实现
│   ├── joke_agent.py             # 笑话 Agent — 两节点流水线
│   ├── react_agent.py            # ReAct Agent — 思考-执行-观察循环
│   ├── time_agent.py             # 时间 Agent — 工具调用示例
│   └── news_agent.py             # 新闻 Agent — 中间件集成
├── study/                        # 📚 学习与探索
│   ├── demo_agent.py             # LangGraph Dev Server 演示
│   ├── middleware/                # 中间件模式（装饰器/类/异步）
│   └── planner_agent/            # 任务规划 Agent
└── deepagent/                    # 🚀 进阶
    └── coder_agent.py            # 编程助手（含子 Agent）

---

🤖 Agent 详解

1. 🎭 笑话 Agent — agents/joke_agent.py

架构模式： 两节点线性流水线（LangGraph StateGraph）

用户输入话题 → [生成节点 temp=0.9] → 草稿笑话 → [优化节点 temp=0.7] → 最终笑话

• 使用高低不同温度参数控制创意度
• 展示 LangGraph 状态图的基本用法
• 状态： {topic, draft, final}

2. 🔄 ReAct Agent — agents/react_agent.py

架构模式： ReAct 循环（Think → Execute → Observe）

用户输入 → [思考] → 需要工具? → [执行] → [观察] → 满意? → 输出 / 继续循环

• 实现经典的 ReAct 推理模式
• 内置工具：search、calculator、get_weather
• 支持 @register_tool 装饰器扩展自定义工具
• 自动限制最大迭代次数防止死循环

3. ⏰ 时间 Agent — agents/time_agent.py

架构模式： 简单工具调用 Agent

• 工具：get_current_time、get_current_date、get_timestamp
• 使用 zoneinfo 处理时区（Asia/Shanghai）
• 最简洁的 Agent 实现，适合入门学习

4. 📰 新闻 Agent — agents/news_agent.py

架构模式： 带中间件的 Agent

• 工具：fetch_news、search_news、summarize_news、get_hot_news
• 中间件：日志记录、调用计数、工具守卫（3次重试）、完成通知
• 演示中间件在 Agent 生命周期中的应用

5. 🧩 中间件学习 — study/middleware/

三种中间件实现方式的对比学习：

方式	文件	特点
装饰器语法	middleware_agent.py	@before_agent、@wrap_tool_call 等糖语法
类继承	class_middleware.py	AgentMiddleware 子类，面向对象风格
异步版本	async_middleware.py	异步中间件，支持令牌桶限流

6. 📋 任务规划 Agent — study/planner_agent/agent.py

架构模式： Planner → Scheduler → Executor → Summarizer 四阶段流水线

用户请求 → [规划] → 任务列表 → [调度] → [执行] → 循环 → [总结]

• 自动将复杂任务拆解为可执行的子任务
• 支持文件操作工具：read_file、write_file、list_files、search_files
• 条件边控制任务循环执行

7. 🚀 编程助手 — deepagent/coder_agent.py

架构模式： 深度 Agent + 子 Agent 协作

• 基于 deepagents 库构建
• 内置工具：文件操作、代码执行、语法检查
• 子 Agent：code_reviewer（代码审查）、test_writer（测试生成）
• 支持 LangGraph Dev Server 部署

---

🚀 快速开始

环境要求

• Python 3.10+
• pip

安装依赖

pip install -r requirements.txt

配置环境变量

复制 .env.example 并填入你的 API Key：

cp .env.example .env

编辑 .env 文件：

# SiliconFlow API（DeepSeek-V3）
OPENAI_API_KEY=your_api_key_here
OPENAI_API_BASE=https://api.siliconflow.cn/v1
OPENAI_MODEL=deepseek-ai/DeepSeek-V3

# LangSmith 追踪（可选）
LANGCHAIN_API_KEY=your_langsmith_key
LANGCHAIN_PROJECT=cat_agent
LANGCHAIN_TRACING_V2=true

运行 Agent

# 运行笑话 Agent
python -m agents.joke_agent

# 运行 ReAct Agent
python -m agents.react_agent

# 运行时间 Agent
python -m agents.time_agent

# 运行新闻 Agent
python -m agents.news_agent

启动 LangGraph Dev Server

cd study
langgraph_cli dev --port 8123

---

🛠️ 技术栈

类别	技术	用途
核心框架	LangChain + LangGraph	Agent 编排与状态管理
LLM 服务	DeepSeek-V3 (SiliconFlow)	大语言模型推理
可观测性	LangSmith	调用链追踪与调试
可视化	Matplotlib	Agent 流程图绘制
配置管理	python-dotenv	环境变量管理

---

📝 学习路线建议

入门 ──────────────────────────────────────────────── 进阶

时间 Agent → 笑话 Agent → ReAct Agent → 新闻 Agent
  (工具调用)   (流水线)    (推理循环)   (中间件)
                                    ↓
                              中间件学习 → 任务规划 Agent → 编程助手
                                (三种模式)    (多阶段流水线)   (子Agent协作)

---

📄 License

MIT License

---

_{🐱 Built with LangChain & LangGraph | Powered by DeepSeek-V3}