AI Agent: Design Principles and Engineering Practice is an open-source book that explains how AI agents combine language models, context, and tools, with accompanying experiments and code. It is intended for readers studying the principles and engineering of AI agents, from fundamentals through production use. The catalogue skills support coding-agent work related to the book's subject matter.
Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add bojieli/ai-agent-book --skill eval-dataset-designgit clone --depth 1 https://github.com/bojieli/ai-agent-bookWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/bojieli/ai-agent-book/eval-dataset-design)<a href="https://agentmods.dev/skills/bojieli/ai-agent-book/eval-dataset-design"><img src="https://agentmods.dev/badge/skills/bojieli/ai-agent-book/eval-dataset-design/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/bojieli/ai-agent-book/eval-dataset-design"><img src="https://agentmods.dev/badge/skills/bojieli/ai-agent-book/eval-dataset-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00138 | $0.03041 |
| Opus 5.5 | $0.00055 | $0.01216 |
| Sonnet 5 | $0.00028 | $0.00608 |
| Haiku 4.5 | $0.00014 | $0.00304 |
Grade A, and why
eval-dataset-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 88 lines — stays where its author put it; the contents beside it link to each section on GitHub.
评估数据集设计
何时使用
- 从零设计评估集,或评审现有任务定义是否站得住
- 为 Agent 编写单条评估任务:工单、用户模拟规范、初始状态、验收标准
- 设计验证器:该断言终态、断言动作,还是检查必须告知用户的信息
- 评估任务被模型"猜答案"蒙过,需要提高信噪比
- 怀疑评估集已被污染/泄漏进训练数据,需要防泄漏与检测手段
- 决定自建评估集的任务从哪来:公开基准、业务集、还是生产失败回流
- 评估集上线后需要长期维护:修补环境、描述、验证逻辑与初始状态问题
核心原则
- 一条评估任务 = 四个部分:给 Agent 的工单、给模拟器的行为规范、两侧状态的初始重置、成功判定标准。缺任何一部分,任务都无法重复运行。
- 把用户的认知边界建模为独立字段,而非靠提示词约束。 用户不知晓的信息 Agent 无从推测,只能通过提问与引导获得——渐进式信息透露不是一句"不要一次说完",而是
known_info与task_instructions的拆分。 - 没有事实锚定的用户模拟器会让评估退化为两个模型相互确认。 模拟用户关于环境状态的任何回答都必须以工具返回为依据,不许编造工具结果;否则 Agent 稍加引导,用户就确认"问题已解决"。
- 验证器必须核实机器可独立复核的事实,不能采信 Agent 的自我陈述。 Agent 很容易写一篇"任务已全部完成"的报告而实际什么都没做。
- 训练集与评估集严格隔离。 答案不可从互联网直接检索、任务实例参数化生成、嵌入 canary 使泄漏可检测——三招至少用一招。
- 验收口径要有可核实的边界,防"敷衍性修复"。 "网络已恢复"不可核实;"测速评级 excellent 才算解决,poor/fair/good 均不接受"才堵得住压制症状、不除根因的糊弄。
- 高质量的评估集是修出来的,不是写出来的。 主流基准的现行形态都是初版暴露问题后逐轮修补的结果;发布前人工淘汰、发布后持续修两类问题都要预算。
- 每道题亲手做一遍。 做完问两个问题:描述是否有多种合理解释,验证器认可哪一种?蒙混过关的最低成本路径是什么,验证器拦得住吗?
- 难度分层让评估集不过时,且每层失败指向不同改进方向:基础层失败指向工具使用,中间层指向多步规划,最高层指向长序列思考。
实践模式
1. 任务解剖:四件套字段清单
以 τ²-bench telecom 一条真实任务为范本,逐项对照自建任务:
- ticket(给 Agent 的工单):只含用户会主动说出的部分。真实用户的初始表述往往只是"我上不了网",把需求澄清到可执行的程度本身就是 Agent 必须具备的能力。
- user_scenario(给模拟器的行为规范):
known_info界定用户知悉范围(姓名、号码、所在国),故障原因不在其中;task_instructions规定透露方式,并包含三类约束——情绪设定(首次修复失败后表现不满)、验收口径(仅 excellent 算解决)、事实锚定(设备状态回答必须基于工具结果)。 - initial_state(初始重置):
initialization_actions把两侧状态重置到同一起点,包括用户侧(飞行模式、漫游开关)与 Agent 侧(运营商侧配置)。 - evaluation_criteria(成功判定):四个可检查维度按需组合,外加聚合规则。
2. 四维校验与聚合规则
env_assertions验终态:移动数据可用、测速达 200 Mbps 且评级 excellent。actions验关键动作是否发生(哪些工具被哪一侧调用)。communicate_info/nl_assertions验必要信息是否已告知用户——别只查环境状态。reward_basis是聚合规则。二元奖励(只看终态)以过程颗粒度换取跨模型可比的单一数字:满分轨迹里违反"一次只做一个工具调用"的政策也不会被捕获。生产评估系统需要更多:不仅判对错,还要指出问题出在哪。
3. 验证器设计的三种模式
- 双命题验证(SWE-bench Verified):FAIL_TO_PASS(修复前失败、修复后通过,证明问题确已解决)+ PASS_TO_PASS(修复前后均通过,证明未引入新缺陷)。只验前者,Agent 可以删改妨碍通过的断言蒙混;只验后者等于未检验。另需排除自身不稳定的 flaky test。
- 深状态核查(OSWorld 式):134 个独立评估函数,拥有完整系统访问权限,查文件系统结构、进程状态、网络连接与应用内部状态;数据库任务连库核实 SQL 是否真执行,浏览器任务分析 DOM、cookie 与 localStorage 并向后端发验证请求——能抓住"表面完成、实质错误"。
- 不可伪造执行(Terminal-Bench 式):成功标准是真实构建并运行(如从源码构建内核并在 QEMU 启动日志出现自定义 printk),Agent 无法伪造输出,只能真做完全流程。
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- yesterday First seen · 88 lines · 138 tokens per session scan A 26dce0ca97c8
eval-dataset-design is a skill published in the GitHub repository bojieli/ai-agent-book (50,785 stars, last pushed today), licensed Apache-2.0. It adds 138 tokens to every session and 3,041 once invoked, about $0.0006 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-24.
Other skills, from other repositories
11-browser-qa
Run post-review browser QA and produce short named videos for a locked happy path and sourced browser edge cases. Use when the user wants concise reviewer evidence for a web journey. Not for API, CLI, automated tests, diff review, or application fixes.
06-test
Write and iterate tests until they pass, or validate a user journey end to end in the browser. Use when the user wants to add coverage, find what's untested, or walk a flow. Not for auditing test health or debugging a failure.
e2e-setup
Set up Playwright e2e automation tailored to this team and app. Probes the running app (auth mechanism, API surface, spec availability), interviews with recommendations instead of open questions, scaffolds the playwright/ folder, and records every decision in playwright/AUTOMATION.md for the other e2e skills to read.…
test-cases
Generate test cases from a Jira ticket's acceptance criteria. Produces e2e test scenarios (steps and expected results, no code) and a unit test checklist for developers. Test cases map back to requirements for traceability. Use when: "write test cases", "generate tests", "e2e tests for PROJ-789", "test cases for this…
verify-fix
Re-test a bug fix after a developer resolves it. Pulls the original bug from Jira, re-executes the repro steps in the browser, checks for regressions, and updates the bug status. The final step in the SDT workflow before a ticket moves to Done. Use when: "verify fix", "retest", "is this fixed?", "check BUG-123"…
e2e-pom
Build and maintain Page Object Models by live element discovery — never by guessing selectors. Build mode pairs with the user: derives the element inventory from test cases, proves every locator against the running app, and confirms with highlighted screenshots before anything enters the POM. Heal mode runs…