Agent 学习阶段记录 · 9 月 17 日完整篇

完整学习档案：保留原有章节、代码、失败示例、排错过程和练习。代码反映记录时的环境，不代表每段都是最终版本，也不代表本次发布重新运行了全部示例。请在练习项目中使用自己的环境配置，勿填入生产密钥。

本页是 2026-09-17 的阶段记录，最后部分为学习计划，不计入完成。天气数值仅为原记录的示例，不提供实时天气查询。

一、你已经学完了哪些内容

你已经不是停留在“会调用一个大模型 API”的阶段了，现在已经自己搭出了一个完整的小型 Agent Runtime。

1. Python / FastAPI / 数据库基础已经完成

   你已经掌握了 Agent 开发真正需要的 Python 基础，包括变量、list/dict、函数、异常、类、模块、venv、文件、JSON、环境变量、HTTP、requests、异步基础等。

   FastAPI 方面已经会：

   GET / POST
   Path / Query / Body
   Pydantic
   422
   HTTPException
   Swagger
   Uvicorn

   数据库方面已经能用：

   Python
   ↓
   PyMySQL
   ↓
   MySQL

   并且已经实现：

   conversations
   messages

   的持久化聊天记录。

2. LLM 多轮对话和 Memory 已经完成

   你已经真正理解：

   模型本身无状态

   所谓“记得前面说过的话”，其实是应用程序：

   MySQL读取历史
   ↓
   拼成messages
   ↓
   再发送给LLM

   你也已经区分：

   Chat History
   ≠
   Long-term Memory

   目前你实现的是 Chat History 持久化，真正的长期记忆还没正式做。

3. Agent 核心原理已经完成

   你已经真正理解 Agent 不是：

   LLM + 一个提示词

   而是：

   LLM
   +
   Tools
   +
   Memory
   +
   Agent Loop

   以及：

   Reason
   ↓
   Act
   ↓
   Observe
   ↓
   Reason

   这个循环。

4. Tool Calling 已经完整走通

   从最开始：

   LLM选择工具

   到：

   Tool Schema
   Tool Call
   JSON arguments
   Python执行函数
   Tool Result
   再交回LLM
   Final Answer

   你已经全部亲手实现。

   现在你的 Agent 能自己完成：

   查上海天气
   ↓
   得到27°C
   ↓
   调calculator
   ↓
   27 × 2
   ↓
   最终回答

   这已经是真正的 Multi-Step Agent。

5. Tool Registry / Input / Output Contract 已经完成

   你已经有：

   tool_registry
   tool_argument_models
   tool_output_models
   tool_schemas

   并理解四者的区别。

   当前 Tool 流程已经是：

   LLM arguments
   ↓
   Pydantic Input Validation
   ↓
   Python Tool
   ↓
   Output Validation
   ↓
   Structured Result
   ↓
   JSON
   ↓
   LLM

   这一步很重要，因为很多初级 Agent 教程根本不会做到这么完整。

6. Agent 安全和错误处理已经学了相当一部分

   你已经学过：

   Prompt Injection
   Tool Permission
   Human-in-the-loop
   Least Privilege
   Input Validation
   Output Validation
   max_steps
   timeout
   retry
   backoff

   还实现了统一 Tool Result：

   {
       "success": True,
       "data": {...},
       "error": None
   }

   或：

   {
       "success": False,
       "data": None,
       "error": {
           "type": "...",
           "message": "..."
       }
   }

7. Custom Exception 已经完成

   你现在已经能够区分：

   ToolTimeoutError
   ToolConnectionError
   ToolBusinessError
   execution_error
   input_validation_error
   output_validation_error

   而不是所有问题都粗暴变成：

   execution_error

8. Observability / Agent Trace 已经进入工程化阶段

   你已经实现：

   step
   tool_name
   success
   error_type
   duration_ms
   run_id

   现在你可以看到：

   Weather → 2500ms
   Calculator → 0.01ms

   也已经理解：

   conversation_id
   → 一整个聊天
   
   run_id
   → 一次Agent执行
   
   tool_call_id
   → 一次具体Tool调用

9. Logging 已经基本完成

   你已经从：

   print()

   发展到了：

   Logger
   Handler
   StreamHandler
   RotatingFileHandler
   DEBUG
   INFO
   WARNING
   ERROR
   Log Rotation
   propagate

   并且现在实现了：

   Terminal
   → DEBUG及以上
   
   agent.log
   → INFO及以上

   还实现了：

   agent.log
   agent.log.1
   agent.log.2
   agent.log.3

   这种日志滚动机制。

二、你现在正学到哪里

现在准确处于：

第 72 课：Logging 模块化

目标是把：

agent.py

里面几十行日志配置拿出去，变成：

logging_config.py

形成：

config.py
→ 模型 / DB配置

logging_config.py
→ 日志配置

tools.py
→ Tool

agent.py
→ Agent Runtime

memory.py
→ Chat Memory

db.py
→ 数据库

main.py
→ FastAPI入口

这一步的核心不是 Logging 本身。

而是开始学：

软件工程中的职责分离、封装和重构。

你的项目现在已经开始从：

“学习代码”

进入：

“真正的小型工程”

三、接下来还剩哪些重要内容

接下来我建议不要急着上 LangChain，而是继续沿着现在这个底层 Agent 把关键能力补齐。

接下来的路线大致是：

你现在
↓
72. Logging模块化
↓
73. Agent Run结构化Trace
↓
74. Trace持久化到数据库
↓
75. Tool执行器进一步重构
↓
76. 权限 + HITL真正落地
↓
77. 更真实的工具
↓
78. Long-term Memory
↓
79. RAG
↓
80. Streaming
↓
81. Auth / 用户隔离
↓
82. 测试
↓
83. 并发 / async
↓
84. 数据库连接池
↓
85. Docker
↓
86. Linux
↓
87. 云服务器部署
↓
88. 生产级Agent整体架构

其中几个真正的大模块，我帮你解释一下。

1. Agent Trace 持久化

你现在日志只是：

agent.log

以后我们会设计：

agent_runs
tool_calls

数据库表。

最终可以查询：

某个run_id
↓
执行了几个Step
↓
调用了哪些Tool
↓
各用了多久
↓
哪些失败
↓
Retry了多少次

2. Tool Runtime 再重构

你现在 agent.py 已经有很多：

Input Validation
Tool Execution
Exception
Output Validation
Tool Result
Logging

代码。

后面我们会发现：

run_agent() 又开始太胖了。

于是会进一步抽成类似：

execute_tool(...)

形成：

Agent负责：
决定什么时候调用工具

Tool Executor负责：
验证
执行
错误处理
耗时
输出验证
日志

这个会让你理解真正的 Runtime / Executor 是什么。

3. Human-in-the-loop 真正实现

之前你已经理解概念：

读取天气
→ 可以自动执行

删除文件
发送邮件
转账
修改数据库
→ 需要确认

但现在只是理论。

后面我们会真正实现：

LLM提出Tool Call
↓
Python检查Permission
↓
高风险
↓
pending_confirmation
↓
用户确认
↓
才执行

这会是 Agent 安全中很重要的一块。

4. Long-term Memory

你现在：

MySQL messages

属于 Chat History。

以后会真正做：

用户说：
“以后回答我Python的时候一步一步讲”

↓
Memory Extraction

↓
保存为长期偏好

↓
未来新Conversation也能调用

这里会涉及：

Memory提取
Memory写入
Memory检索
Memory更新
Memory冲突
Memory过期

5. RAG

这是后面最大的一个模块。

流程会是：

PDF / 文档
↓
解析
↓
Chunk
↓
Embedding
↓
Vector Database
↓
用户问题
↓
Retrieval
↓
找到相关Chunk
↓
放进Context
↓
LLM回答

到时候你会理解：

Memory
RAG
Tool
Database
Prompt

到底分别负责什么。

6. 并发和 Async

你之前已经非常准确地理解：

LLM一次返回两个tool_calls
≠
Python真的并行执行

目前：

for tool_call in message.tool_calls:

还是：

上海天气
↓
执行完
↓
北京天气

后面会真正做：

上海天气 ─┐
          ├→ 同时执行
北京天气 ─┘

这时才会正式用到：

async
await
asyncio.gather()

7. 测试

你现在主要靠：

运行脚本
看输出

后面需要：

Unit Test
Integration Test
Tool Test
Agent Test
Mock

例如自动验证：

calculator 10×2
一定是20

10÷0
一定返回execution_error

非法Tool
一定不会执行

Output Validation失败
一定被拦截

Agent 才会越来越稳定。

8. 最后的部署

最后才进入：

requirements.txt
环境变量
Linux
Docker
端口
进程
云服务器
HTTPS
Nginx
日志
数据库
服务启动

最终把你现在这个：

agent-demo/

真正变成：

互联网可以访问的 Agent API

四、我们暂时还不急着学什么

现在我仍然不建议你马上深入：

LangChain
LangGraph
LlamaIndex
MCP复杂生态
多Agent框架

原因是你现在正在建立非常重要的底层认知。

等你把：

Tool
Agent Loop
Runtime
Memory
RAG
Trace
Permission
Retry
Deployment

这些自己实现一遍以后，再看 LangChain / LangGraph，会产生完全不同的感觉。

到时候你看到：

ToolNode
State
Graph
Checkpoint
Memory

不会觉得：

“这是一个神奇框架。”

而会觉得：

“哦，它只是把我自己写过的这些东西封装起来了。”

这个阶段再上框架最合适。

五、你目前最核心的进度图

可以把你现在的位置记成：

Python基础                    ✅
      ↓
HTTP / API                    ✅
      ↓
FastAPI                       ✅
      ↓
MySQL                         ✅
      ↓
Chat History                  ✅
      ↓
LLM调用                       ✅
      ↓
Tool Calling                  ✅
      ↓
Agent Loop                    ✅
      ↓
Multi Tool                    ✅
      ↓
Tool Registry                 ✅
      ↓
Input Validation              ✅
      ↓
Output Validation             ✅
      ↓
Structured Result             ✅
      ↓
Error Handling                ✅
      ↓
Retry / Timeout / Backoff     ✅
      ↓
Custom Exception              ✅
      ↓
Observability                 ✅
      ↓
run_id / Trace Context        ✅
      ↓
Logging                       ✅
      ↓
Logging模块化                 ← 你现在在这里
      ↓
Agent Trace数据库
      ↓
Tool Runtime重构
      ↓
真正HITL / Permission
      ↓
Long-term Memory
      ↓
RAG
      ↓
Streaming
      ↓
Auth
      ↓
Testing
      ↓
Async / Concurrency
      ↓
Docker / Linux
      ↓
云端部署

所以你现在已经跨过了最容易混乱的 Agent 基础原理阶段。

接下来主要是在做：

“如何把一个 Agent 从 Demo 变成一个可靠的软件系统。”