Stanford CS 329Z Lecture 10 covers Agent evaluation engineering with Terminal-Bench and Harbor
CS 329Z: Engineering AI Agents
In Lecture 10 of the Stanford CS 329Z course, Alex Shaw and Ryan Marten explain how to use Terminal-Bench and Harbor to turn Agent evaluation into an iterative engineering process. Terminal-Bench builds a community benchmark from terminal tasks; a task directory consists of instruction.md, task.toml, environment/Dockerfile, solution/solve.sh, and tests/test.sh, and the verifier determines environment state through programmatic checks and an LLM judge. The lecture notes also present practices for isolating the agent and verifier environments to prevent reward hacking, and for distinguishing reruns from regrades by major/minor patch versions.
Why read this
AI score 57
The lecture notes break Agent evaluation down into task structure, verifier isolation, and version semantics, which can be transferred to engineering practices for self-built evals.
Topics
View original postCS 329Z: Engineering AI Agents Stanford / Fall 2026 @stanfordnlp https://t.co/ynvpE8PKFE Course positioning: the engineering discipline from "models" to "systems" Coverage: simple LLM pipelines → compound AI systems → autonomous Agents. The backgrounds of the three instructors are also highly complementary: @Diyi_Yang (Stanford NLP professor, human-computer interaction and social computing) @michaelryan207 (core contributor to DSPy, author of the automatic evaluation AutoMetrics) @jyangballin (author of SWE-agent / SWE-bench / SWE-smith, one of the most important researchers in the software engineering Agent field) # Course throughline: three major engineering challenges The three core questions that run through the entire course—decomposition, data, and evaluation. The 11 weeks of content basically unfold around these three lines and can be divided into five modules: Module 1: Building primitives (Week 2–3) · LLM as a building material: API/SDK (litellm), structured output, constrained generation, decoding strategies, test-time compute, context engineering, model selection and cost/latency trade-offs · RAG: embedding, vector stores, chunking strategies, hybrid retrieval, cross-encoder and ColBERT late interaction · Tool calling: function calling APIs, MCP (Model Context Protocol), tool design, code sandboxes, error handling and retries Module 2: Frameworks and design patterns (Week 3–5) · Framework layer: DSPy (signature / module / optimizer), LangChain/LangGraph, LlamaIndex, with the focus on "what the framework abstracts away vs. what you hand-write" · Design patterns: the taxonomy of workflow vs. agent, five composable workflow patterns, ReAct / plan-and-execute / reflection, "the scaffold itself is a design decision" · Memory architecture: short-term/long-term memory, memory as a tool action, the file system as externalized memory, cross-Agent memory (MemGPT, Mem0, Generative Agents) · Multi-Agent systems: orchestration patterns, handoff and state passing, and a very opinionated pair of contrasting readings—reading both AutoGen and "Why Do Multi-Agent LLM Systems Fail?" and Neubig's "Don't Sleep on Single-agent Systems" Module 3: Optimization (Week 5) · A panorama from prompts to fine-tuning: GEPA, MIPROv2, OPRO, TextGrad (prompt optimization); LoRA/QLoRA, distillation, RLHF/DPO (weight optimization); test-time scaling (inference compute) · The core issue is the decision framework: when to optimize prompts, when to optimize weights, and when to throw inference compute at it Module 4: Data and evaluation (Week 6–8)—the most substantial part · Data: three types of data—trace, demonstration, feedback; training data vs. evaluation data; the data flywheel; synthetic data; building datasets from Agent trajectories (SWE-smith) · Evaluation fundamentals: why eval is hard; the 4-tuple framework (request / environment / stopping criteria / scorer); properties of a good benchmark; tinyBenchmarks · Evaluation infrastructure: three types of graders, prompt design for LLM-as-judge and its known biases, pairwise vs. pointwise, the non-deterministic metrics pass@k vs. pass^k, harness design Module 5: Safety and frontiers (Week 8–11) · Safety: privacy risks of tool access, prompt injection (including indirect injection), red teaming, sandboxes and permission models, output guardrails, human-in-the-loop · Coding Agents: end-to-end architecture comparison of SWE-agent, Claude Code, and OpenHands · Proactive Agents: from reactive to proactive, General User Models (GUM), Next Action Prediction, and the mixed-initiative question of "when an Agent should act proactively and when it should wait" · Open problems: multimodal/web/computer-use Agents, scientific Agents, long-running architectures, production observability (tracing, monitoring, cost management) # Assignment design: build with one hand, evaluate with the other HW1: Build an Agent system from scratch (10%) Given a paper library, build an Agent that can retrieve and reason to answer scientific questions. · Part A: Use only litellm to hand-write RAG + tool calling + a ReAct-style Agent loop · Part B: Rebuild the key components with DSPy and reflect on what the framework abstracts away HW2: Evaluate an Agent (10%) Given a prebuilt Agent, design a complete evaluation suite: code-based graders, at least one LLM-as-judge, benchmark tasks built with the 4-tuple framework, and error analysis.
View original
CS 329Z: Engineering AI Agents Stanford / Fall 2026 @stanfordnlp https://t.co/ynvpE8PKFE 课程定位:从"模型"到"系统"的工程学 覆盖:简单 LLM 流水线 → 复合 AI 系统 → 自主 Agent。三位讲师的背景也高度互补: @Diyi_Yang(斯坦福 NLP 教授,人机交互与社会计算方向) @michaelryan207(DSPy 核心贡献者,自动评估 AutoMetrics 作者) @jyangballin(SWE-agent / SWE-bench / SWE-smith 作者,软件工程 Agent 领域最重要的研究者之一) # 课程主线:三大工程挑战 贯穿全课的三个核心问题——分解(decomposition)、数据(data)、评估(evaluation)。11 周的内容基本围绕这三条线展开,可以分为五个模块: 模块 1:构建基元(Week 2–3) · LLM 作为构建材料:API/SDK(litellm)、结构化输出、约束生成、解码策略、test-time compute、上下文工程、模型选型与成本/延迟权衡 · RAG:embedding、向量库、分块策略、混合检索、cross-encoder 与 ColBERT 后期交互 · 工具调用:函数调用 API、MCP(Model Context Protocol)、工具设计、代码沙箱、错误处理与重试 模块 2:框架与设计模式(Week 3–5) · 框架层:DSPy(signature / module / optimizer)、LangChain/LangGraph、LlamaIndex,重点是"框架抽象了什么 vs. 你手写了什么" · 设计模式:workflow vs. agent 的分类学,五种可组合 workflow 模式,ReAct / plan-and-execute / reflection,"scaffold(脚手架)本身就是设计决策" · 记忆架构:短期/长期记忆、记忆作为工具动作、文件系统作为外化记忆、跨 Agent 记忆(MemGPT、Mem0、Generative Agents) · 多 Agent 系统:编排模式、handoff 与状态传递,以及一个很有态度的对照阅读——既读 AutoGen,也读《Why Do Multi-Agent LLM Systems Fail?》和 Neubig 的《Don't Sleep on Single-agent Systems》 模块 3:优化(Week 5) · 从提示词到微调的全景:GEPA、MIPROv2、OPRO、TextGrad(提示优化);LoRA/QLoRA、蒸馏、RLHF/DPO(权重优化);test-time scaling(推理算力) · 核心问题是决策框架:什么时候优化 prompt、什么时候优化 weights、什么时候堆推理算力 模块 4:数据与评估(Week 6–8)——最有分量的部分 · 数据:trace、demonstration、feedback 三类数据;训练数据 vs. 评估数据;数据飞轮;合成数据;从 Agent 轨迹构建数据集(SWE-smith) · 评估基础:为什么 eval 难;4 元组框架(request / environment / stopping criteria / scorer);好 benchmark 的性质;tinyBenchmarks · 评估基础设施:三类 grader、LLM-as-judge 的 prompt 设计与已知偏差、pairwise vs. pointwise、非确定性指标 pass@k vs. pass^k、harness 设计 模块 5:安全与前沿(Week 8–11) · 安全:工具访问的隐私风险、prompt injection(含间接注入)、红队、沙箱与权限模型、输出护栏、human-in-the-loop · Coding Agent:SWE-agent、Claude Code、OpenHands 的端到端架构对比 · 主动式 Agent:从 reactive 到 proactive,General User Models(GUM)、Next Action Prediction,以及"Agent 何时应主动、何时应等待"的 mixed-initiative 问题 · 开放问题:多模态/web/计算机使用 Agent、科学 Agent、长时运行架构、生产可观测性(tracing、monitoring、成本管理) # 作业设计:一手建、一手评 HW1:从零构建 Agent 系统(10%) 给定论文库,构建能检索并推理回答科学问题的 Agent。 · Part A:只用 litellm 手写 RAG + 工具调用 + ReAct 式 Agent 循环 · Part B:用 DSPy 重建关键组件,并反思框架抽象了什么 HW2:评估一个 Agent(10%) 给定一个预构建 Agent,设计完整评估套件:代码型 grader、至少一个 LLM-as-judge、用 4 元组框架构建 benchmark 任务、错误分析。
Body
CS 329Z: Engineering AI Agents Stanford / Fall 2026 @stanfordnlp https://t.co/Ko6UarsQff
来到了第 10 课「Evaluating Agents — Terminal-Bench and Harbor」, @alexgshaw @ryan_marten 来分享Terminal-Bench 与 Harbor 怎么把 Agent 当成可迭代工程。 https://t.co/OCrE9ETWQX
软件世界正从「规则是真相」(手写代码)转向「评测是真相」(agent 靠 eval 开发、软件再由 agent 生成)。Terminal-Bench 用终端任务把这套做成可跑的社区基准;Harbor 把同一套任务格式与基础设施产品化,让你自己造百万级 eval,不是只消费某一个榜。
从演绎到归纳:为什么 Evaluator 成了新角色 讲义先用软件史铺垫:机器码 → 汇编 → 高级语言(Hoare:程序性质原则上可从文本演绎出来)→ ML 的「输入+输出 → 规则」→ LLM → Agents。Shannon 的「真能思考、学习、操纵环境」那句话被用来收束:数字技术开发整体在变归纳。三层递进:模型从数据学;agent 靠评测养;软件由 agent 生成。于是 Specifier 仍是软件工程师,但 Evaluator 成为缺失的工种;规格的落点从「写规则」变成「写 evaluation」。
Terminal-Bench:bash 当「万能工具」的基准 核心洞察:终端里几乎什么都能干(对比一长串 AWS CLI)。社区数字(讲义页):64 张 model card、171 贡献者、1k+ GitHub 参与、5k+ Discord、7M+ 次 benchmark run;首 commit 约 2025-01,Claude Code 约 2025-02 发布,时间线对应 coding agent 爆发与终端基准同窗。
任务解剖示例:把 /app/schematic.png 的 2D 示意图变成 /app/out.step,verifier 不是「看起来像」,而是一串几何断言(合法 STEP、水密、体积/表面积/惯性矩/凸包/拓扑/平均曲率等)。结构拆成:INSTRUCTION.MD + ENVIRONMENT/DOCKERFILE + TEST/…。
共用词汇(任务怎么长什么样) Task / Trial / Benchmark / Verifier(Grader) / Trajectory(Trace) / Evaluation harness / Agent harness。任务目录约定为 agent 无关、易定义、可移植: instruction.md · task.toml · environment/Dockerfile · solution/solve.sh · tests/test.sh
写任务要问:你在测什么、测对了吗?三条硬约束:指令与 verifier 对齐、防 reward hacking、真实/公平/有趣。指令要充分指定,同时尽量短、尽量像真人说话。环境尽量贴近 prod:真软件/多容器优于 mock;「开放世界/联网」有 tradeoff;能 bake 进镜像的网络依赖就 bake,减 flakiness。Verifier 是对环境状态的 outcome 分类器:看混淆矩阵;与 instruction 需求 1–1;程序化检查 + LLM judge 并用。
Reward hacking 与隔离 Agent 环境锁定、verifier 环境隔离、agent 代码执行隔离;产物从 agent env 交到 verifier env 再跑测试,避免 agent 改测试或摸到打分器。Oracle solution/ 用来调试 verifier/环境,动作应像 agent 会走的路径,忌 hardcoded 捷径。
Infra、QA、版本、结果 Eval infra:容错、可复现、可并行、本地/云 sandbox 可移植;rollout 覆盖 test/train/prod。Task QA:任务会以很微妙的方式坏掉;静态检查 + agentic 检查(agent judge、oracle agent、frontier agents、cheat agents,并对轨迹做 judge)。CI/CD 视角:任务就是软件,软件有 bug,用量带来 bug 报告、flakiness、infra 噪声、新模型新行为、假阴性、reward hacking;https://t.co/l8GwCDbhH1 上有版本与 issue 流。
版本语义(讲义三列)很实用: · 主版本 (x+1):改 agent 环境 → 整测重跑(新任务、欠/过指定 prompt、数据工具、资源) · 次版本 (y+1):改 verifier → 可 regrade(过严、清 hack、调 judge、减 flakiness、改奖励) · 补丁 (z+1):元数据 → 可 reuse(文档、钉依赖、修笔误、oracle 偶发) 结果要求:每一行都有完整收据,每 trial 的轨迹、日志、产物、奖励。