{
"cells": [
{
"cell_type": "markdown",
"id": "2bf5f533",
"metadata": {},
"source": [
"# 🧠 最小 AI 编程智能体 — 从零理解 Agent Loop\n",
"\n",
"> **目标**:用约 150 行 Python 代码,从零搭建一个 AI 编程助手,理解大模型「智能体」的工作原理。\n",
"\n",
"---\n",
"\n",
"## 你将学到什么?\n",
"\n",
"- 大模型(LLM)如何通过 **函数调用(Function Calling)** 操作你的文件\n",
"- **Agent Loop** 是什么——整个 AI 编程助手的核心架构\n",
"- 亲手实现一个能读文件、写文件、列出目录的 AI 助手\n",
"\n",
"## 你需要准备什么?\n",
"\n",
"| 你需要 | 说明 |\n",
"|--------|------|\n",
"| LLM API Key | 任一支持 OpenAI 兼容接口的模型均可(智谱 / DeepSeek / Qwen / OpenAI 等)|\n",
"| Python 基础 | 了解变量、函数、`print()` 即可 |\n",
"\n",
"> 💡 免费额度推荐:[智谱 GLM-4](https://open.bigmodel.cn/) / [DeepSeek](https://platform.deepseek.com/)\n",
"\n",
"## 学习路径\n",
"\n",
"1. **Part 1** ← 你在这里:安装依赖,配置模型,验证连接\n",
"2. **Part 2**:直接体验 Agent 的效果(先感受,不用管代码)\n",
"3. **Part 3**:逐段拆解代码,理解每一个部分\n",
"4. **Part 4**:🎉 自由探索你的 Agent\n",
"\n",
"> ⚠️ **请按顺序执行每个 Cell**,不要跳着运行。\n"
]
},
{
"cell_type": "markdown",
"id": "5d65c7e1",
"metadata": {},
"source": [
"## Part 1:环境准备\n",
"\n",
"### 1.1 安装依赖"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "07d09095",
"metadata": {},
"outputs": [],
"source": [
"!pip install openai -q"
]
},
{
"cell_type": "markdown",
"id": "76b9eeb1",
"metadata": {},
"source": [
"### 1.2 配置你的模型\n",
"\n",
"> ⚠️ **重要提醒**:API Key 相当于你账户的密码。**不要**把含 Key 的 Notebook 分享给他人!\n",
"> 每次重新打开 Notebook 需要重新填入 Key。\n",
"\n",
"选择任一支持 OpenAI 兼容接口的模型,修改下方配置后运行。\n",
"\n",
"| Provider | base_url | 免费额度 |\n",
"|----------|----------|---------|\n",
"| 智谱 | `https://open.bigmodel.cn/api/paas/v4` | ✅ 有 |\n",
"| DeepSeek | `https://api.deepseek.com` | ✅ 有 |\n",
"| Qwen(阿里) | `https://dashscope.aliyuncs.com/compatible-mode/v1` | ✅ 有 |\n",
"| OpenAI | `https://api.openai.com/v1` | ❌ 付费 |\n",
"| 其他兼容接口 | 问你用的提供商 | - |"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ab20e527",
"metadata": {},
"outputs": [],
"source": "# 👇 改下面三行为你自己的配置\nAPI_KEY = \"********************************\"\nBASE_URL = \"https://open.bigmodel.cn/api/paas/v4\" # 改成你用的服务商地址\nMODEL = \"glm-4.5-air\" # 改成你用的模型名\n\nprint(\"✅ 配置已保存(请运行下一个 Cell 验证连接)\")"
},
{
"cell_type": "markdown",
"id": "c4fe72d0",
"metadata": {},
"source": [
"### 1.3 验证模型连接\n",
"\n",
"发送一条测试消息,确认 API 可用。"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "730a4b25",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"⚠️ 模型返回 content 为空(<class 'str'>),但 API 调用本身成功\n",
" 模型信息: glm-4.5-air\n",
" 这通常不影响后续 function calling 功能\n"
]
}
],
"source": [
"from openai import OpenAI\n",
"\n",
"client = OpenAI(api_key=API_KEY, base_url=BASE_URL)\n",
"\n",
"try:\n",
" response = client.chat.completions.create(\n",
" model=MODEL,\n",
" messages=[{\"role\": \"user\", \"content\": \"你好,请回复'连接成功'\"}],\n",
" max_tokens=50\n",
" )\n",
" msg = response.choices[0].message\n",
" # 检查 content 是否为 None(某些 provider 在 function calling 模式下不返回 content)\n",
" reply = msg.content\n",
" if reply is None or reply.strip() == \"\":\n",
" print(f\"⚠️ 模型返回 content 为空({type(reply)}),但 API 调用本身成功\")\n",
" print(f\" 模型信息: {response.model}\")\n",
" print(f\" 这通常不影响后续 function calling 功能\")\n",
" else:\n",
" print(f\"✅ 连接成功!模型回复:{reply}\")\n",
" print(f\" 使用模型:{response.model}\")\n",
"except Exception as e:\n",
" print(f\"❌ 连接失败:{e}\")\n",
" print(f\" 请检查:\")\n",
" print(f\" 1) API Key 是否正确\")\n",
" print(f\" 2) BASE_URL 是否正确(注意末尾不要带 /chat/completions)\")\n",
" print(f\" 3) MODEL 名称是否正确\")"
]
},
{
"cell_type": "markdown",
"id": "6460c24a",
"metadata": {},
"source": [
"---\n",
"\n",
"## Part 2:先感受!Agent 能做什么\n",
"\n",
"> 下面这个 Cell 定义了完整的智能体。**先点运行,不用管里面是什么代码**——我们会在 Part 3 逐行拆解。\n",
"> \n",
"> 运行成功后,你会看到 Agent 已经准备好,等待你的指令。"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "4a85a9a4",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"✅ Agent 初始化完成!试试下面的示例吧 👇\n"
]
}
],
"source": [
"import json\n",
"import os\n",
"from pathlib import Path\n",
"\n",
"# ═══════════════════════════════════════════\n",
"# Agent 完整定义(点击左侧三角展开查看)\n",
"# ═══════════════════════════════════════════\n",
"\n",
"# 路径工具\n",
"def resolve_path(path_str: str) -> Path:\n",
" \"\"\"相对路径转绝对路径\"\"\"\n",
" p = Path(path_str).expanduser()\n",
" return p.resolve() if not p.is_absolute() else p\n",
"\n",
"# 工具 1:读取文件\n",
"def read_file(path: str) -> dict:\n",
" \"\"\"读取文件的完整内容\"\"\"\n",
" full_path = resolve_path(path)\n",
" content = full_path.read_text(encoding=\"utf-8\")\n",
" return {\"file_path\": str(full_path), \"content\": content}\n",
"\n",
"# 工具 2:列出目录\n",
"def list_files(path: str) -> dict:\n",
" \"\"\"列出目录中的文件和子目录\"\"\"\n",
" full_path = resolve_path(path)\n",
" items = []\n",
" for item in sorted(full_path.iterdir()):\n",
" items.append({\"filename\": item.name, \"type\": \"file\" if item.is_file() else \"dir\"})\n",
" return {\"path\": str(full_path), \"files\": items}\n",
"\n",
"# 工具 3:编辑文件\n",
"def edit_file(path: str, old_str: str, new_str: str) -> dict:\n",
" \"\"\"编辑文件:old_str为空则创建,非空则替换首次出现\"\"\"\n",
" full_path = resolve_path(path)\n",
" if old_str == \"\":\n",
" full_path.write_text(new_str, encoding=\"utf-8\")\n",
" return {\"path\": str(full_path), \"action\": \"created_file\"}\n",
" original = full_path.read_text(encoding=\"utf-8\")\n",
" if old_str not in original:\n",
" return {\"path\": str(full_path), \"action\": \"old_str not found\"}\n",
" edited = original.replace(old_str, new_str, 1)\n",
" full_path.write_text(edited, encoding=\"utf-8\")\n",
" return {\"path\": str(full_path), \"action\": \"edited\"}\n",
"\n",
"# 工具注册表\n",
"TOOL_REGISTRY = {\n",
" \"read_file\": read_file,\n",
" \"list_files\": list_files,\n",
" \"edit_file\": edit_file,\n",
"}\n",
"\n",
"# 工具 JSON Schema(LLM 的「菜单」)\n",
"TOOLS = [\n",
" {\n",
" \"type\": \"function\",\n",
" \"function\": {\n",
" \"name\": \"read_file\",\n",
" \"description\": \"读取文件的完整内容\",\n",
" \"parameters\": {\n",
" \"type\": \"object\",\n",
" \"properties\": {\"path\": {\"type\": \"string\", \"description\": \"文件路径\"}},\n",
" \"required\": [\"path\"]\n",
" }\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"function\",\n",
" \"function\": {\n",
" \"name\": \"list_files\",\n",
" \"description\": \"列出目录中的文件和子目录\",\n",
" \"parameters\": {\n",
" \"type\": \"object\",\n",
" \"properties\": {\"path\": {\"type\": \"string\", \"description\": \"目录路径\"}},\n",
" \"required\": [\"path\"]\n",
" }\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"function\",\n",
" \"function\": {\n",
" \"name\": \"edit_file\",\n",
" \"description\": \"编辑文件:old_str为空则创建文件;否则替换首次出现的old_str\",\n",
" \"parameters\": {\n",
" \"type\": \"object\",\n",
" \"properties\": {\n",
" \"path\": {\"type\": \"string\", \"description\": \"文件路径\"},\n",
" \"old_str\": {\"type\": \"string\", \"description\": \"要替换的文本,空字符串=创建新文件\"},\n",
" \"new_str\": {\"type\": \"string\", \"description\": \"替换后的文本\"}\n",
" },\n",
" \"required\": [\"path\", \"old_str\", \"new_str\"]\n",
" }\n",
" }\n",
" }\n",
"]\n",
"\n",
"# 系统提示词\n",
"SYSTEM_PROMPT = \"\"\"你是一个编程助手智能体。你可以使用以下工具:\n",
"\n",
" • read_file:读取文件的完整内容\n",
" • list_files:列出目录中的文件和子目录\n",
" • edit_file:编辑文件(old_str为空则创建,非空则替换)\n",
"\n",
"使用规则:\n",
"1. 先判断是否需要工具\n",
"2. 需要时直接发起工具调用\n",
"3. 收到结果后继续推理或回复\n",
"4. 创建文件时 old_str 传空字符串\"\"\n",
"5. 修改文件前,先 read_file 了解当前内容\n",
"\"\"\"\n",
"\n",
"# ── SimpleAgent 类 ────────────────────────────\n",
"class SimpleAgent:\n",
" \"\"\"最小 AI 编程智能体\"\"\"\n",
" \n",
" def __init__(self, api_key, base_url, model):\n",
" self.client = OpenAI(api_key=api_key, base_url=base_url)\n",
" self.model = model\n",
" self.conversation = [{\"role\": \"system\", \"content\": SYSTEM_PROMPT}]\n",
" \n",
" def chat(self, user_message):\n",
" \"\"\"处理一条用户消息,运行完整的 Agent Loop\"\"\"\n",
" print(f\"📝 用户: {user_message}\")\n",
" self.conversation.append({\"role\": \"user\", \"content\": user_message})\n",
" \n",
" while True: # ← 内层循环\n",
" response = self.client.chat.completions.create(\n",
" model=self.model,\n",
" messages=self.conversation,\n",
" tools=TOOLS,\n",
" tool_choice=\"auto\",\n",
" )\n",
" msg = response.choices[0].message\n",
" \n",
" # 没有 tool_calls → LLM 直接回复,结束内层循环\n",
" if not msg.tool_calls:\n",
" self.conversation.append({\"role\": \"assistant\", \"content\": msg.content})\n",
" print(f\"🤖 Agent: {msg.content or '(空消息)'}\\n\")\n",
" return msg.content\n",
" \n",
" # 有 tool_calls → 执行工具\n",
" self.conversation.append({\n",
" \"role\": \"assistant\",\n",
" \"content\": msg.content,\n",
" \"tool_calls\": [{\n",
" \"id\": tc.id,\n",
" \"type\": \"function\",\n",
" \"function\": {\"name\": tc.function.name, \"arguments\": tc.function.arguments}\n",
" } for tc in msg.tool_calls]\n",
" })\n",
" \n",
" # 逐个执行工具调用\n",
" for tc in msg.tool_calls:\n",
" tool_name = tc.function.name\n",
" tool_args = json.loads(tc.function.arguments)\n",
" tool_fn = TOOL_REGISTRY.get(tool_name)\n",
" \n",
" print(f\" 🔧 调用工具: {tool_name}({json.dumps(tool_args, ensure_ascii=False)})\")\n",
" \n",
" if tool_fn is None:\n",
" result = {\"error\": f\"未知工具: {tool_name}\"}\n",
" else:\n",
" try:\n",
" result = tool_fn(**tool_args)\n",
" except Exception as e:\n",
" result = {\"error\": str(e)}\n",
" \n",
" preview = json.dumps(result, ensure_ascii=False)\n",
" print(f\" 📋 工具结果: {preview[:120]}{'...' if len(preview) > 120 else ''}\")\n",
" \n",
" self.conversation.append({\n",
" \"role\": \"tool\",\n",
" \"tool_call_id\": tc.id,\n",
" \"content\": json.dumps(result, ensure_ascii=False)\n",
" })\n",
" # 继续内层循环,让 LLM 处理工具结果\n",
"\n",
"# 初始化 Agent\n",
"agent = SimpleAgent(API_KEY, BASE_URL, MODEL)\n",
"print(\"✅ Agent 初始化完成!试试下面的示例吧 👇\")"
]
},
{
"cell_type": "markdown",
"id": "e5eac904",
"metadata": {},
"source": [
"### 示例 1:创建文件\n",
"\n",
"让 Agent 创建一个 `hello.py`。注意观察 `edit_file` 工具被调用时 `old_str` 为空。"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "f7da918a",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"📝 用户: 创建一个文件 hello.py,内容为打印 'hello ,小帅' 的 Python 代码\n",
" 🔧 调用工具: edit_file({\"path\": \"hello.py\", \"old_str\": \"\", \"new_str\": \"print('hello ,小帅')\"})\n",
" 📋 工具结果: {\"path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\\\\hello.py\", \"action\": \"created_file\"}\n",
"🤖 Agent: \n",
"已成功创建 hello.py 文件,文件内容为:\n",
"```python\n",
"print('hello ,小帅')\n",
"```\n",
"\n",
"这个文件包含了您要求的 Python 代码,运行后会打印出 \"hello ,小帅\"。\n",
"\n"
]
},
{
"data": {
"text/plain": [
"'\\n已成功创建 hello.py 文件,文件内容为:\\n```python\\nprint(\\'hello ,小帅\\')\\n```\\n\\n这个文件包含了您要求的 Python 代码,运行后会打印出 \"hello ,小帅\"。'"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"agent.chat(\"创建一个文件 hello.py,内容为打印 'hello ,小帅' 的 Python 代码\")"
]
},
{
"cell_type": "markdown",
"id": "cecb7420",
"metadata": {},
"source": [
"### 示例 2:修改文件(重点观察!)\n",
"\n",
"让 Agent 给 `hello.py` 添加一个函数。**仔细观察输出**:Agent 会**自动先读文件,再修改**——这个「先读后改」的决策完全是 LLM 自己做出的!"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "e8613167",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"📝 用户: 给 hello.py 添加一个加法函数 add(a, b),返回两数之和\n",
" 🔧 调用工具: read_file({\"path\": \"hello.py\"})\n",
" 📋 工具结果: {\"file_path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\\\\hello.py\", \"content\": \"print('hello ,小帅')\"}\n",
" 🔧 调用工具: edit_file({\"path\": \"hello.py\", \"old_str\": \"print('hello ,小帅')\", \"new_str\": \"def add(a, b):\\n return a + b\\n\\nprint('hello ,小帅')\"})\n",
" 📋 工具结果: {\"path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\\\\hello.py\", \"action\": \"edited\"}\n",
" 🔧 调用工具: read_file({\"path\": \"hello.py\"})\n",
" 📋 工具结果: {\"file_path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\\\\hello.py\", \"content\": \"def add(a, b):\\n return a + b\\n\\nprint('hello ...\n",
"🤖 Agent: \n",
"已成功为 hello.py 添加了 add(a, b) 函数。现在文件内容为:\n",
"\n",
"```python\n",
"def add(a, b):\n",
" return a + b\n",
"\n",
"print('hello ,小帅')\n",
"```\n",
"\n",
"这个 add 函数可以接收两个参数 a 和 b,并返回它们的和。\n",
"\n"
]
},
{
"data": {
"text/plain": [
"\"\\n已成功为 hello.py 添加了 add(a, b) 函数。现在文件内容为:\\n\\n```python\\ndef add(a, b):\\n return a + b\\n\\nprint('hello ,小帅')\\n```\\n\\n这个 add 函数可以接收两个参数 a 和 b,并返回它们的和。\""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"agent.chat(\"给 hello.py 添加一个加法函数 add(a, b),返回两数之和\")"
]
},
{
"cell_type": "markdown",
"id": "357caf33",
"metadata": {},
"source": [
"👀 **查看左侧文件树**,双击 `hello.py` 看看内容是否已经更新!"
]
},
{
"cell_type": "markdown",
"id": "878e06ff",
"metadata": {},
"source": [
"### 示例 3:列出目录\n",
"\n",
"让 Agent 看看当前目录有哪些文件。"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "4440668e",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"📝 用户: 列出当前目录的所有文件\n",
" 🔧 调用工具: list_files({\"path\": \".\"})\n",
" 📋 工具结果: {\"path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\", \"files\": [{\"filename\": \".env\", \"type\": \"file\"}, {\"filename\": \".env.example\",...\n",
" 🔧 调用工具: read_file({\"path\": \"hello.py\"})\n",
" 📋 工具结果: {\"error\": \"[Errno 2] No such file or directory: 'D:\\\\\\\\00_mywork\\\\\\\\15_agent_loop_cc\\\\\\\\hello.py'\"}\n",
" 🔧 调用工具: edit_file({\"path\": \"hello.py\", \"old_str\": \"\", \"new_str\": \"print('hello ,小帅')\"})\n",
" 📋 工具结果: {\"path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\\\\hello.py\", \"action\": \"created_file\"}\n",
" 🔧 调用工具: list_files({\"path\": \".\"})\n",
" 📋 工具结果: {\"path\": \"D:\\\\00_mywork\\\\15_agent_loop_cc\", \"files\": [{\"filename\": \".env\", \"type\": \"file\"}, {\"filename\": \".env.example\",...\n",
"🤖 Agent: \n",
"现在可以看到当前目录包含以下文件和目录:\n",
"\n",
"**文件:**\n",
"- .env\n",
"- .env.example\n",
"- agent.ipynb\n",
"- CLAUDE.md\n",
"- hello.py (刚刚创建的)\n",
"\n",
"**目录:**\n",
"- .ipynb_checkpoints\n",
"- .pi\n",
"- openspec\n",
"- test\n",
"- work\n",
"\n",
"hello.py 文件已经成功创建并出现在目录列表中。\n",
"\n"
]
},
{
"data": {
"text/plain": [
"'\\n现在可以看到当前目录包含以下文件和目录:\\n\\n**文件:**\\n- .env\\n- .env.example\\n- agent.ipynb\\n- CLAUDE.md\\n- hello.py (刚刚创建的)\\n\\n**目录:**\\n- .ipynb_checkpoints\\n- .pi\\n- openspec\\n- test\\n- work\\n\\nhello.py 文件已经成功创建并出现在目录列表中。'"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"agent.chat(\"列出当前目录的所有文件\")"
]
},
{
"cell_type": "markdown",
"id": "bb18976d",
"metadata": {},
"source": [
"### 示例 4:异常处理\n",
"\n",
"故意让 Agent 读取一个不存在的文件,观察它如何处理错误。"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "d3133331",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"📝 用户: 读取文件 not_exist_xyz.py 的内容\n",
" 🔧 调用工具: read_file({\"path\": \"not_exist_xyz.py\"})\n",
" 📋 工具结果: {\"error\": \"[Errno 2] No such file or directory: 'not_exist_xyz.py'\"}\n",
"🤖 Agent: \n",
"文件 `not_exist_xyz.py` 不存在,系统返回了错误信息:`[Errno 2] No such file or directory: 'not_exist_xyz.py'`\n",
"\n",
"这个文件在当前目录中不存在。\n",
"\n"
]
},
{
"data": {
"text/plain": [
"\"\\n文件 `not_exist_xyz.py` 不存在,系统返回了错误信息:`[Errno 2] No such file or directory: 'not_exist_xyz.py'`\\n\\n这个文件在当前目录中不存在。\""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"agent.chat(\"读取文件 not_exist_xyz.py 的内容\")"
]
},
{
"cell_type": "markdown",
"id": "02851e31",
"metadata": {},
"source": [
"---\n",
"\n",
"## 你已经体验了 Agent 的核心能力!\n",
"\n",
"总结一下刚才发生了什么:\n",
"\n",
"| 示例 | Agent 做了什么 | 关键观察 |\n",
"|------|---------------|---------|\n",
"| 创建文件 | 调用 `edit_file`,`old_str` 为空 | 单次工具调用完成 |\n",
"| 修改文件 | **先** `read_file`,**再** `edit_file` | LLM 自主决定了两步! |\n",
"| 列出目录 | 调用 `list_files` | 返回结构化文件列表 |\n",
"| 异常处理 | `read_file` 失败 → 错误传回 LLM → 友好回复 | Agent 能优雅处理错误 |\n",
"\n",
"> 接下来,我们逐段拆解代码,看看这个「魔法」到底是怎么实现的。"
]
},
{
"cell_type": "markdown",
"id": "7564f300",
"metadata": {},
"source": [
"## Part 3:逐段拆解 — 魔法是怎么发生的\n",
"\n",
"刚才你看到 Agent 能自主创建文件、修改代码、处理错误。现在我们把代码**拆成一块一块**,理解每一部分在做什么。\n",
"\n",
"---\n",
"\n",
"### 3.1 配置模型\n",
"\n",
"这是整个 Agent 的「发动机」。任何支持 OpenAI 兼容接口的大模型都可以用。\n",
"\n",
"**用生活中的概念来理解:**\n",
"\n",
"| 概念 | 生活类比 | 代码中的体现 |\n",
"|------|---------|-------------|\n",
"| `api_key` | 门禁卡,证明你有权限使用服务 | `API_KEY` |\n",
"| `base_url` | 服务器地址,告诉程序去哪找模型 | `BASE_URL` |\n",
"| `model` | 具体用哪个模型 | `MODEL` |"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6adc1e7e",
"metadata": {},
"outputs": [],
"source": [
"# 创建 OpenAI 客户端(连接到你自己的服务商)\n",
"from openai import OpenAI\n",
"\n",
"client = OpenAI(\n",
" api_key=API_KEY, # 你的「门禁卡」\n",
" base_url=BASE_URL # 你的服务商地址\n",
")\n",
"\n",
"# 验证一下\n",
"r = client.chat.completions.create(\n",
" model=MODEL,\n",
" messages=[{\"role\": \"user\", \"content\": \"回复 OK\"}],\n",
" max_tokens=10\n",
")\n",
"print(f\"✅ 模型 {r.model} 连接正常\")\n",
"print(f\" 回复:{r.choices[0].message.content}\")"
]
},
{
"cell_type": "markdown",
"id": "4d75a31e",
"metadata": {},
"source": [
"### 3.2 定义工具 — Agent 的「手和眼睛」\n",
"\n",
"LLM 本身只是一个文本生成器,它**不能操作文件**。所谓「AI 编程助手」,其实是:LLM 告诉你它想做什么 → 你的代码帮它做 → 把结果告诉 LLM。\n",
"\n",
"这三个工具就是 Agent 的「手和眼睛」。\n",
"\n",
"#### 工具 1:`read_file` — 眼睛\n",
"\n",
"读取文件内容,让 LLM「看到」代码。"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "df432f63",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"文件路径:D:\\00_mywork\\15_agent_loop_cc\\hello.py\n",
"文件内容:\n",
"def add(a, b):\n",
" return a + b\n",
"\n",
"print('hello ,小帅')\n"
]
}
],
"source": [
"def read_file(path: str) -> dict:\n",
" \"\"\"读取文件的完整内容\"\"\"\n",
" from pathlib import Path\n",
" full_path = Path(path).expanduser().resolve()\n",
" content = full_path.read_text(encoding=\"utf-8\")\n",
" return {\"file_path\": str(full_path), \"content\": content}\n",
"\n",
"# 试一试\n",
"result = read_file(\"hello.py\")\n",
"print(f\"文件路径:{result['file_path']}\")\n",
"print(f\"文件内容:\\n{result['content']}\")"
]
},
{
"cell_type": "markdown",
"id": "e7c02de5",
"metadata": {},
"source": [
"#### 工具 2:`list_files` — 导航\n",
"\n",
"列出目录内容,让 LLM「浏览」项目结构。"
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "f2c4ac85",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" 📄 .env\n",
" 📄 .env.example\n",
" 📁 .ipynb_checkpoints\n",
" 📁 .pi\n",
" 📄 agent.ipynb\n",
" 📄 agent.py\n",
" 📄 build_notebook.py\n",
" 📄 cells_data.json\n",
" 📄 CLAUDE.md\n",
" 📄 hello.py\n",
" 📁 nul\n",
" 📁 openspec\n",
" 📄 prompt_his.md\n",
" 📄 README.md\n",
" 📄 requirements.txt\n",
" 📁 test\n",
" 📄 test_agent.py\n"
]
}
],
"source": [
"def list_files(path: str) -> dict:\n",
" \"\"\"列出目录中的文件和子目录\"\"\"\n",
" from pathlib import Path\n",
" full_path = Path(path).expanduser().resolve()\n",
" items = []\n",
" for item in sorted(full_path.iterdir()):\n",
" items.append({\n",
" \"filename\": item.name,\n",
" \"type\": \"file\" if item.is_file() else \"dir\"\n",
" })\n",
" return {\"path\": str(full_path), \"files\": items}\n",
"\n",
"# 试一试\n",
"result = list_files(\".\")\n",
"for f in result[\"files\"]:\n",
" print(f\" {'📄' if f['type']=='file' else '📁'} {f['filename']}\")"
]
},
{
"cell_type": "markdown",
"id": "39cb0b3d",
"metadata": {},
"source": [
"#### 工具 3:`edit_file` — 手\n",
"\n",
"最复杂的工具,有**两种模式**:\n",
"\n",
"| 条件 | 行为 | 使用场景 |\n",
"|------|------|---------|\n",
"| `old_str` 为空 `\"\"` | 创建/覆盖文件 | 新建文件 |\n",
"| `old_str` 非空 | 替换文件中首次出现的匹配文本 | 修改现有文件 |"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "70b38b75",
"metadata": {},
"outputs": [],
"source": [
"def edit_file(path: str, old_str: str, new_str: str) -> dict:\n",
" \"\"\"编辑文件:old_str为空则创建,非空则替换\"\"\"\n",
" from pathlib import Path\n",
" full_path = Path(path).expanduser().resolve()\n",
"\n",
" if old_str == \"\":\n",
" # 模式 1:创建新文件\n",
" full_path.write_text(new_str, encoding=\"utf-8\")\n",
" return {\"path\": str(full_path), \"action\": \"created_file\"}\n",
"\n",
" # 模式 2:替换文本\n",
" original = full_path.read_text(encoding=\"utf-8\")\n",
" if old_str not in original:\n",
" return {\"path\": str(full_path), \"action\": \"old_str not found\"}\n",
"\n",
" edited = original.replace(old_str, new_str, 1)\n",
" full_path.write_text(edited, encoding=\"utf-8\")\n",
" return {\"path\": str(full_path), \"action\": \"edited\"}\n",
"\n",
"# 试一试:模式 1 创建文件\n",
"result = edit_file(\"test_temp.txt\", \"\", \"这是测试内容\")\n",
"print(f\"创建文件:{result}\")\n",
"\n",
"# 试一试:模式 2 替换文本\n",
"result = edit_file(\"test_temp.txt\", \"测试\", \"演示\")\n",
"print(f\"替换文本:{result}\")"
]
},
{
"cell_type": "markdown",
"id": "97e332eb",
"metadata": {},
"source": [
"### 3.3 工具注册 — 告诉 LLM「你能用什么」\n",
"\n",
"现在有了三个工具函数,还需要**两样东西**把工具「介绍」给 LLM:\n",
"\n",
"1. **`TOOL_REGISTRY`**:Python 字典,名称 → 函数映射(供代码查找和执行)\n",
"2. **`TOOLS`**:JSON 数组,描述每个工具的名称、用途、参数(供 LLM 理解)\n",
"\n",
"`TOOLS` 是 LLM 的「菜单」,LLM 看了就知道有哪些工具可用、每个工具需要什么参数。"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ddad90e6",
"metadata": {},
"outputs": [],
"source": [
"# 工具注册表:名称 → 函数\n",
"TOOL_REGISTRY = {\n",
" \"read_file\": read_file,\n",
" \"list_files\": list_files,\n",
" \"edit_file\": edit_file,\n",
"}\n",
"\n",
"# 工具的 JSON Schema(LLM 的「菜单」)\n",
"TOOLS = [\n",
" {\n",
" \"type\": \"function\",\n",
" \"function\": {\n",
" \"name\": \"read_file\",\n",
" \"description\": \"读取文件的完整内容\",\n",
" \"parameters\": {\n",
" \"type\": \"object\",\n",
" \"properties\": {\"path\": {\"type\": \"string\"}},\n",
" \"required\": [\"path\"]\n",
" }\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"function\",\n",
" \"function\": {\n",
" \"name\": \"list_files\",\n",
" \"description\": \"列出目录中的文件和子目录\",\n",
" \"parameters\": {\n",
" \"type\": \"object\",\n",
" \"properties\": {\"path\": {\"type\": \"string\"}},\n",
" \"required\": [\"path\"]\n",
" }\n",
" }\n",
" },\n",
" {\n",
" \"type\": \"function\",\n",
" \"function\": {\n",
" \"name\": \"edit_file\",\n",
" \"description\": \"编辑文件:old_str为空则创建,非空则替换\",\n",
" \"parameters\": {\n",
" \"type\": \"object\",\n",
" \"properties\": {\n",
" \"path\": {\"type\": \"string\"},\n",
" \"old_str\": {\"type\": \"string\"},\n",
" \"new_str\": {\"type\": \"string\"}\n",
" },\n",
" \"required\": [\"path\", \"old_str\", \"new_str\"]\n",
" }\n",
" }\n",
" }\n",
"]\n",
"\n",
"print(\"✅ 工具注册完成!\")\n",
"print(f\" 已注册 {len(TOOLS)} 个工具:\", [t['function']['name'] for t in TOOLS])"
]
},
{
"cell_type": "markdown",
"id": "224b8051",
"metadata": {},
"source": [
"### 3.4 系统提示词 — 给 LLM 的「说明书」\n",
"\n",
"系统提示词是给 LLM 的角色设定和操作规则。它告诉 LLM:\n",
"\n",
"- **你是谁**:编程助手\n",
"- **你能用什么**:三个工具\n",
"- **怎么用**:先判断、再调用、有结果后继续\n",
"\n",
"系统提示词附加在对话历史的**最前面**,LLM 在整个对话中都会遵守这些规则。"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7146e6ff",
"metadata": {},
"outputs": [],
"source": [
"SYSTEM_PROMPT = \"\"\"你是一个编程助手智能体。你可以使用以下工具:\n",
"\n",
" • read_file:读取文件的完整内容\n",
" • list_files:列出目录中的文件和子目录\n",
" • edit_file:编辑文件(old_str为空则创建,非空则替换)\n",
"\n",
"使用规则:\n",
"1. 先判断是否需要工具\n",
"2. 需要时直接发起工具调用\n",
"3. 收到结果后继续推理或回复\n",
"4. 创建文件时 old_str 传空字符串\"\"\n",
"5. 修改文件前,先 read_file 了解当前内容\n",
"\"\"\"\n",
"\n",
"print(\"系统提示词:\")\n",
"print(SYSTEM_PROMPT)"
]
},
{
"cell_type": "markdown",
"id": "fdef6df9",
"metadata": {},
"source": [
"### 3.5 Agent Loop — 核心中的核心 ⭐\n",
"\n",
"这是整个智能体的「心脏」。理解了这个循环,就理解了所有 AI 编程助手的工作原理。\n",
"\n",
"```\n",
"用户输入:\"添加一个乘法函数\"\n",
" │\n",
" ▼\n",
"┌──────────────┐ ┌────────────────┐\n",
"│ 第 1 轮 │────▶│ read_file() │\n",
"│ LLM 推理 │ │ 返回文件内容 │\n",
"└──────┬───────┘ └───────┬────────┘\n",
" │ │\n",
" │ 结果送回 LLM │\n",
" ▼ │\n",
"┌──────────────┐ ┌──────▼─────────┐\n",
"│ 第 2 轮 │────▶│ edit_file() │\n",
"│ LLM 推理 │ │ 文件修改成功 │\n",
"└──────┬───────┘ └───────┬────────┘\n",
" │ │\n",
" │ 结果送回 LLM │\n",
" ▼ │\n",
"┌──────────────┐ │\n",
"│ 第 3 轮 │ 无 tool_calls\n",
"│ LLM 推理 │──────────────┘\n",
"└──────┬───────┘\n",
" │\n",
" ▼\n",
"\"乘法函数已添加完成!\" ← 内层循环结束\n",
"\n",
"回到外层循环,等待下一个用户输入\n",
"```\n",
"\n",
"**关键理解**:\n",
"- 每一轮 LLM 调用后,检查「是否还需要工具?」\n",
"- 如果需要 → 执行工具 → 结果送回 → 继续内层循环\n",
"- 如果不需要 → 输出回复 → 内层循环结束 → 等待用户下一条消息"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d47b8488",
"metadata": {},
"outputs": [],
"source": [
"class SimpleAgent:\n",
" \"\"\"最小 AI 编程智能体\"\"\"\n",
" \n",
" def __init__(self, api_key, base_url, model):\n",
" self.client = OpenAI(api_key=api_key, base_url=base_url)\n",
" self.model = model\n",
" # 对话历史:以系统提示词开头\n",
" self.conversation = [{\"role\": \"system\", \"content\": SYSTEM_PROMPT}]\n",
" \n",
" def chat(self, user_message):\n",
" \"\"\"处理一条用户消息,运行完整的 Agent Loop\"\"\"\n",
" self.conversation.append({\"role\": \"user\", \"content\": user_message})\n",
" \n",
" while True: # ← 内层循环:LLM 推理 → 工具执行 → 结果回传\n",
" response = self.client.chat.completions.create(\n",
" model=self.model,\n",
" messages=self.conversation,\n",
" tools=TOOLS,\n",
" tool_choice=\"auto\",\n",
" )\n",
" msg = response.choices[0].message\n",
" \n",
" # ── 关键判断:LLM 要调用工具吗? ──\n",
" if not msg.tool_calls:\n",
" # 不需要工具 → 直接回复用户 → 结束内层循环\n",
" self.conversation.append({\"role\": \"assistant\", \"content\": msg.content})\n",
" return msg.content\n",
" \n",
" # 需要工具 → 追加 assistant 消息(含 tool_calls)\n",
" self.conversation.append({\n",
" \"role\": \"assistant\",\n",
" \"content\": msg.content,\n",
" \"tool_calls\": [{\n",
" \"id\": tc.id, \"type\": \"function\",\n",
" \"function\": {\"name\": tc.function.name, \"arguments\": tc.function.arguments}\n",
" } for tc in msg.tool_calls]\n",
" })\n",
" \n",
" # 执行每个工具\n",
" for tc in msg.tool_calls:\n",
" tool_name = tc.function.name\n",
" tool_args = json.loads(tc.function.arguments)\n",
" tool_fn = TOOL_REGISTRY.get(tool_name)\n",
" \n",
" try:\n",
" result = tool_fn(**tool_args)\n",
" except Exception as e:\n",
" result = {\"error\": str(e)}\n",
" \n",
" # 结果追加为 tool 角色消息(含 tool_call_id 匹配)\n",
" self.conversation.append({\n",
" \"role\": \"tool\",\n",
" \"tool_call_id\": tc.id,\n",
" \"content\": json.dumps(result, ensure_ascii=False)\n",
" })\n",
" # 循环继续,让 LLM 处理工具结果\n",
"\n",
"print(\"✅ SimpleAgent 类已定义\")\n",
"print(\" 核心就一个 chat() 方法 + 一个 while True 内层循环\")"
]
},
{
"cell_type": "markdown",
"id": "9d7fef7e",
"metadata": {},
"source": [
"### Part 3 小结\n",
"\n",
"恭喜!你已经理解了 Agent Loop 的全部组成部分:\n",
"\n",
"| 组件 | 作用 | 代码量 |\n",
"|------|------|--------|\n",
"| 模型配置 | 连接 LLM(发动机) | ~5 行 |\n",
"| 三个工具 | Agent 的「手和眼睛」 | ~30 行 |\n",
"| 工具注册 | 告诉 LLM 能做什么(菜单) | ~40 行 |\n",
"| 系统提示词 | LLM 的角色说明书 | ~10 行 |\n",
"| **Agent Loop** | **核心循环:推理→执行→回传** | **~30 行** |\n",
"\n",
"**核心公式:**\n",
"> LLM 决定要什么工具 → 代码执行 → 结果送回 → 继续循环 → 直到 LLM 不再要工具"
]
},
{
"cell_type": "markdown",
"id": "6917be86",
"metadata": {},
"source": [
"---\n",
"\n",
"## Part 4:🎉 自由探索\n",
"\n",
"现在你已经理解了原理——试试你自己的任务吧!\n",
"\n",
"Agent 保留了之前的对话上下文(还记得 hello.py),你可以继续操作,也可以做全新的任务。"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "78f18286",
"metadata": {},
"outputs": [],
"source": [
"# 🎉 自由探索模式\n",
"# 输入任何编程任务,观察 Agent 的工作过程\n",
"# 输入 'exit' 退出\n",
"\n",
"while True:\n",
" task = input(\"\\n👉 你的任务(输入 exit 退出): \").strip()\n",
" if task.lower() == \"exit\" or task == \"\":\n",
" break\n",
" agent.chat(task)\n",
"\n",
"print(\"👋 探索结束!翻到下一个 Cell 查看总结。\")"
]
},
{
"cell_type": "markdown",
"id": "de775269",
"metadata": {},
"source": [
"## 📝 总结:你学到了什么\n",
"\n",
"### Agent Loop = 一个循环\n",
"\n",
"```python\n",
"while True: # 对每条用户消息\n",
" response = LLM(messages, tools) # 调用 LLM\n",
" if 没有 tool_calls: # 不需要工具?\n",
" print(response) # 直接回复\n",
" break # 等下一句\n",
" 执行所有工具调用() # 需要工具 → 执行\n",
" 结果追加到 messages # 结果送回去\n",
" # 再问一次 LLM\n",
"```\n",
"\n",
"### 为什么这个模式如此强大?\n",
"\n",
"1. **LLM 自主决策**:代码没有写死「修改前先读文件」,LLM 自己决定的\n",
"2. **工具可扩展**:加新工具只需定义函数 + 注册,LLM 自动学会使用\n",
"3. **错误自恢复**:工具执行失败 → 错误回传 → LLM 调整策略\n",
"4. **上下文连续**:对话历史累积,LLM 记住之前的所有操作\n",
"\n",
"### 这 150 行代码 = Claude / Cursor / Copilot 的核心\n",
"\n",
"生产级 AI 编程助手多出来的:\n",
"- 更多工具(bash、grep、web search...)\n",
"- 更好的错误处理(模糊匹配、自动重试...)\n",
"- 流式输出、UI 界面...\n",
"- 上下文管理(长对话的裁剪和摘要...)\n",
"\n",
"但 **核心循环一模一样**。\n",
"\n",
"### 延伸学习\n",
"\n",
"- 📄 [原文: The Emperor Has No Clothes](https://www.mihaileric.com/The-Emperor-Has-No-Clothes/)\n",
"- 🧪 [GitHub: 完整源码(~200行)](https://shorturl.at/HmMeI)\n",
"- 🔧 练习:试试给 Agent 添加一个新工具(比如 `grep` 搜索代码)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.7"
}
},
"nbformat": 4,
"nbformat_minor": 5
}