Agent on Tech In Sight

手写一个 AI Agent：从零理解它的原理和本质

Sun, 24 May 2026 17:00:00 +0800

手写一个 AI Agent：从零理解它的原理和本质

用 300 行代码，让你看穿所有 Agent 框架的底牌

一、Agent 到底是什么？

这两年 AI 圈最火的概念之一就是 Agent。LangChain、LangGraph、AutoGen、CrewAI……框架层出不穷，但如果你扒开这些框架的外衣，会发现最核心的东西只有一句话：

Agent = LLM + 工具 + 循环

把这句话拆开：

LLM：大脑，负责推理和决策
工具：手脚，让 LLM 能影响外部世界（执行命令、查数据库、发请求）
循环：把上面两个串起来：思考 → 行动 → 观察结果 → 继续思考

这就是 ReAct (Reasoning + Acting) 模式，所有 Agent 框架的最底层原语。

本文不教你用框架，而是带你从零手写一个 Agent，让你亲眼看到每一轮对话里 LLM 是怎么思考的、Agent 是怎么解析的、工具是怎么被调用的。

二、核心流程：ReAct 循环

我们先不看代码，先理解这个循环长什么样。

你: "我的机器有几个 CPU 核心？"
                  │
                  ▼
LLM（收到问题，开始推理）:
  "用户想知道 CPU 核心数 -> 用 nproc 命令"
                  │
                  ▼
Agent（解析 LLM 输出 → 发现 Action）:
  执行: nproc
                  │
                  ▼
命令行返回: "8"
                  │
                  ▼
LLM（看到结果，继续推理）:
  "8 个核心 -> 可以回答了"
                  │
                  ▼
你收到: "你的机器有 8 个 CPU 核心 ✅"

关键是：LLM 不是一次输出就完事，它在"思考→行动→观察→再思考"这个圈里转，直到它能给出最终答案。

这个圈，就是 Agent 的全部秘密。

三、动手写一个：逐行解析

我们的实现分四个模块：

3.1 LLM 客户端

最外层是调用大模型的接口。DeepSeek 兼容 OpenAI 协议，所以我们直接用 openai SDK：

class LLMClient:
    def __init__(self):
        load_dotenv()
        self.client = OpenAI(
            api_key=os.getenv("DEEPSEEK_API_KEY"),
            base_url=os.getenv("DEEPSEEK_BASE_URL"),
        )

    def chat(self, messages) -> str:
        response = self.client.chat.completions.create(
            model="deepseek-v4-flash",
            messages=messages,
            temperature=0.0,
        )
        return response.choices[0].message.content or ""

这段代码没什么神秘的——就是一个 API 封装。关键在后面。

3.2 CLI 执行器

Agent 需要"手脚"来做事。我们给它一个能安全执行 CLI 命令的工具：

class CLIExecutor:
    DANGEROUS_PATTERNS = [
        r"\bsudo\b", r"\bmkfs\b", r"\brm\s+-rf\s+/$", ...
    ]

    def run(self, command: str) -> str:
        # 1. 安全检查：拒绝危险命令
        for pattern in self.DANGEROUS_PATTERNS:
            if re.search(pattern, command, re.IGNORECASE):
                return f"[Safety Error] 危险命令被拦截"

        # 2. 执行命令（带超时）
        result = subprocess.run(
            command, shell=True,
            capture_output=True, text=True,
            timeout=30,
        )

        # 3. 处理输出（截断、报错）
        output = result.stdout + result.stderr
        if result.returncode != 0:
            output = f"[Exit code: {result.returncode}]\n{output}"
        return output[:3000]

这里有个要点：工具返回的结果会被送回给 LLM，让它"看到"自己行动的结果。

3.3 协议：LLM 怎么告诉 Agent 要干什么？

这是最精妙的部分。LLM 是一个文本输入/文本输出的模型，Agent 要让它"执行命令"，需要一个约定的格式。

我们在 System Prompt 里告诉 LLM：

可用工具:
- run_command: 执行 shell 命令

输出格式（二选一）:

=== 要执行命令 ===
Thought: <你的推理>
Action: run_command
Action Input: <命令>

=== 要给出答案 ===
Final Answer: <你的回答>

Agent 收到 LLM 的输出后，用正则表达式解析：

def parse_response(response: str) -> dict:
    # 是 Final Answer 吗？
    if re.search(r"Final Answer:\s*(.*)", response, re.DOTALL):
        return {"type": "final", "content": "..."}

    # 是 Action 吗？
    if re.search(r"Action:\s*run_command\s*Action Input:\s*(.*)", response):
        return {"type": "action", "command": "..."}

    # 都不是 → 还在思考
    return {"type": "thought", "content": "..."}

这就是 Agent 的核心协议——双方约定好一套文本格式，LLM 输出 Action，Agent 解析后执行，然后把结果喂回去。

所有 Agent 框架（LangChain、AutoGen、OpenAI Function Calling）都是在给这套"文本协议"加语法糖。

3.4 ReAct 循环（核心中的核心）

把上面三块串起来：

def run_agent(user_input: str):
    llm = LLMClient()
    executor = CLIExecutor()

    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_input},
    ]

    for turn in range(1, 11):  # 最多 10 轮
        # 1. 调 LLM
        response = llm.chat(messages)
        parsed = parse_response(response)

        # 2. 根据解析结果做不同的事
        if parsed["type"] == "final":
            print(parsed["content"])
            return

        if parsed["type"] == "action":
            observation = executor.run(parsed["command"])
            # 把"思考"和"观察结果"都追加到消息历史
            messages.append({"role": "assistant", "content": response})
            messages.append({"role": "user", "content": observation})
            # 继续下一轮循环

        if parsed["type"] == "thought":
            # 还没给出明确指令，推它一把
            messages.append({"role": "user", "content": "请给出 Action 或 Final Answer。"})

这个循环就是 Agent 的全部。用流程图看更清楚：

用户输入
    │
    ▼
┌─────────────────────────────┐
│  给 LLM 发送消息历史          │
│  (system + 之前的对话)        │
└──────────┬──────────────────┘
           │
           ▼
┌─────────────────────────────┐
│  LLM 返回文本                 │
│  "Thought... Action: xxx"    │
└──────────┬──────────────────┘
           │
    ┌──────┴──────┐
    ▼              ▼
 Final?         Action?
    │              │
    ▼              ▼
 输出答案     执行命令 → 拿到结果
                             │
                  ┌──────────┘
                  ▼
            追加到消息历史
                  │
                  ▼
            回到 LLM（继续循环）

四、Skill 系统：让 Agent 拥有"专业技能"

基础的 ReAct 循环有了，但 LLM 只知道"执行 CLI 命令"这一种能力。如果想让 Agent 能做更专业的事（比如代码审查、技术写作、调试），怎么办？

答案是 Skill（技能）系统。

思路很简单：每个 Skill 是一段 prompt 模板，描述了特定的专业能力。Agent 启动时把所有 skill 的名称和描述列在 system prompt 里，LLM 在推理过程中如果发现需要某个技能，就通过 load_skill action 加载它。

Skill 文件

---
name: code-review
description: 审查代码质量，检查 bug、安全漏洞和代码风格
---

你是一个资深代码审查专家。请从以下维度审查用户提供的代码：
1. 逻辑正确性
2. 安全漏洞
3. 代码风格
4. 性能问题

加载流程

User: "帮我审查这段代码"
                      │
                      ▼
LLM（看到 system prompt 里的 skill 列表）:
  "这需要 code-review skill"
  Action: load_skill
  Action Input: code-review
                      │
                      ▼
Agent（加载 skill.md 文件）:
  把 skill 的 prompt 追加为 system message
                      │
                      ▼
LLM（现在拥有了审查专家的指令）:
  开始按 skill 要求工作
  Action: run_command
  Action Input: cat file.py
  ...

关键要点：

只把 skill 的"名称+描述"放进 system prompt（节省 token）
完整 prompt 只在被调用时才加载
不额外调用 LLM（匹配发生在 LLM 的正常推理过程中）

这和 MCP（Model Context Protocol）的设计哲学相似：工具/技能的描述轻量挂载，按需加载。

五、Agent 的"协议"本质

回看整个过程，你会发现一个规律：

所谓的 Agent，本质上是把 LLM 的"对话接口"扩展成了"指令接口"

普通对话：用户问 → LLM 答
Agent：用户问 → LLM 思考 → LLM 发出指令 → Agent 执行指令 → 结果喂回 → LLM 继续

这套"指令协议"是手工约定的（正则解析），到了 OpenAI Function Calling 和 Anthropic Tool Use 层面，它被标准化了——但本质没变。

你完全可以自己定义协议：

// 不用 Action/Final Answer，用 XML
<tool_call>
  <name>search_web</name>
  <args>{"q": "weather in Beijing"}</args>
</tool_call>

// 或者用 JSON
{"tool": "search_web", "params": {"q": "weather"}}

// 或者用任意你喜欢的格式
→ SEARCH: weather in Beijing ←

协议只是形式，循环才是灵魂。

六、从手写到框架

理解了这 300 行代码的顺序，你就理解了所有 Agent 框架：

框架	等价于我们做的
LangChain	AgentExecutor + Tool abstractions
LangGraph	State machine 化的 ReAct 循环
OpenAI Assistants	托管版的 ReAct + 工具管理
AutoGen / CrewAI	多 Agent + 消息路由
MCP	标准化工具发现和调用协议

框架解决的是工程问题（并发、持久化、多 Agent 编排、错误恢复），但核心逻辑和我们这 300 行代码一模一样。

七、试试看

你可以在这个仓库里看到完整代码，跟着步骤运行：

# 1. 配置 API Key
cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

# 2. 安装依赖
uv sync

# 3. 运行
uv run python agent.py

然后试试这些话：

whoami — 最简单的 ReAct 测试
我有哪些 Python 文件？ — LLM 会调用 find 或 ls
帮我审查一下 agent.py 的代码质量 — 加载 code-review skill 再审查
看下系统有多少内存 — 会用 free 或 cat /proc/meminfo

每一轮对话你都会看到：

Agent 发送给 LLM 的完整消息列表（上下文怎么积累的）
LLM 的原始输出（它怎么思考的）
解析结果（Agent 从文本中提取了什么）
命令执行输出（工具调用的结果）

看完这些日志，你对 Agent 就再也不会有"魔法感"了。

八、写在最后

AI Agent 不是一个产品，而是一种计算模式。

把 LLM 从"对话机器人"变成"自主执行者"，只需要一个循环 + 一个协议。框架会帮你管理复杂度，但不要被框架迷惑——回到原点，它就是一个 while 循环加几个 if 判断。

如果你看懂了这里的 300 行代码，下次再听到"Agent"这个词，你脑海里浮现的不再是某个框架的黑盒，而是一个清晰的循环：

LLM 说：我要做 X
Agent 做 X
LLM 看到结果，说：那我该做 Y 了

就这么简单。

AI 辅助编程的三次范式跃迁：从代码补全到 Agent 工程自治

Sun, 01 Dec 2024 10:00:00 +0800

AI 辅助编程的三次范式跃迁：从代码补全到 Agent 工程自治

近三年，AI 辅助编程技术完成了跨越式迭代，彻底重构了软件开发的工作范式。从最初简单的代码片段补全，到人机对话协同开发，再到如今 AI 自主完成全流程工程任务，整个行业经历了三次清晰且不可逆的范式转移。

很多开发者的直观感受高度统一：2024 年是 AI 编程全民普及的元年。在此之前，AI 编程仅为小众工具能力；在此之后，AI 从辅助工具逐步进化为工程协作主体。本文将以严谨的行业时间线、技术特征与产品迭代为依据，完整梳理 AI 辅助编程的三代演进脉络，清晰拆解每一轮范式升级的核心逻辑与能力边界。

第一阶段：行内代码补全时代（2022 下半年 — 2024 上半年）

时代背景

2021 年，OpenAI 发布 Codex 模型与相关技术原型，首次验证了大模型代码生成的可行性，但该阶段仅停留在实验室研究与极客内测阶段，无规模化商用能力，并未走入大众开发者视野。

真正的行业起点为 2022 年 6 月 GitHub Copilot 正式商用上线，这标志着大模型驱动的 AI 编程工具正式落地产业。2023 年至 2024 上半年，代码补全工具逐步渗透主流开发场景，成为开发者标配辅助工具，开启了 AI 辅助编程的第一个正式时代。

核心范式特征

本阶段的核心定位是被动式代码辅助，AI 的核心价值是“替开发者节省打字时间”，整体交互模式与技术能力具备极强的局限性。

交互形态：依托 IDE 编辑器内置能力，以“幽灵文本”的形式实时展示单行、短代码片段补全建议，无主动交互入口
触发逻辑：完全被动触发，仅根据当前编辑文件、相邻代码上下文生成内容，依赖开发者手动判断、接受或拒绝建议
能力边界：仅擅长单函数、短片段代码生成，不支持跨文件理解、逻辑重构、问题解释，无复杂推理能力
人机关系：AI 是“键盘后的辅助写手”，开发者主导所有逻辑设计与代码编写，AI 仅承担机械录入工作

标志性产品与底层能力

本阶段主流产品均以代码补全为核心能力，包括 GitHub Copilot、Amazon CodeWhisperer、早期版本 Cursor、Roo Code、TabNine 等。

底层依托初代 Codex、GPT-3 衍生模型，模型上下文窗口较小，指令遵循能力弱，仅能适配简单、碎片化的代码生成场景，无法支撑完整的工程任务。

第二阶段：对话式编程协作时代（2024 上半年 — 2024 年底）

时代背景

2024 年是 AI 编程的全民普及拐点。随着 GPT-4、Claude 3.5 Sonnet 等高精度大模型成熟，长上下文理解、复杂指令遵循、多文件关联分析能力大幅提升，彻底打破了初代代码补全工具的能力瓶颈。

主流 IDE 厂商快速跟进，全线内置 AI 对话功能，独立 AI 编程工具完成能力升级，对话式人机协作模式正式取代传统补全，成为行业主流，这也是绝大多数开发者深度接触 AI 编程的开端。

核心范式特征

本阶段的核心升级是从“单向补全”变为“双向协作”，AI 从机械工具升级为开发者的结对协作伙伴。

交互形态：以 IDE 侧边栏、独立对话窗口为核心载体，支持完整的多轮对话、问题追问、需求细化
能力拓展：不再局限于代码补全，可实现代码解释、逻辑重构、bug 修复、单元测试生成、代码优化等全场景辅助能力
落地方式：对话生成的代码可一键插入编辑器、局部替换或增量修改，大幅降低代码落地成本
人机关系：开发者负责定义需求、把控架构与核心逻辑，AI 负责落地细节、优化代码、解决常规问题，形成高效结对编程模式

标志性产品与底层能力

本阶段代表性产品包括 GitHub Copilot Chat、JetBrains AI Assistant、Amazon Q Developer、Cursor Composer 等 IDE 原生对话工具，同时 ChatGPT、Claude 等通用大模型也成为开发者高频使用的编程辅助渠道。

底层模型具备超长上下文、强指令理解与基础逻辑推理能力，支持单项目多文件关联分析，可完成中等复杂度的编程任务，但仍依赖开发者拆分任务、把控流程，无法自主完成全链路工程落地。

第三阶段：CLI 与 Agent 工程自治时代（2024 年底 — 至今）

时代背景

2024 年末开始，AI 编程正式迈入前沿范式阶段。随着大模型工具调用、长链规划、自主纠错能力的成熟，AI 不再局限于 IDE 界面内的被动协作，开始具备独立工程执行能力。

行业逐步兴起 Harness Engineering（驾驭式工程） 与 Vibe Coding（自然语言全项目生成） 理念，标志着人机开发关系再次重构，AI 正式从“协作伙伴”升级为“自主工程执行者”，目前该模式仍处于快速迭代、逐步普及的阶段。

核心范式特征

本阶段的核心变革是从“人机对话协作”变为“AI 自主工程自治”，交互载体与工作逻辑发生根本性颠覆。

交互迁移：核心操作界面从传统 IDE 编辑器、侧边栏，回归终端（CLI），AI 直接对接本地工程环境
全权限执行：AI 可自主完成文件读写、代码修改、命令执行、测试运行、Git 版本管理、依赖安装等全流程工程操作
Agent 核心能力：具备自主任务拆解、分步规划、工具调用、运行校验、错误回滚、自我迭代的完整闭环能力，无需开发者逐步骤指导
人机关系重构：开发者不再聚焦具体代码编写，核心工作变为定义项目目标、制定规范、把控工程质量、驾驭 AI 执行流程，实现“目标驱动、AI 落地”

标志性产品与底层能力

本阶段主流工具均为 Agent 终端编程工具，代表性产品包括 Claude Code、OpenAI Codex CLI、Gemini CLI、Cursor Agent 模式，以及 aider、open-interpreter 等优质社区开源项目。

底层依托新一代高阶大模型，具备超长代码库上下文承载能力、强逻辑推理、结构化输出、多工具联动与故障自愈能力，首次让“自然语言定义需求、AI 独立完成全项目开发”的工程模式具备落地可行性。

三代演进核心总结：看似倒退，实则是能力的极致进化

复盘 AI 辅助编程的完整演进路径，三次范式跃迁的本质清晰可见：AI 从“键盘后面的文字幽灵”，迭代为“并肩协作的结对程序员”，最终进化为“可被驾驭的自主工程执行体”。

从界面形态来看，演进路径是「IDE 行内补全 → IDE 侧边对话 → 终端 CLI 指令」，看似是交互界面的简化与“后退”，实则是 AI 能力质变的必然结果：早期 AI 能力不足，需要依托编辑器辅助约束；如今 AI 具备独立工程决策与执行能力，无需依赖 IDE 界面束缚，可直接对接底层工程环境，实现最高效的开发闭环。

站在开发者视角，工作模式也完成了彻底升级：从最初的**“逐行码字、AI 补全”，到“提出需求、AI 协作”，再到如今的“定义目标、AI 自治”**。这不仅是工具的迭代，更是整个软件开发行业生产方式的颠覆性变革。