┌──────────────────────────────────────┐
│              AI Agent                 │
│                                      │
│  🧠 大脑（LLM）：负责理解和思考       │
│     → 就像 GPT-4、Claude、通义千问    │
│                                      │
│  🛠 工具（Tools）：手和脚             │
│     → 搜索、发邮件、读文件、写代码    │
│                                      │
│  📝 记忆（Memory）：记事本            │
│     → 记住之前的对话和经验            │
│                                      │
│  📋 规划（Planning）：工作计划        │
│     → 把大任务拆成小步骤              │
│                                      │
└──────────────────────────────────────┘

普通聊天 AI：
  用户提问 → AI 回答 → 结束

AI Agent：
  用户提问 → AI 思考 → 调用工具 → 观察结果 → 继续思考
          → 可能再调用另一个工具 → 观察结果 → ... → 给出最终答案

🎯 编程助手    → 自动写代码、Debug、代码审查
📊 数据分析    → 自动处理 Excel、生成报表
🔍 信息搜索    → 自动搜索、整理、总结信息
📧 办公自动化  → 自动处理邮件、文档、日程
🛒 电商运营    → 自动选品、写文案、监控竞品
🎮 游戏NPC     → 智能对话、自主决策
📱 个人助手    → 日程管理、信息提醒、学习辅导

什么是 LLM？
- 就是 ChatGPT、Claude、通义千问背后的技术
- 它能理解文字、生成文字、推理逻辑
- 但它只能"想"，不能"做"

类比：一个超级聪明但被困在房间里的人

什么是 Prompt？
- 就是你发给 AI 的指令
- 好的 Prompt = 清晰的任务描述 + 约束条件 + 输出格式

例子：
❌ 差的 Prompt："帮我分析一下市场"
✅ 好的 Prompt："请分析 2026 年 AI Agent 市场的三个趋势，
   每个趋势给出一个具体的公司案例，用表格呈现"

什么是 Function Calling？
- 让 LLM 能够"调用外部工具"
- LLM 不直接执行，而是告诉你"我想调什么工具，传什么参数"
- 你的代码执行后，把结果喂回给 LLM

流程：
你 → LLM："明天北京天气？"
LLM → 你："我想调用 get_weather(city='北京')"
你 → 执行API → 结果："28°C，晴"
你 → LLM："工具返回了28°C，晴"
LLM → 你："明天北京28°C，晴天，适合出门"

ReAct = Reasoning（推理）+ Acting（行动）

循环过程：
Thought（思考）→ Action（行动）→ Observation（观察）→ Thought → Action → ... → 最终答案

这就是 Agent 能"多步完成任务"的秘密！

什么是 RAG？
- Retrieval-Augmented Generation（检索增强生成）
- 简单说：先从知识库里找到相关内容，再让 AI 基于这些内容回答

类比：
- 不用 RAG = 让你闭卷考试
- 用了 RAG = 让你开卷考试，还能精准翻到对应页

Agent 的记忆分两种：

短期记忆：记住当前对话的上下文
  → "刚才你说了要查天气，我已经查到了..."

长期记忆：记住历史经验和用户偏好
  → "你之前说过你住在北京，所以默认查北京天气"

# 1. 变量（存东西）
name = "小明"
age = 25

# 2. 列表（存一组东西）
tools = ["搜索", "计算器", "翻译"]
print(tools[0])  # 输出：搜索

# 3. 字典（存带标签的东西）
config = {"model": "gpt-4", "temperature": 0.7}
print(config["model"])  # 输出：gpt-4

# 4. if/else（做判断）
if age >= 18:
    print("成年人")

# 5. for 循环（重复做事）
for tool in tools:
    print(f"可用工具：{tool}")

# 6. 函数（封装一段逻辑）
def ask_agent(question):
    # 调用 API 的代码
    return "Agent 的回答"

# 7. 安装第三方包（在终端执行）
# pip install openai langchain

步骤：
1. 打开 coze.cn，用手机号注册
2. 点击"创建 Bot"
3. 写提示词："你是一个 AI 学习顾问，帮助用户学习 AI Agent"
4. 添加插件：搜索、网页读取
5. 配置知识库：上传几篇 AI Agent 教程的 PDF
6. 点"发布" → 在聊天窗口测试

全程不需要写一行代码！

步骤：
1. 打开 dify.ai，注册
2. 选择"创建空白应用" → 选"Agent"
3. 配置 LLM（选 GPT-4 或国产模型）
4. 添加工具（搜索、天气、计算器等）
5. 在画布上拖拽连接，设计 Agent 的工作流
6. 测试并发布

Dify 是开源的，也可以本地部署！

"""
你的第一个 AI Agent！
功能：一个能搜索 + 计算的智能助手
"""

from openai import OpenAI

client = OpenAI(api_key="your-api-key")

# 定义 Agent 可以使用的工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "查询指定城市的天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名"}
                },
                "required": ["city"]
            }
        }
    }
]

# 模拟天气工具的执行
def get_weather(city):
    # 实际项目中这里会调用真实的天气 API
    weather_data = {
        "北京": "28°C，晴天",
        "上海": "25°C，多云",
        "深圳": "32°C，雷阵雨"
    }
    return weather_data.get(city, f"{city}：数据暂无")

# Agent 主循环
messages = [{"role": "user", "content": "北京和上海明天天气怎么样？哪个更适合出门？"}]

# 第一轮：发送给 LLM
response = client.chat.completions.create(
    model="gpt-4",
    messages=messages,
    tools=tools
)

message = response.choices[0].message
print(f"🤖 Agent 思考：{message}")

# 如果 Agent 决定调用工具
if message.tool_calls:
    for tool_call in message.tool_calls:
        if tool_call.function.name == "get_weather":
            import json
            args = json.loads(tool_call.function.arguments)
            result = get_weather(args["city"])
            print(f"🛠 执行工具：查询{args['city']}天气 → {result}")

            # 把工具结果喂回给 LLM
            messages.append(message)
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result
            })

    # 第二轮：LLM 基于工具结果生成最终回答
    final_response = client.chat.completions.create(
        model="gpt-4",
        messages=messages,
        tools=tools
    )
    print(f"\n💬 最终回答：{final_response.choices[0].message.content}")

# 输出示例：
# 🤖 Agent 思考：需要调用两次天气查询
# 🛠 执行工具：查询北京天气 → 28°C，晴天
# 🛠 执行工具：查询上海天气 → 25°C，多云
# 💬 最终回答：北京28°C晴天更适合出门，上海多云也可以但温度稍低。

用户输入
   ↓
┌─────────────────────────────────┐
│         Agent 主循环             │
│                                 │
│  1. 把用户消息 + 工具列表发给 LLM │
│  2. LLM 决定：                   │
│     a. 直接回答 → 返回给用户     │
│     b. 调用工具 → 执行工具        │
│        → 把结果喂回 LLM          │
│        → 回到步骤 1              │
│  3. 循环直到 LLM 给出最终回答    │
│                                 │
└─────────────────────────────────┘
   ↓
返回结果给用户

"""
手写一个最简 Agent，不用 LangChain 等框架
帮助你理解 Agent 的本质
"""
import json
from openai import OpenAI

client = OpenAI(api_key="your-api-key")

class SimpleAgent:
    def __init__(self):
        self.tools = {}       # 注册的工具
        self.messages = []    # 对话历史（短期记忆）

    def register_tool(self, name, func, description, parameters):
        """注册一个工具"""
        self.tools[name] = {
            "func": func,
            "schema": {
                "type": "function",
                "function": {
                    "name": name,
                    "description": description,
                    "parameters": parameters
                }
            }
        }

    def run(self, user_input, max_steps=5):
        """运行 Agent 主循环"""
        self.messages.append({"role": "user", "content": user_input})

        tool_schemas = [t["schema"] for t in self.tools.values()]

        for step in range(max_steps):
            print(f"\n--- 第 {step + 1} 步 ---")

            # 1. 让 LLM 思考
            response = client.chat.completions.create(
                model="gpt-4",
                messages=self.messages,
                tools=tool_schemas if tool_schemas else None
            )

            msg = response.choices[0].message
            self.messages.append(msg)

            # 2. 检查是否需要调工具
            if not msg.tool_calls:
                # 不需要调工具，直接返回
                print(f"💬 最终回答：{msg.content}")
                return msg.content

            # 3. 执行所有工具调用
            for tool_call in msg.tool_calls:
                tool_name = tool_call.function.name
                tool_args = json.loads(tool_call.function.arguments)

                print(f"🛠 调用工具：{tool_name}({tool_args})")

                # 执行工具
                if tool_name in self.tools:
                    result = self.tools[tool_name]["func"](**tool_args)
                    print(f"📊 工具返回：{result}")
                else:
                    result = f"错误：未知工具 {tool_name}"

                # 把结果喂回
                self.messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": str(result)
                })

        return "达到最大步数限制，任务未完成。"


# ===== 使用示例 =====
agent = SimpleAgent()

# 注册工具
def calculate(expression):
    """安全计算数学表达式"""
    try:
        return str(eval(expression))  # 生产环境请用更安全的方式
    except:
        return "计算错误"

def search_web(query):
    """模拟网页搜索"""
    fake_results = {
        "Python": "Python 是最流行的编程语言之一，适合 AI 开发",
        "Agent": "AI Agent 是能自主执行任务的智能体",
    }
    for key in fake_results:
        if key.lower() in query.lower():
            return fake_results[key]
    return f"搜索'{query}'：暂无结果"

agent.register_tool(
    "calculate", calculate,
    "计算数学表达式",
    {"type": "object", "properties": {"expression": {"type": "string"}}, "required": ["expression"]}
)
agent.register_tool(
    "search", search_web,
    "搜索互联网信息",
    {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}
)

# 测试！
agent.run("帮我搜索一下什么是AI Agent，然后算一下 2026 * 3 等于多少")

pip install smolagents

# LangChain 版本的简单 Agent
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain.tools import tool
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# 定义工具
@tool
def search_web(query: str) -> str:
    """搜索互联网信息"""
    return f"搜索结果：{query} 的相关信息..."

@tool  
def calculate(expression: str) -> str:
    """计算数学表达式"""
    return str(eval(expression))

# 创建 Agent
llm = ChatOpenAI(model="gpt-4")
tools = [search_web, calculate]
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个有用的AI助手，可以使用工具帮助用户。"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 运行
result = agent_executor.invoke({"input": "搜索AI Agent并计算100*25"})
print(result["output"])

功能：
  - 上传文档（PDF/Word/TXT）
  - 自动分块 + 向量化
  - 用户提问 → 自动检索相关内容 → 生成回答

技术栈：
  - LangChain / LlamaIndex
  - ChromaDB（向量数据库）
  - OpenAI Embeddings + GPT-4
  - Gradio / Streamlit（界面）

学到什么：
  ✅ RAG 的完整实现
  ✅ 向量数据库的使用
  ✅ 文档分块和检索策略

功能：
  - 定时监控指定网页/数据源
  - 自动分析变化
  - 执行相应操作（发通知/生成报告）
  - 记录历史数据

技术栈：
  - LangGraph（工作流编排）
  - 多个 Tool（网页抓取、邮件发送、数据库操作）
  - 定时任务（APScheduler）

学到什么：
  ✅ 复杂工作流设计
  ✅ 多工具协作
  ✅ Agent 的定时调度

功能：
  - 多个 Agent 扮演不同角色
  - Agent 之间能对话和协作
  - 自动分配任务、汇总结果

示例：AI 开发团队
  - 产品经理 Agent：分析需求
  - 程序员 Agent：写代码
  - 测试员 Agent：测试代码
  - 评审员 Agent：代码审查

技术栈：
  - CrewAI / AutoGen
  - 自定义 Agent 角色和工具
  - Agent 间通信协议

学到什么：
  ✅ 多 Agent 系统设计
  ✅ 角色定义和任务分配
  ✅ Agent 间通信和协调

✅ 好的工具：search_web(query)、send_email(to, subject, body)
❌ 坏的工具：do_everything(action, params)

✅ 好的 System Prompt：
"你是一个数据分析 Agent。
可用工具：search、calculate、read_csv、plot_chart。
工作方式：先收集数据，再分析，最后可视化。
回答语言：中文。
如果不确定，先调用工具确认，不要猜测。"

❌ 坏的 System Prompt："你是一个助手"

短期记忆：当前对话（最近 10 轮）
中期记忆：今天的工作上下文
长期记忆：用户偏好、历史经验

- 设置最大步数（防止死循环）
- 工具调用失败时要有备用方案
- 输出要有格式校验
- 关键操作要人工确认

第一版：1 个工具，能跑通
第二版：加 2-3 个工具
第三版：加记忆
第四版：加错误处理
第五版：加用户界面

第 1-2 周 🟢 搞懂概念
  └─ 看 3 个讲解视频 + 理解 ReAct 循环

第 3-5 周 🟡 熟练使用
  └─ Coze 搭建 Agent + 学 Python + 写代码调 API

第 6-9 周 🟠 理解原理
  └─ 手写 Agent + 读 smolagents 源码 + LangChain 实战

第 10 周+ 🔴 独立创造
  └─ 做 3 个实战项目（知识库→工作流→多Agent）

小白入门路径（按顺序学，每个 1-2 天）：

Day 1-2   📺 B站看 2-3 个 "AI Agent 通俗讲解" 视频
Day 3-4   📖 读 Lilian Weng 的 "LLM Powered Autonomous Agents"
Day 5-7   🎓 吴恩达 Prompt Engineering 课程（1小时）
Day 8-10  🎓 吴恩达 Functions/Tools/Agents 课程（3小时）
Day 11-14 🛠 用 Coze/Dify 搭建第一个 Agent（零代码）
Day 15-17 🎓 吴恩达 AI Agents in LangGraph 课程（4小时）
Day 18-21 💻 写第一个 Python Agent 代码（参考本文第四章）
Day 22-28 🛠 做项目：个人知识库 Agent（RAG）
Day 29-35 💻 读 smolagents 源码，理解原理
Day 36-42 🛠 做项目：自动化工作流 Agent
Day 43-56 🛠 做项目：多 Agent 协作系统