一天介绍一个项目|从零手搓一个AGENT

今天介绍一个最近在 GitHub Trending 上爆火的开源项目——learn-claude-code,目前已经快 3 万星了。

项目地址:https://github.com/shareAI-lab/learn-claude-code

这个项目是干嘛的?

一句话概括:从零开始,手把手教你搓一个类似 Claude Code 的 AI Agent。

用过 Claude Code 的朋友应该都好奇过:它到底是怎么做到"你说一句话,它就能帮你改代码、跑命令、操作文件"的?这个项目就是来揭秘的。

作者的核心观点很直接——"Bash is all you need"。意思是,Agent 没有你想的那么复杂,本质就是一个循环:调 LLM → 拿到工具调用 → 执行 → 把结果喂回去 → 再调 LLM……如此反复。

用项目原话说:代理就是模型,代码只是支撑框架(harness)。

12 节课,从入门到能打

这个项目最牛的地方是它把学习路径拆成了 12 节循序渐进的课,每节课对应一个 Python 文件,跑起来就能看到效果。

第一阶段:搞懂基本循环(s01-s02)

这是最核心的部分。s01 教你写一个最简单的 Agent 循环——就是一个 while True,不断调 LLM,如果返回的是工具调用就执行,如果是普通文本就输出给用户。

s02 加入工具分发机制,把不同工具的处理函数注册到一个字典里,循环只管查字典调函数,加新工具完全不用改核心逻辑。

一句话总结:一个 while True 循环就是 Agent 的心脏。

第二阶段:让 Agent 不再瞎跑(s03-s06)

光有循环还不够,Agent 容易"跑偏"。这个阶段加了四个关键能力:

  • s03 规划系统:让 Agent 先想好怎么做,再动手,不会东一榔头西一棒槌
  • s04 子 Agent:复杂任务拆成小任务,每个子任务有独立的对话上下文,互不干扰
  • s05 技能系统:把常用操作封装成"技能文件",Agent 可以按需加载
  • s06 上下文压缩:聊久了上下文会爆,这节课教你用三层压缩策略(摘要层 + 核心记忆层 + 实时工作层)解决这个问题

第三阶段:跨会话记忆(s07-s08)

  • s07 任务持久化:把任务存到文件系统里,关掉程序再打开,之前的任务还在
  • s08 后台任务:用多线程让 Agent 可以同时干好几件事

第四阶段:团队作战(s09-s12)

这是进阶内容,教你搞多 Agent 协作:

  • s09-s10:多个 Agent 之间怎么通信(用 JSONL 邮箱协议),怎么自动认领任务
  • s11-s12:工作树隔离,每个 Agent 在独立目录里干活,互不干扰,最后合并

核心代码长啥样?

说了这么多,Agent 的核心骨架到底多简单?看这段代码就够了:

def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            return
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

就这么几行。调 LLM,拿到工具调用就执行,拿到文本就返回。这就是 Agent 的全部骨架。

怎么开始学?

动手只需要 5 步:

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env  # 填入你的 ANTHROPIC_API_KEY
python agents/s01_agent_loop.py  # 从第一课开始跑

从 s01 开始,一节一节往后学,每节课都是一个独立可运行的 Python 文件。

另外项目还提供了一个 Next.js 做的可视化学习平台,可以在浏览器里看架构图和步进调试:

cd web && npm install && npm run dev
# 打开 http://localhost:3000

适合谁?

  • 想搞明白 Agent 到底是怎么回事的开发者
  • 用过 Claude Code 但好奇它内部原理的人
  • 想自己从零搓一个 Agent 的实践派
  • 刚入门 AI 应用开发,想找个靠谱教程的同学

最后

别光收藏,clone 下来跑一遍 s01,你会发现 Agent 真没那么神秘。

#AI项目实战##AI求职实录#
全部评论

相关推荐

不愿透露姓名的神秘牛友
03-19 10:38
实力求职者:真的绷不住了,第一张霸总人设,第二张求生欲拉满
点赞 评论 收藏
分享
03-18 10:30
已编辑
阿里巴巴_淘宝_前端
// 淘天 27 届暑期实习生正在招聘 各方向都有海量 HC 欢迎看我置顶帖子投递最近在帮部门看简历,发现不少同学在做项目时都挂了 Agent 的标签。但在面试过程中,很多同学对这个方向的理解还停留在调用API的层面,稍微深挖一下架构设计就接不住了。整理了一个最近面试中比较高频的Agent技术问题,大家可以先试着回答一下,看看基础扎不扎实:---一面 | AI Agent 架构设计面试题:请设计一个支持多工具调用的 ReAct Agent,说明其核心循环、工具调度策略、以及如何处理多步推理中的错误恢复。---参考答案一、ReAct 核心循环ReAct 的本质是一个 思考 → 行动 → 观察的迭代循环。Agent 在每一步先进行推理(Thought),分析当前状态和已有信息,决定下一步该做什么;然后执行行动(Action),选择一个工具并传入参数;最后获取观察结果(Observation),把工具返回的信息追加到上下文中,进入下一轮循环。直到 Agent 判断已经获得足够信息,输出最终答案。与纯 Chain-of-Thought 的核心区别:CoT 是闭卷考试,Agent 是开卷——每一步推理都可以与外部世界交互,用真实数据修正推理方向,而不是纯靠模型内部知识"硬猜"。二、工具注册与调度工具如何让 LLM "认识":每个工具以结构化方式注册,包含名称、功能描述、参数定义(类型、是否必填、含义说明)。这些信息会被注入到系统提示词中,LLM 通过理解这些描述来决定何时调用哪个工具、传什么参数。工具描述的质量直接决定了 Agent 的调度准确率——描述模糊,模型就会选错工具。三种调度策略:- 串行调用:每次只调一个工具,等到结果后再决定下一步。适合步骤之间有依赖关系的场景,比如"先查订单号,再根据订单号查物流"。- 并行调用:一次推理中输出多个工具调用,并发执行。适合多个独立子任务,比如"同时查北京天气和上海天气"。- 规划-执行分离:先让 LLM 生成一个完整的多步计划,再逐步执行每一步。适合复杂任务需要全局视角的场景。生产环境通常是混合策略:Agent 动态判断当前步骤是否有可并行的操作,有则并行,否则串行。三、错误恢复机制工具执行失败:核心原则是**不要在工程侧硬编码恢复逻辑**。工具失败后,应该把错误信息作为 Observation 原样返回给 LLM,让模型自己决定下一步——是重试、换个工具、还是换一种思路绕过。这恰恰是 Agent 相比传统程序的核心优势:用 LLM 的推理能力应对非预期情况。当然,对于网络超时这类瞬时错误,工程侧可以做有限次数的自动重试,但逻辑层面的恢复应该交给模型。推理陷入死循环:Agent 可能反复执行相同的操作却期待不同结果。需要一个循环检测机制:对比最近几步和之前几步的行为模式,如果工具调用和参数完全重复,就往上下文中注入一条引导信息,提示模型"你在重复相同操作,请尝试不同方法"。同时设置全局最大迭代次数作为硬性兜底。上下文窗口溢出:这是多步推理中最现实的工程问题。每一轮循环都会往上下文里追加 thought + action + observation,几轮下来就可能撑爆窗口。常用解法:对早期步骤做摘要压缩只保留关键结论,对过长的工具返回结果先截断或提取摘要再存入历史,以及每隔几步让 LLM 自己总结"到目前为止的关键发现"。四、生产级可观测性上线不是终点。一个可靠的 Agent 系统需要:完整的 Trace 记录(每一步的推理、行动、观察),Token 消耗监控(防止成本失控),任务维度的成功率和平均步数统计,以及超过最大步数后降级到人工处理的兜底机制。---追问 Q&AQ1:多 Agent 协作时,如何设计 Agent 之间的通信和协调机制?A:主流有两种模式。Supervisor 模式(中心化):一个"主管 Agent"负责接收任务、拆解子任务、分配给专项 Agent,然后汇总各 Agent 的结果做最终决策。好处是流程可控、容易调试,缺点是主管 Agent 成为单点瓶颈,它的推理能力决定了整个系统的上限。去中心化消息传递:多个 Agent 通过共享的消息总线或黑板系统通信,每个 Agent 监听自己关心的消息类型,处理后将结果发回总线。好处是扩展性强、不存在单点瓶颈,缺点是调试困难、消息顺序和冲突处理复杂。实际工程中更常见的是分层混合架构:顶层用 Supervisor 做任务编排,底层的子任务内部允许 Agent 之间点对点通信。这样兼顾了全局可控性和局部灵活性。一个经常被忽略的关键设计点是共享上下文管理:多个 Agent 看到的"世界状态"如何保持一致?通常会设计一个共享的 State 对象,所有 Agent 只能通过定义好的接口读写状态,避免并发冲突。---Q2:Agent 的短期记忆和长期记忆应该如何设计和配合?A:本质上对应两种不同的信息需求。短期记忆就是当前对话的上下文窗口,存放的是本次任务的推理过程和中间结果。它的特点是时效性强但容量有限。核心挑战前面说过——窗口溢出管理。长期记忆是跨会话持久化的知识,通常用向量数据库实现。每次对话结束后,把值得记住的信息(用户偏好、历史决策、领域知识)向量化后存入。下次对话开始时,根据当前问题做相似性检索,把相关的长期记忆注入到系统提示词中。两者的配合策略:Agent 在每一轮推理前,先从长期记忆中检索与当前任务相关的历史经验("上次处理类似问题时用了什么方法"),注入到上下文中作为参考。短期记忆负责当前任务的连贯推理,长期记忆负责跨任务的知识积累。一个常见的坑是记忆污染:把错误的推理结论写入了长期记忆,导致后续任务反复犯同样的错。所以写入长期记忆前需要有质量校验机制,比如只有任务成功完成时才写入,或者由另一个 LLM 评估该记忆是否值得保留。---Q3:如何防止 Prompt Injection 导致 Agent 执行恶意工具调用?A:这是 Agent 安全中最核心的问题。攻击面在于:Agent 处理的用户输入或工具返回的外部数据中,可能嵌入了恶意指令,诱导 LLM 执行非预期操作。防御需要多层:第一层:输入隔离。 用户输入和系统指令必须在提示词中明确分隔,使用结构化标记区分"这是系统指令"和"这是用户数据"。避免用户输入被模型当作指令执行。第二层:工具权限分级。不同风险等级的工具设置不同的调用条件。只读查询类工具可以自由调用,但涉及写入、删除、发送等不可逆操作的工具,需要额外的确认机制——比如二次 LLM 审核(用另一个独立的模型判断"这次调用是否合理"),或者直接要求人工确认。第三层:输出过滤。工具返回的外部数据在进入 Agent 上下文前,先做清洗,去除可能被解释为指令的内容。第四层:行为监控。对 Agent 的工具调用模式做异常检测。比如一个处理客服问题的 Agent 突然开始调用文件系统工具,这明显异常,应该立即阻断并告警。没有银弹,必须纵深防御。---Q4:如何评估一个 Agent 系统的效果?和评估单次 LLM 调用有什么区别?A:区别很大。单次 LLM 调用的评估是静态的——给输入、看输出、算指标。但 Agent 是一个多步动态过程,同一个最终结果可能有完全不同的路径质量。Agent 评估需要看三个维度:结果维度:任务是否完成、最终答案是否正确。这和评估普通 LLM 类似。过程维度:用了几步完成(效率)、有没有冗余操作(比如查了不需要的信息)、有没有走弯路后自我纠正(鲁棒性)。两个 Agent 都答对了,但一个用了 3 步另一个用了 15 步,质量完全不同。成本维度:总 Token 消耗、工具调用次数、端到端延迟。在生产环境中,这直接决定了系统是否可用。评估方式上,通常会构建一个 benchmark 数据集,包含不同难度的任务和标准答案。让 Agent 跑一遍,同时记录完整 trace。然后用自动化指标(完成率、平均步数、Token 消耗)加人工评审(推理路径是否合理)综合打分。
查看5道真题和解析
点赞 评论 收藏
分享
暴杀流调参工作者:春招又试了一些岗位,现在投递很有意思,不仅要精心准备简历,投递官网还得把自己写的东西一条一条复制上去,阿里更是各个bu都有自己的官网,重复操作无数次,投完简历卡完学历了,又该写性格测评、能力测评,写完了又要写专业笔试,最近还有些公司搞了AI辅助编程笔试,有些还有AI面试,对着机器人话也听不明白录屏硬说,终于到了人工面试又要一二三四面,小组成员面主管面部门主管面hr面,次次都没出错机会,稍有不慎就是挂。 卡学历卡项目卡论文卡实习什么都卡,没有不卡的😂
点赞 评论 收藏
分享
评论
5
9
分享

创作者周榜

更多
牛客网
牛客网在线编程
牛客网题解
牛客企业服务