Add comprehensive Agent development tutorials and examples

README.md

@@ -1 +1,107 @@
-# Agent-Basic-Tutorial
+# Agent 基础教程 (Agent Basic Tutorial)
+
+欢迎来到 Agent 基础教程！本仓库旨在为开发者提供关于 AI Agent 使用的基础指导教程和实践经验分享。
+
+## 📚 简介
+
+AI Agent（智能代理）是一种能够自主感知环境、做出决策并执行任务的智能系统。本教程将帮助您从零开始学习和掌握 Agent 的开发与应用。
+
+## 🎯 教程目标
+
+- 理解 Agent 的核心概念和工作原理
+- 掌握 Agent 的基本开发方法
+- 学习 Agent 的实践应用场景
+- 了解 Agent 开发的最佳实践
+- 积累实际项目经验
+
+## 📖 教程目录
+
+### 基础教程
+
+1. [**Agent 简介**](tutorials/01-introduction.md)
+   - 什么是 Agent
+   - Agent 的特点和优势
+   - Agent 的应用场景
+
+2. [**快速开始**](tutorials/02-getting-started.md)
+   - 环境准备
+   - 第一个 Agent 程序
+   - 基本操作示例
+
+3. [**核心概念**](tutorials/03-core-concepts.md)
+   - Agent 架构
+   - 感知与决策
+   - 工具与能力
+   - 记忆系统
+   - 规划与执行
+
+4. [**实践案例**](tutorials/04-practical-examples.md)
+   - 简单对话 Agent
+   - 任务执行 Agent
+   - 数据分析 Agent
+   - 代码生成 Agent
+
+5. [**最佳实践**](tutorials/05-best-practices.md)
+   - Prompt 工程技巧
+   - Agent 设计原则
+   - 性能优化方法
+   - 错误处理策略
+
+6. [**高级主题**](tutorials/06-advanced-topics.md)
+   - 多 Agent 协作
+   - 长期记忆管理
+   - Agent 安全性
+   - 评估与测试
+
+7. [**常见问题与故障排除**](tutorials/07-troubleshooting.md)
+   - 常见错误及解决方案
+   - 调试技巧
+   - 性能问题诊断
+
+8. [**资源与参考**](tutorials/08-resources.md)
+   - 推荐工具和框架
+   - 学习资源
+   - 社区与支持
+
+## 💡 代码示例
+
+在 [examples](examples/) 目录中，您可以找到各种实用的代码示例：
+
+- 基础 Agent 实现
+- 工具集成示例
+- 实际应用场景演示
+
+## 🚀 快速开始
+
+1. 克隆本仓库：
+```bash
+git clone https://github.com/sunshuang1866/Agent-Basic-Tutorial.git
+cd Agent-Basic-Tutorial
+```
+
+2. 从 [01-introduction.md](tutorials/01-introduction.md) 开始学习
+
+3. 跟随教程逐步实践
+
+4. 查看 [examples](examples/) 目录中的代码示例
+
+## 🤝 贡献指南
+
+欢迎贡献您的经验和案例！如果您有好的想法或发现问题：
+
+1. Fork 本仓库
+2. 创建您的特性分支
+3. 提交您的修改
+4. 发起 Pull Request
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
+
+## 📧 联系方式
+
+如有问题或建议，欢迎提 Issue 或联系维护者。
+
+---
+
+**Happy Learning! 祝学习愉快！** 🎉

examples/01_simple_agent.py

@@ -0,0 +1,130 @@
+"""
+简单 Agent 示例
+
+这个示例展示了如何创建一个基本的 Agent，包含一个简单的时间查询工具。
+
+学习要点：
+1. Agent 的基本结构
+2. 如何定义工具
+3. 如何与 Agent 交互
+"""
+
+from langchain.agents import initialize_agent, AgentType
+from langchain.chat_models import ChatOpenAI
+from langchain.tools import Tool
+from datetime import datetime
+import os
+from dotenv import load_dotenv
+
+# 加载环境变量
+load_dotenv()
+
+# 检查 API 密钥
+if not os.getenv('OPENAI_API_KEY'):
+    print("错误：未找到 OPENAI_API_KEY 环境变量")
+    print("请在 .env 文件中设置：OPENAI_API_KEY=your-api-key")
+    exit(1)
+
+
+def get_current_time() -> str:
+    """
+    获取当前时间
+
+    Returns:
+        str: 格式化的当前时间字符串
+    """
+    now = datetime.now()
+    return now.strftime("%Y年%m月%d日 %H:%M:%S")
+
+
+def get_current_date() -> str:
+    """
+    获取当前日期
+
+    Returns:
+        str: 格式化的当前日期字符串
+    """
+    now = datetime.now()
+    return now.strftime("%Y年%m月%d日 星期%w")
+
+
+def main():
+    """主函数"""
+
+    print("=" * 50)
+    print("简单 Agent 示例")
+    print("=" * 50)
+    print()
+
+    # 1. 初始化大语言模型
+    print("正在初始化 Agent...")
+    llm = ChatOpenAI(
+        temperature=0,  # 温度为0，使输出更确定
+        model="gpt-3.5-turbo"
+    )
+
+    # 2. 定义工具列表
+    tools = [
+        Tool(
+            name="GetCurrentTime",
+            func=get_current_time,
+            description="获取当前的日期和时间。当用户询问现在几点或当前时间时使用此工具。"
+        ),
+        Tool(
+            name="GetCurrentDate",
+            func=get_current_date,
+            description="获取当前的日期和星期。当用户询问今天是几号或星期几时使用此工具。"
+        ),
+    ]
+
+    # 3. 初始化 Agent
+    agent = initialize_agent(
+        tools=tools,
+        llm=llm,
+        agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
+        verbose=True,  # 显示详细执行过程
+        handle_parsing_errors=True  # 处理解析错误
+    )
+
+    # 4. 测试 Agent
+    test_queries = [
+        "现在几点了？",
+        "今天是星期几？",
+        "告诉我现在的完整日期和时间",
+    ]
+
+    for i, query in enumerate(test_queries, 1):
+        print(f"\n{'='*50}")
+        print(f"测试 {i}: {query}")
+        print(f"{'='*50}\n")
+
+        try:
+            response = agent.run(query)
+            print(f"\n✅ 回答：{response}\n")
+        except Exception as e:
+            print(f"\n❌ 错误：{str(e)}\n")
+
+    # 5. 交互模式
+    print("\n" + "=" * 50)
+    print("进入交互模式（输入 'quit' 或 'exit' 退出）")
+    print("=" * 50 + "\n")
+
+    while True:
+        user_input = input("您的问题：").strip()
+
+        if user_input.lower() in ['quit', 'exit', '退出', 'q']:
+            print("\n再见！👋")
+            break
+
+        if not user_input:
+            continue
+
+        try:
+            response = agent.run(user_input)
+            print(f"\n回答：{response}\n")
+        except Exception as e:
+            print(f"\n错误：{str(e)}\n")
+
+
+if __name__ == "__main__":
+    main()