从 0 实现一个 Agent

百科 · 学习路径 · Python · 不依赖 Agent 框架

这是百科里的动手路径，不是全部词条。先做出能聊天的机器人，再给它套上 Harness，然后才挂本地工具、MCP、Skill 和 RAG。

用户 → Harness（会话 / 循环 / 权限 / 轨迹）
  ├ 聊天（模型）
  ├ 工具（进程内行动）
  ├ MCP（进程外工具 / 资源）
  ├ Skill（专项流程）
  └ RAG（资料）

阶段一 · 聊天机器人

只会说话。先把 API、多轮、人设和流式输出做稳，作为后面所有能力的底板。

  1. 00

    Chatbot：对话底板

    只会说话、默认不行动。先把对话协议和边界讲清楚。

  2. 01

    Responses API

    另一套信封：input、output 条目。流式事件见 Responses SSE。后面的例子仍按 chat/completions。

  3. 02

    多轮对话

    把历史带上。为什么不能每次都开一个新聊天。

  4. 03

    System prompt

    人设、边界、输出习惯。后面 Skill 会按需覆盖或补充它。

  5. 04

    流式输出

    打字机效果，为 Harness 的事件流做准备。

  6. 05

    本阶段产物：CLI 聊天机器人

    一条命令能聊。还不会用工具，但会话是完整的。

    撰写中

阶段二 · Harness

给聊天套上运行时：会话托管、取消与超时、日志和轨迹。后面的循环、MCP、Skill、RAG 都注册进这个壳，而不是各写一套。

  1. 06

    什么是 Harness

    模型和 Harness 的分工。为什么「智能」很大一块其实在运行时。

    撰写中
  2. 07

    会话、取消、超时

    一次 run 的生命周期：开始、打断、结束、落盘。

    撰写中
  3. 08

    事件与轨迹

    把文本、工具、错误打成统一事件，给人和调试看。

    撰写中
  4. 09

    权限位先留好

    谁能读文件、谁能上网。工具章再接线，概念先放进 Harness。

    撰写中

阶段三 · 循环与工具

在 Harness 里先挂上进程内工具和 Agent Loop。MCP 下一阶段再接，避免一开始就把协议和循环缠在一起。

  1. 10

    从聊天到办事

    工具和聊天回复的差别。模型如何「伸手」。

  2. 11

    第一次 function calling

    工具清单、参数 Schema、解析 tool_calls。

  3. 12

    Agent Loop

    执行工具，把观察写回 messages，再请求。步数到顶就停。

  4. 13

    实用工具与安全

    读文件、HTTP、计算。白名单、超时、参数校验。

    撰写中
  5. 14

    失败与死循环

    工具报错、编造工具名、同一工具空转。重试和人工确认。

    撰写中

阶段四 · MCP

本地工具写在进程里；MCP 把工具、资源和提示放到另一个进程，用同一套协议给 Harness 调用。先当客户端接进去，再自己写一个最小 server。

  1. 15

    MCP 是什么

    和本地 function calling 的差别：进程外、可插拔、tools / resources / prompts。

    撰写中
  2. 16

    写一个最小 MCP Server

    stdio 起一个服务，暴露一两个 tool。先能被别人连上。

    撰写中
  3. 17

    Harness 当 MCP Client

    握手、列出工具、调用工具，合并进同一份清单和同一套 Loop。

    撰写中
  4. 18

    资源、提示与权限

    resources、prompts 怎么用。哪些 server 能连、工具能不能写。

    撰写中

阶段五 · Skill

Skill 不是新工具，也不是 MCP。它是按需加载的专项说明书（可附脚本）。Harness 负责发现、挑选、读入。

  1. 19

    Skill 是什么

    和 system prompt、本地工具、MCP、RAG 的边界。

    撰写中
  2. 20

    发现与加载

    SKILL.md 的名字和说明先给模型看，真正用到再读全文。

    撰写中
  3. 21

    写第一个 Skill

    例如「整理会议纪要」或「按仓库规范改代码」。让 Harness 在匹配时注入。

    撰写中
  4. 22

    Skill 里的脚本

    纯指令 vs 附带可执行步骤。脚本仍走工具或 MCP 通道。

    撰写中

阶段六 · RAG

让 Harness 能查你自己的材料。检索是一种能力，不是另起一个机器人。

  1. 23

    为什么要 RAG

    模型没读过你的文件。检索和微调、加长上下文的差别。

    撰写中
  2. 24

    最小切片与向量检索

    切块、嵌入、取回 top-k。先跑通，不追求花哨。

    撰写中
  3. 25

    检索接进 Harness

    作为本地工具、MCP 工具，或在进模型前注入。

    撰写中
  4. 26

    引用与防编造

    答案必须能指回片段。材料里没有的要说未提及。

    撰写中

阶段七 · 合成

聊天、Harness、本地工具、MCP、Skill、RAG 拼成一个 Agent。用固定题做回归。

  1. 27

    组装最终 Agent

    同一套 Harness 上同时挂本地工具、MCP、Skill、RAG。配置和开关。

    撰写中
  2. 28

    评测

    会不会停、选对工具、连对 MCP、加载对 Skill、不瞎编资料。

    撰写中
  3. 29

    附录：框架是别人的 Harness

    什么时候才值得换现成框架，以及对照我们自己写过的零件。

    撰写中