ShallowAgents 是一个专为开发者设计的 Agent 核心原理教学项目。
核心宗旨：拒绝过度封装，剔除所有非核心的兼容性逻辑与异步噪音。仅使用 Python 原生数据结构与 OpenAI SDK，用 < 400 行 的总代码量，拆解智能体（Agent）的底层运行机制。
我们通过 8 个完全独立的脚本，解构了现代 Agent 的全套支柱。
| 序号 | 模块名称 | 核心功能 | 逻辑代码量 | 学习目标 |
|---|---|---|---|---|
| 01 | 基础调用 | 模型交互与角色定义 | < 30 行 | 显式区分 system_prompt (规则) 与 user_prompt (指令)。 |
| 02 | 对话记忆 | 上下文维持机制 | < 45 行 | 通过手动拼接历史对话 (Prompt Injection)，还原记忆的物理本质。 |
| 03 | 工具调用 | 外部函数集成 | < 80 行 | 实现 Function Calling 闭环：指令识别 -> 本地执行 -> 数据回传。 |
| 04 | 推理循环 | 自主决策引擎 (ReAct) | < 70 行 | 基于 ReAct 模式，利用 while 循环驱动 Agent 实现思考-行动闭环。 |
| 05 | 知识检索 | RAG 技术原型 | < 50 行 | 实现"检索-增强-生成"全流程，解决模型时效性与幻觉问题。 |
| 06 | 自我反思 | 多轮审阅与修正 | < 50 行 | 通过"生成-评审-优化"的博弈架构，提升复杂任务输出质量。 |
| 07 | 多智能体 | 协作与任务分发 | < 60 行 | 学习不同 Agent (如 Planner 与 Executor) 之间如何通信与协作。 |
| 08 | MCP 原型 | 工具发现与解耦 | < 50 行 | 模拟 Model Context Protocol 协议，实现工具的动态发现与远程调用。 |
只需安装最基础的依赖：
pip install openai python-dotenv参考仓库中的 .env.example 创建 .env 文件。
本项目各模块完全独立，没有任何耦合。你可以按顺序运行以下脚本来体验 Agent 的进化之路：
# [选修] 综合演示：体验集成多智能体与 MCP 理念的系统原型
python main.py
# 01. 体验最基础的 Agent 对话与人设切换
python 01_llm_basic.py
# 02. 体验具备"短期记忆"的对话（观察 Prompt 拼接过程）
python 02_memory_chat.py
# 03. 体验 Agent 如何自主操控 Python 函数（查天气）
python 03_tool_use.py
# 04. 体验 ReAct 循环：Agent 如何通过多步推理解决数学题
python 04_react_loop.py
# 05. 体验 RAG：Agent 如何检索外部知识库回答问题
python 05_simple_rag.py
# 06. 体验自我反思：Agent 如何通过禁词挑战完成自我修正
python 06_reflection.py
# 07. 体验多智能体协作：Planner (规划者) 与 Executor (执行者)
python 07_multi_agent.py
# 08. 体验 MCP 协议：模拟工具的动态发现与远程调用过程
python 08_mcp_concept.py- 透明 (Transparent)：没有黑盒封装。没有复杂的类继承和 Pydantic 模型，代码即是最好的文档。
- 解耦 (Decoupled)：每个功能模块完全独立。你可以像查字典一样，运行并修改任意一个核心组件。
- 标准 (Standardized)：统一采用
invoke/chat等行业标准命名，严格遵循 OpenAI 协议规范。
本项目基于 OpenAI SDK 标准协议，理论上支持所有兼容 OpenAI 格式的模型供应商。我们已经在 .env.example 中提供了以下厂商的配置模板：
- OpenAI (GPT-4o, GPT-4o-mini 等)
- DeepSeek (性价比首选，深度求索系列)
- Alibaba Qwen (阿里通义千问系列)
- Zhipu AI (智谱 GLM 系列)
- 各中转代理服务 (如智增增等)
Enjoy Coding! 🚀