Comprehensive Guide to AI Agents: From Entry to Mastery (Practical Tutorial: Building a Research Paper Agent)

我最近给娃买了一本书，叫《给宝宝的机器人学》。

书里从做一个圆形开始：最早拿笔画，再用剪刀剪；后来换成圆形工具，压一下就能得到一个圆；再往后有了机器、程序、传感器、摄像头、传送带和机械臂，最后做成了一台可以自动生产圆形的机器人。

Agent 的发展也是这条路。

大模型会回答以后，人们很快发现，光会回答还不够。它得拿到最新数据，要能打开文件，得知道刚才那一步有没有做成，还得在出错以后继续处理。今天看到的 Claude Code、Codex 和各种桌面 Agent，都是这些具体问题一点点推出来的。

大模型和 Agent 到底有什么区别？

大模型会生成答案，Agent 会接着把事情做下去。

把一份会议纪要发给大模型，它会在对话框里整理出行动清单。把同一项任务交给 Agent，它可以自己找到会议文件，读取内容，生成清单，写回项目目录，再检查负责人和截止时间有没有漏掉。

Agent 里面也有模型。除此之外，它还要能读文件、调用工具、记住做到哪里，并把结果写回去。聊天模型交出来的通常是一段话，Agent 交出来的可能是一张表、一个改好的文件，或者一项已经跑完的任务。

同一个模型放进不同产品，表现会差很多。放在聊天框里，它主要看到当前对话；放进 Claude Code 或 Codex CLI，它可以读取文件、运行命令、查看报错；放进 Codex 桌面端，它又能管理项目、保存任务、展示文件改动和等待权限确认。

所以，同一个模型放进不同产品，做事的差距可以很大。差别并不全在模型本身，还在它能接触什么、能调用什么，以及做完以后会不会检查。

左边是一份回答，右边是一项做完的工作。

再讲一个真实的故事

上周，我给一个学医的朋友装了 Codex。他以前也用 AI，主要是豆包和元宝。做信息录入和学术研究时，他会找 AI 问问题，但材料仍然要自己整理，先把AI的回答从对话框里复制出来，再复制进表格或文档。

Codex 装好以后，他很快给我反馈说，这个东西太好用了，额度完全不够，让我帮他充了 20 美元的会员。

他没有去学编程。变化来自 Codex 开始接触他的工作现场：它可以读取指定文件夹里的材料，调用工具处理内容，把结果写回文件，再重新打开检查。过去的 AI 给他一段答案，他自己完成剩下的搬运；现在的 Agent 可以接手其中一段完整流程。

这件事给我的感受很直接。会写、会总结的 AI，他早就在用了；让他愿意立刻付费的，是 AI 终于能进入文件和软件，把一段工作接过去。

模型：最早的 AI 只负责回答

大语言模型最基础的工作，是根据前面的内容猜后面最可能出现什么。它每次生成一个 token，再接着往后预测。token 有时是一个字，有时是一个词的一部分。文章、代码和回答，就是这样一点点生成出来的。

2017 年出现的 Transformer，让模型更善于处理一段文字前后的关系，也让大规模训练变得可行。模型看过的文字和代码越来越多以后，开始能够写文章、做翻译、总结材料和生成程序。

早期模型更像一个续写器。后来加入指令微调和人类反馈，它才逐渐学会按要求回答、使用指定格式，也更接近今天熟悉的聊天助手。

推理模型又把多步骤问题做得更稳。遇到数学、代码和复杂分析，它会在给出结果前做更多判断。模型变强了，能力仍然停留在生成这一层：它看不到用户电脑里的文件，不知道刚刚发生的新闻，也没有打开邮箱和修改表格的权限。

这也解释了模型为什么会一本正经地说错。它生成的是当前上下文里很顺的一段内容，没有自动去原始资料里逐项核对。人名、年份和论文题目如果缺少来源约束，几个相近的信息可能被拼到一起。

上下文窗口变长后，模型一次可以看到更多材料。窗口仍然有边界，任务越长，文件、工具结果和历史步骤占用的空间越多。系统还要决定哪些内容继续保留，哪些做成摘要，什么时候回到原文件重读。

放进后面要搭的论文资料项目里，这时我们只有一个“摘要助手”。复制一段摘要给模型，它能整理题目、研究对象和主要结论。下一篇论文仍然要人去找，表格也要人自己建。

模型的输出，是一个 token 接着一个 token 生成的。

Tool 和 API：模型开始能够调用真实数据

模型靠训练记住的知识会过时。天气、订单、日历和论文数据库却一直在变化，要取得这些内容，需要访问对应的软件服务。

API 是软件留给外部程序的接口。天气服务的 API 接收城市和日期，返回温度和降雨；日历 API 接收时间、标题和参与人，创建一条日程。Tool 则把这些能力整理成模型能够看懂的说明：这个工具能做什么，需要填哪些信息，会返回什么结果。

用户问“明天杭州会不会下雨”，模型先从工具列表里选中天气工具，交出“杭州”和“明天”。承载 Agent 的程序检查权限，访问天气 API，再把结果送回模型。模型读完真实天气数据以后，才组织回答。

在这个过程中，模型负责选择工具、填写信息、理解返回的结果；程序负责联网、保管密钥和执行动作。模型不会因为会调用天气工具，就顺便获得邮箱和数据库的权限。

2023 年，ChatGPT Plugins 和 function calling 把这种方式带给更多开发者。搜索、计算器、邮件、日历和数据库，开始被登记成模型可以选择的工具。

工具说明写得好不好，会直接影响 Agent。一个工具只写“查询数据”，模型很难判断该什么时候用；写成“查询客户订单”，再说明订单号和时间范围，选择就会稳定很多。错误信息也一样。“执行失败”没法指导下一步，“订单不存在”和“当前账号无权查询”会让 Agent 采取不同处理。

论文资料项目到了这里，可以接入 PubMed 检索工具。模型把研究问题整理成检索词，工具取得 PMID、作者、年份和摘要，模型再去理解摘要。来源由工具取回，内容由模型归纳。

Tool 和 API 让模型拿到训练数据之外的最新结果。

Agent Loop：做完一步，再看下一步

一次 Tool 调用只能完成一个动作。真实工作往往要连续做很多次：先找材料，再读取内容，发现缺项后继续搜索，生成表格，最后重新打开检查。

Agent Loop 说的就是这个过程：看当前情况，做一个动作，拿到结果，再决定下一步。

2022 年提出的 ReAct，把推理和行动交错在一起。搜索没有结果，模型可以换关键词；命令执行失败，它会读报错；文件生成以后，它还能重新打开，看看内容是否符合要求。

循环里要保存任务进度。Agent 需要知道哪些文件已经读过，哪些步骤已经完成，哪些问题还在等待处理。任务变长以后，旧过程还会被压缩成摘要，关键结果则继续保留。

计划也会变化。原本准备读完三份材料就写报告，第二份材料出现了冲突，Agent 应该增加核对来源这一步。计划提供方向，不会把它锁死在一条固定路线里。

循环还要知道什么时候停。文件写出来，只说明保存成功。如果完成标准是“12 份材料全部覆盖、重复项合并、缺失字段标出”，Agent 还要重新打开结果逐项核对。遇到无法判断的冲突，它应该停下来找人。

2023 年的 Auto-GPT 已经具备这种连续行动的形态。当时经常出现忘记目标、反复搜索和把错误继续带到后面的情况。循环让模型能够一直做，也会把一次误判连续放大。模型、工具、上下文和停止条件都稳定以后，Agent 才逐渐从演示走进日常工作。

论文资料项目也会沿着这个循环运行：读取本地材料，缺信息时检索，整理字段，生成表格，再查重复 PMID、空字段和失效链接。发现问题就回去修，达到要求以后再结束。

结果不合格就回去再做一遍，这就是 Agent Loop。

文件、终端和屏幕：Agent 终于有了工作现场

聊天模型看到的是用户贴进对话框的内容。Agent 进入文件系统以后，可以自己寻找材料，打开文件，把结果保存到指定目录。进入终端以后，它还能搜索内容、转换格式、处理表格和运行检查。

终端每做一件事都会留下结果。命令成功还是失败，哪个文件没有找到，表格有多少行，这些信息都能回到 Agent Loop。Agent 不再靠猜，它开始根据真实反馈调整。

还有一些软件没有开放 API。2024 年，Anthropic 发布 computer use 公测，让模型根据截图移动鼠标、点击按钮和输入文字。2025 年，OpenAI 的 Operator 和 Computer-Using Agent 也展示了相近方向。

屏幕操作能覆盖更多老软件，稳定性却比 API 低。按钮换位置、网页弹窗、登录失效，都可能让任务中断。有接口时优先通过接口取得结构化结果，确实没有接口，再让 Agent 操作屏幕。

工作现场越真实，权限也越值得注意。Agent 看到文件和网页，可能读到夹在其中的恶意指令。项目目录、沙箱和人工确认负责限制它能去哪里、能改什么。

论文资料项目的工作范围可以很小：原始材料放在项目里，结果写到单独文件夹，公开信息从 PubMed 取得。它没有读取整台电脑的理由，也不应该接触患者资料。

文件和终端把模型的回答变成电脑里的实际结果。

MCP：让 Agent 接上外部软件

每个 Agent 都会遇到同一个接入问题：怎样连接文档库、数据库、设计工具和业务系统。过去每款 Agent 都要分别适配，工具一多，连接和维护会变得很麻烦。

MCP 在 2024 年发布，规定了一套通用的连接方式。一个 MCP Server 会告诉 Codex：这里有哪些工具，每个工具需要什么信息，调用后会返回什么。Codex 连接以后，模型就能从这份清单里选择合适的工具。

MCP 背后通常还是 API。API 负责真正查询或修改数据，MCP 负责把这些能力用统一方式交给 Agent。它没有替模型做计划，也不会替用户决定权限。

一个 MCP 连接中心，可以把多种外部工具交给 Agent。

接上 MCP 以后，工具本身仍然要做好。一次返回几万行无关数据，模型很难找到重点；写入工具没有预览和确认，误操作的风险会很高。返回范围、错误说明和权限设计，都会影响最终结果。

论文都在本地项目里时，Codex 自带的文件和网络能力已经够用。资料放在 Google Drive、Notion 或其他外部系统里，再通过插件或 MCP 接入。工具应该跟着任务增加，不用一开始把所有服务都接上。

模型接上的东西越来越多，Agent 才有了今天的样子。

Claude Code 和 Codex CLI：为什么 Agent 先在代码里跑通

2025 年，Claude Code、Codex CLI 等产品让程序员明显感受到变化。用户交出“找到登录失败的原因，修好以后运行测试”，Agent 会搜索项目、读取文件、修改内容，再执行测试。测试失败，它读完报错继续改；测试通过，才把改动交给人审查。

代码项目很适合早期 Agent。材料都在仓库里，终端已经有搜索、编辑、运行和测试工具。程序执行后会产生清楚的错误信息，修改前后可以看 Git Diff，方向做错了还能借助版本记录恢复。

普通聊天模型写出一段代码，究竟能不能运行，要等人复制出去才知道。编码 Agent 可以当场执行，看到缺少模块或者测试失败，再回到文件里修改。这种密集反馈，让它更容易把长任务做完。

代码后来又成了 Agent 处理其他工作的通用工具。整理资料时，它可以临时做一个提取工具；处理表格时，可以检查空值和重复项；制作网页、图表和课件时，代码负责批量处理，用户拿到的是最终文件。

2025 年 2 月，Claude Code 以研究预览的方式发布。4 月，OpenAI 发布 Codex CLI；5 月，Codex 云端 Agent 上线。模型、文件、终端和反馈被放进同一个现场，Agent 终于有了一套容易执行、容易检查、出错后也容易恢复的工作环境。

从 CLI 到桌面端：普通人也开始用 Agent

CLI 对程序员很自然，普通人却很难从一屏命令里判断 Agent 做到了哪里、改过什么、下一步需要什么权限。Agent 已经能处理很多工作，入口仍然偏技术。

2026 年 2 月，Codex 桌面端发布。项目、任务、文件修改、产物预览和权限审批被放进一个工作台。用户看到的单位也从“一轮聊天”变成“一项工作”：任务可以运行较长时间，连续调用工具，最后留下文件、修改记录和待确认事项。

桌面端做的事情远不止给 CLI 换一层界面。它把任务属于哪个项目、Agent 正在处理什么、改过哪些文件、哪项操作等待授权、产物去哪里查看，都摆到了用户面前。

桌面端把终端里的工作过程摊开给人看。

多个任务也可以分开运行。一个整理资料，一个核对引用，一个生成网页，各自保留自己的上下文和文件变更。人不必守着每一步操作，回来以后还能看懂每份结果从哪里来。

同一个项目可以同时保留多个任务，每项工作都有自己的进度和上下文。

Claude Code、Codex CLI、Codex 桌面端、Claude Cowork 和 WorkBuddy 展示的是同一条产品线：Agent 从终端走向普通人的文件和办公软件。评价它的标准也随之变化，从“回答得好不好”变成“工作能不能稳稳交回来”。

为什么同一个模型放进 Codex，会好用这么多

聊天框每次拿到的，主要是当前对话里的文字。Codex 打开一个项目以后，还能看到项目里的文件、之前留下的规则，以及工具刚刚返回的结果。

它改完一个文件，可以重新打开；做完一张表，可以检查行数和空值；运行失败，可以直接读报错。模型不必凭空猜测“应该已经好了”，因为电脑会把结果告诉它。

Codex 还会把每项任务单独保存。一个任务整理材料，另一个任务核对引用，两个任务不会挤在同一段长对话里。哪些文件被改过、哪些操作需要授权，也能在界面里看到。

行业里有人把包在模型外面的这套东西叫 Harness。名字可以先不记。只要记住一件事：模型决定下一步做什么，Codex 负责把文件、工具、权限和执行结果送到它面前。缺了后面这部分，再强的模型也只能隔着聊天框给建议。

实战：用 Codex 做一个论文资料整理 Agent

下面继续用学医朋友的工作来做。目标很明确：放入几份公开论文或摘要，Codex 整理出题目、作者、年份、研究对象、主要结论和原始来源。查不到的内容留空，不允许顺手补一个答案。

接下来搭的论文资料 Agent，就是这样一条从材料到结果的流水线。

先把项目建起来

在电脑上新建“论文资料整理”文件夹，然后用 Codex 打开。新建任务，把下面这段话发给它：

~~~text 请在当前项目里建立三个文件夹：

原始资料：保存论文、摘要和文献导出文件 整理结果：保存表格和待确认清单 参考模板：保存我认可的表格样例

只创建文件夹，不要处理材料。 不要修改“原始资料”里的文件。 ~~~

建好以后，把三到五份公开材料放进“原始资料”。数量少一点，方便核对第一遍结果。

先让它完整跑一次

把任务切到 Plan 模式，让 Codex 先看材料，再说准备怎么做：

1读取“原始资料”中的全部文件，整理一份论文索引。
2
3表格包含：题目、作者、年份、研究对象、主要结论、原文件名和来源链接。 重复论文合并。
4原文没有写明的信息标记为“待确认”，不要推测。
5结果保存到“整理结果”，不要修改原始文件。
6先给出处理计划。计划中列出你识别到的文件、准备生成的文件，以及完成后怎样检查遗漏。
7
8等我确认后再执行。

文件生成后直接打开看。输入了五份材料，表格就应该能对应到这五份；重复项有没有合并，也能从题目、DOI 或 PMID 看出来。主要结论至少抽两条回原文核对。“待确认”如果被填成了确定答案，就让 Codex 删除并重新检查整张表。

这一版不接 MCP，也不做 Skill。先确认 Codex 只靠本地材料能把基本流程跑顺。

缺书目信息，再补 PubMed 工具

本地摘要经常缺年份、期刊或 PMID。每次都手动搜索很慢，可以让 Codex 为当前项目做一个 PubMed 检索工具。

1当前项目缺少公开文献检索能力。
2
3请先调研 PubMed 的官方公开接口，再为当前项目制作一个检索工具。 输入研究问题、论文题目或检索词后，返回： PMID、题目、作者、年份、期刊、摘要和 PubMed 原始链接。
4单次最多返回 20 条。
5缺失字段保留为空，不要推测。 工具只在当前项目中读写。
6
7先给出方案，说明会新增哪些文件、怎样测试。
8
9等我确认后再制作。

这里不要求自己写代码。Codex 会完成实现。方案出来以后，主要看三件事：数据是不是来自 PubMed，工具会不会跑到项目外面，失败时会不会把“没有结果”说清楚。

让它用一个公开检索词取回三条记录。三个 PMID 都能打开，题目和年份也对得上，这个工具才可以放进后面的流程。

把不能改的规矩写进 AGENTS.md

聊天里的要求很容易散在不同任务中。Codex 会读取项目里的 AGENTS.md，可以把长期规则放进去：

1请在项目根目录创建 AGENTS.md，写入以下规则：
2
3只处理公开论文和我放入“原始资料”的文件。
4不接触患者资料，不生成诊断或治疗建议。 所有结论必须能回到原始摘要或来源链接。
5缺失信息写“待确认”，禁止补写。
6 原始文件只读，结果只能写入“整理结果”。
7交付前检查文件数量、重复 PMID、空字段和失效链接。
8
9写完后重新打开 AGENTS.md，把内容复述给我。

以后在这个项目里新建任务，Codex 都会先读这份文件。规则有变化，直接改 AGENTS.md，不必在每次对话里重新讲一遍。

AGENTS.md 跟着项目走，Skill 留下可以重复使用的方法。

资料在外部软件里，再接 Plugin 或 MCP

论文已经下载到项目里，就继续用本地文件。资料如果放在 Google Drive、Notion 或团队文档库里，再考虑接外部服务。

Codex 的 Plugins 页面可以直接搜索已有插件。打开插件详情，先看它会带来哪些 Skill、连接器或工具，再决定要不要安装。需要账号授权时，授权页面会列出它能读取的范围。

Codex 的 Plugins 页面。

没有现成插件时，可以在“设置”中打开“MCP servers”，选择“Add server”。本机运行的服务使用 STDIO，通过网址连接的服务使用 Streamable HTTP。保存并重启后，在输入框键入 /mcp，可以查看服务器是否已经连上。

MCP 的两种常见连接方式。

MCP 后面连着真实文件和账号，地址不要随手从帖子里复制。先确认提供方，再看权限和工具列表。这个论文项目如果只用本地文件和 PubMed，完全可以不接 MCP。

把这套做法保存成 Skill

前面的流程跑过几次以后，可以把它存成 Skill。以后换一个研究问题，不必重新解释字段、去重方法和检查要求。

在新任务里输入 $skill-creator，然后发送：

1请把当前项目已经跑通的论文资料整理方法做成一个 Skill。
2
3它需要完成： 检查“原始资料”中的文件；
4整理题目、作者、年份、研究对象、主要结论和来源；
5按 PMID 和 DOI 合并重复项； 缺少书目信息时调用项目里的 PubMed 工具；
6生成论文索引和待确认清单；
7交付前重新打开结果，检查遗漏、重复和失效链接。
8项目边界继续遵守 AGENTS.md。
9
10先生成 Skill 草稿，等我确认后再保存。

Skill 可以在新任务中再次调用。

Skill 保存以后，开一个新任务，在输入框键入 $，选中刚才创建的论文资料整理 Skill。然后放入另一批材料，只写本次研究问题：

1整理“原始资料”中的本批文件。
2
3研究问题：睡眠时长与高血压之间有哪些公开研究线索？
4
5完成后在“整理结果”中留下论文索引和待确认清单。

如果新的任务能自动读取 AGENTS.md，按固定字段整理材料，缺信息时调用 PubMed 工具，并把结果放到指定文件夹，这套 Agent 就已经能反复使用了。

下一次换课题，替换“原始资料”里的文件，再写下新的研究问题就可以继续。表格整理、来源补全、重复项检查交给 Codex；论文是否可靠、结论能不能用于研究，仍然由人来判断。

OK，恭喜你，到这里，你就已经把基础的 Agent 功能都跑过一遍了。

我是 Miles，一名从大厂转型 FDE 的 AI 算法专家，做过算法研发、优化部署，也做过企业培训。关注我@miles_mazy，一起成长，一起赚钱。