convez.ai
AgenteAutomaçãoIntermediário
MangolDurian

Agent Harness Lab

MangolDurian/agent-harness-lab

Construa AI Agents incrementais: loop → tools → skills → teams → autonomia

Ver no GitHub
InicialPluginScore · de 0 a 100

Laboratório prático de construção de AI Agents do zero, seguindo um currículo estruturado (s01-s12) que implementa incrementalmente loops, ferramentas, skills, teams e protocolos. Cada estágio adiciona uma camada de complexidade mantendo o core imutável, com código executável, notas detalhadas e validações de cada fase.

Instalação

$npx convez-ai MangolDurian/agent-harness-lab

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Aprender arquitetura de agents do zero com código funcional
  • Implementar sistemas multi-agentes com divisão de tarefas
  • Explorar padrões de isolamento, compactação de contexto e comunicação entre agentes

Veredito

Excelente recurso educacional para quem quer entender a engenharia real de agents com Claude. Estrutura clara (core imutável + camadas) força boas práticas; código está vivo e validado a cada stage. Ideal para construir intuição sólida antes de produção.

README

A tradução para o português deste README ainda está na fila.

agent-harness-lab

跟着 learn-claude-code 从 s01 学到 s12, 自己从零搭一遍 harness,每课都做个"课后作业"证明这一阶段的机制我真的会用了。

Agency 来自模型。Harness 让 agency 落地。

核心信念(整条学习路线的底层)

循环不变,机制叠加。 core/ 里的那个 loop 是 s01 写完的,s02~s12 一个字都不会改,只往 tools/ skills/ tasks/ ... 这些外层加东西。

目录结构(会随课程生长)

agent-harness-lab/
├── core/                       # 永远不变的地基(s01 写完后锁死)
│   ├── llm.py                  # Anthropic 客户端
│   └── loop.py                 # agent_loop()
├── tools/                      # 工具集,s02 起会扩充
│   ├── bash.py
│   ├── read_file.py
│   ├── write_file.py
│   ├── todo.py
│   ├── task.py
│   ├── subagent.py
│   ├── skill.py
│   ├── compact.py
│   ├── background.py
│   └── team.py
│   └── protocols.py
│   └── worktree.py
├── skills/                     # 技能定义(markdown 文件),s05 新增
│   ├── git.md
│   ├── debug.md
│   └── refactor.md
├── agents/                     # 每课一个入口脚本
│   ├── s01_agent_loop.py
│   ├── s02_multi_tool.py
│   ├── s03_todo.py
│   ├── s04_subagent.py
│   ├── s05_skills.py
│   ├── s06_context_compact.py
│   ├── s07_task_system.py
│   └── s08_background.py
│   └── s09_agent_teams.py
│   └── s10_team_protocols.py
│   └── s11_autonomous_agents.py
│   └── s12_worktree_isolation.py
├── docs/                       # 每课一份学习笔记
│   ├── s01-notes.md
│   ├── s02-notes.md
│   ├── s03-notes.md
│   ├── s04-notes.md
│   ├── s05-notes.md
│   ├── s06-notes.md
│   ├── s07-notes.md
│   ├── s08-notes.md
│   ├── s09-notes.md
│   ├── s10-notes.md
│   ├── s11-notes.md
│   ├── s12-notes.md
│   └── review/                 # 大白话讲解 + 面试官视角复盘(s01~s12)
├── examples/                   # 每课一份阶段成果验证清单
│   ├── s01_demo_prompts.md
│   ├── s02_demo_prompts.md
│   ├── s03_demo_prompts.md
│   ├── s04_demo_prompts.md
│   ├── s05_demo_prompts.md
│   ├── s06_demo_prompts.md
│   ├── s07_demo_prompts.md
│   └── s08_demo_prompts.md
│   ├── s09_demo_prompts.md
│   ├── s10_demo_prompts.md
│   ├── s11_demo_prompts.md
│   └── s12_demo_prompts.md
├── run-records/                # 手动实跑记录 + 复盘
│   └── s04-subagent-run-review.md
├── run-outputs/                # 手动实跑产生的文件,避免污染 agents/
│   ├── s03/
│   └── s04/
├── .env.example
├── requirements.txt
└── README.md

快速开始

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env     # 填入 ANTHROPIC_API_KEY 和 MODEL_ID
python agents/s01_agent_loop.py

学习路线与进度

课主题格言状态
s01Agent LoopOne loop & Bash is all you need✅
s02Tool Use加一个工具只加一个 handler✅
s03TodoWrite没有计划的 agent 走哪算哪✅
s04Subagent大任务拆小,每个小任务干净的上下文✅
s05Skills用到什么知识,临时加载什么知识✅
s06Context Compact上下文总会满,要有办法腾地方✅
s07Task System大目标要拆成小任务,记在磁盘上✅
s08Background Tasks慢操作丢后台,agent 继续想下一步✅
s09Agent Teams任务太大一个人干不完,要能分给队友✅
s10Team Protocols队友之间要有统一的沟通规矩✅
s11Autonomous Agents队友自己看看板,有活就认领✅
s12Worktree Isolation各干各的目录,互不干扰✅

每课的完成标准(课后作业的验收口径)

一课"结业"等价于同时满足三件事:

  1. 代码:agents/s{NN}_*.py 能正确跑起来
  2. 笔记:docs/s{NN}-notes.md 里写清楚这一课新加的机制 + 三条我相对原版故意做的差异
  3. 验证:examples/s{NN}_demo_prompts.md 里每条 prompt 跑出预期现象

s01:Agent Loop(已完成)

一个 while 循环 + 一个 bash 工具 = 一个 Agent。

相比原版的三个差异

差异原版本项目
工具分发硬编码 run_bash(...)handlers: dict[str, Callable] dispatch map
循环边界while Truefor turn in range(max_turns) + 返回 stop_reason
分层单文件core / tools / agents 三层,core 锁死

s02:Multi-Tool(已完成)

加一个工具只加一个 handler——core/loop.py 一行不改。

相比原版的三个差异

差异原版本项目
路径安全无限制resolve() + startswith() 工作目录边界检查
工具数量只加一个一次加两个(read + write),更能体现"叠加"模式
_print_tool_call统一格式为每个工具定制可视化(read 显示路径,write 显示路径+行数)

s03:TodoWrite(已完成)

没有计划的 agent 走哪算哪——用 handler wrapper 闭包实现 nag 提醒,core/loop.py 一行不改。

相比原版的三个差异

差异原版本项目
Nag 实现方式修改 agent_loop 内部,往 messages 注入 system reminderhandler wrapper 闭包,追加到工具输出尾部
代码组织单文件,TodoManager 和 handler 都内联tools/todo.py 独立模块 + agents/ 组装
Todo schema 格式Anthropic input_schemaOpenAI function calling format

s04:Subagent(已完成)

大任务拆小,每个小任务干净的上下文——delegate 工具启动嵌套 agent_loop,子 agent 拥有独立上下文。

相比原版的三个差异

差异原版本项目
子 agent 定义位置内联在 agent 入口中tools/subagent.py 独立模块
回调传递方式直接传参模块级变量 set_subagent_callback()
层级可视化无特殊区分缩进 + 灰色(子)vs 黄色(主)

s05:Skills(已完成)

用到什么知识,临时加载什么知识——load_skill 按需加载 markdown 技能文件,不把所有知识塞进系统提示词。

相比原版的三个差异

差异原版本项目
技能格式JSON/YAML 结构化定义纯 markdown 文件
工具设计列出/加载分为两个工具一个 load_skill 处理两种情况
技能发现注册表或硬编码列表自动扫描 skills/ 目录

s06:Context Compact(已完成)

上下文总会满,要有办法腾地方——通过 on_tool_call 回调 + closure 实现三层压缩,core/loop.py 一行不改。

相比原版的三个差异

差异原版本项目
压缩触发位置修改 agent_loop for 循环头部on_tool_call 回调 + closure 访问 messages
compact 工具执行直接在 loop 内检查并调用压缩handler 设置 flag + on_tool_call 检查 flag 并执行
auto_compact 摘要格式单条 system reminderuser+assistant 消息对(兼容 OpenAI 格式交替要求)

s07:Task System(已完成)

大目标要拆成小任务,记在磁盘上——用持久化任务系统替代内存 todo,支持增量操作和父子层级。

相比原版的三个差异

差异原版本项目
存储方式内存中 TodoManagerJSON 文件持久化 + 原子写入
操作模式全量替换(每次传完整列表)三个增量工具(create/update/list)
任务层级扁平列表单层父子(parent_id),树形格式化输出

s08:Background Tasks(已完成)

慢操作丢后台,agent 继续想下一步——bash 工具新增 run_in_background 参数,handler wrapper 注入后台完成通知。

相比原版的三个差异

差异原版本项目
后台通知注入直接插入 assistant 消息handler wrapper 输出前缀(不改 loop)
后台任务管理内建调度系统简单的 threading + dict(daemon 线程)
扩展 bash 参数修改 bash 工具定义deepcopy SCHEMA + agent 层扩展

s09:Agent Teams(已完成)

任务太大一个人干不完,要能分给队友——spawn 创建持久化队友(独立线程),通过 JSONL inbox 消息总线互相通信。

相比原版的三个差异

差异原版(s04 delegate)本项目(s09 队友)
并发模型阻塞主 agent,等子 agent 完成独立线程并发,lead 可继续工作
通信方式子 agent 返回结果给主 agentJSONL inbox 消息总线,双向通信
生命周期一次性,用完即弃持久化,working/idle 状态循环

s10:Team Protocols(已完成)

队友之间要有统一的沟通规矩——结构化请求-响应协议替代随意消息,优雅关机替代强杀线程。

相比原版的三个差异

差异原版本项目
协议实现位置修改 agent_loop 内部独立 tools/protocols.py 模块 + team.py send 扩展
队友工具注入硬编码队友工具列表configure_teammate() 工厂模式,agent 层组装
关机方式保留 __shutdown__ 强杀双轨:shutdown_request 握手优先,__shutdown__ 兜底

s11:Autonomous Agents(已完成)

队友自己看看板,有活就认领——空闲队友自动扫描任务板、认领无主任务、完成后自动找下一个。

相比原版的三个差异

差异原版本项目
认领机制基础设施直接 claim + 执行基础设施扫描但构造 prompt 让 LLM 调 task_claim——保持"队友只通过工具操作"模式
in_progress 约束全局单 in_progress + 文件锁按 owner 的 in_progress 槽——多个队友可并行工作
空闲超时独立计时器线程或事件idle_start 时间戳嵌入现有 poll 循环——无新线程、无新事件

s12:Worktree Isolation(已完成)

各干各的目录,互不干扰——给任务绑定独立的 git worktree 目录,队友认领任务时自动在隔离目录工作。

相比原版的三个差异

差异原版本项目
任务存储.tasks/task_N.json 每任务单文件保持 data/tasks.json 统一文件 + 新增 worktree 字段
执行隔离方式修改 loop 层传入 cwd工厂函数创建 worktree-aware 的 bash/read/write handler
Worktree 粒度全局 worktree exec队友认领绑定 worktree 的任务时自动隔离
Ver o original no GitHub

Bom para

Relacionados