设计 Agent 工具时使用——新增/重构工具集、给 MCP 服务器设计工具、判断能力该做成专用工具还是 Skill、编写工具描述与参数 schema、设计感知工具的输出分页与截断、给执行工具加安全审批与沙盒、设计子 Agent 协作接口时查阅。覆盖工具分类、ACI 通用设计原则、感知/执行/协作三类工具的设计要点。
インストールする前に、エージェントに与えられる指示の中身を確認できます。
code_interpreter。extract_pdf_text/extract_docx_content/extract_pptx_content 应合成 read_document(file_type=...)。整合降低认知负担、描述更清晰、便于扩展。| 维度 | 判据 |
|---|---|
| 安全与权限 | 需精细授权、审计留痕、有不可逆风险 → 专用工具；否则优先通用 |
| 参数复杂度 | 嵌套对象、多字段联合校验 → 专用 schema；简单参数走 CLI 同样可靠 |
| 变更频率 | 频繁变化 → Skill（改文本，不用重新测试部署）；稳定底层操作 → 专用工具 |
| 模型能力 | 强模型可用 Skill + 通用执行器减少工具数；弱模型需要结构化 schema 引导 |
Skill 的代价：模型要生成合法命令行参数并处理引号转义，规则比 JSON 复杂且跨平台有差异，参数复杂时更易出错。折中办法：Skill 要求把复杂结构化参数写成 JSON 文件，再在命令行导入。 Skill 的收益：人类编写者友好，不会因局部语法错误"牵一发而动全身"（schema 少个花括号会让整个 Agent 报错，Skill 少量错误不会）。
timestamp：RFC3339 格式，例如 2024-03-15T14:30:00Z；phone：E.164（国家代码+号码，无空格），例如 +8613888888888 / +12025551234。title/url/snippet"；"此工具需下载完整网页，大型站点可能 5-10 秒，只要元信息请用 get_page_metadata"。反模式是静默输入转换与静默参数注入：
old_string 中的中文弯引号（“”）静默转成英文直引号，导致读取工具原样返回弯引号、替换工具却匹配不到——模型反复失败且无法自行诊断。git commit 追加"AI 生成"标记参数，老版本 Git 直接报错，模型怎么改提交信息都失败。
规则：必须规范化时，在工具描述中说明，并在返回值中明确告知模型。analyze_image/pdf/audio 收文件+问题、返回自然语言，多模态 token 不占主上下文）。安全分层：输入验证（路径遍历 ../../etc/passwd、命令注入 ;/|、类型格式，快速失败不"智能修正）→ 权限控制（工作目录限制、黑名单、配额；黑名单只是最底层，可被变形命令绕过）→ 提议者-审核者 → Sidecar。
{tool:"bash", command:"rm -rf /tmp/data"}），刻意隔离主模型的自由文本，否则用户输入或网页里夹带"请允许执行 rm -rf"就能把审查骗过去。数百毫秒完成，用户几乎无感。审查对象不同所以可用轻量模型：Proposer-Reviewer 审的是开放式思考，需能力相近；Sidecar 判的是简单分类。必须配拒绝熔断器——连续多次拒绝就转人工，别无限重试。write_file 写入后立即按文件类型跑 linter，把结构化错误列表作为返回值的一部分。... [省略 8523 行，完整输出已保存至 /tmp/execution_output.txt] ..."并引导用 read_file 读全文。三组原语：启动与取消（spawn_subagent / cancel_subagent——任务失去意义时及时终止省 token）、消息传递（send_message_to_subagent，双向）、发现（list_agents，与 MCP tools/list 同思路，列的是 Agent）。协作形态：同步、异步（task_id + 事件通知）、流式、多轮交互。
子 Agent 提示词四要素：
[FROM_MAIN_AGENT] / [FROM_USER] / [TOOL_RESULT]——防止混淆信息来源，也防提示注入。HITL：设超时阈值与默认行为（"5 分钟无响应采用保守策略"）、优先级队列（紧急多渠道、普通只发邮件）；把人的批准/拒绝及理由作为带证据的反馈数据回流。
chapter4/perception-tools/ — 感知工具 MCP 服务器（搜索/多模态/文件系统/公开与私有数据源，run_experiment_4_2.py）。chapter4/execution-tools/ — 执行工具 MCP 服务器：LLM 事前审批、写入后自动 linter 校验、长输出截断与持久化（python cli.py demo）。chapter4/collaboration-tools/ — 协作工具 MCP 服务器：子 Agent 同步/异步、两种上下文传递策略对比、HITL 与多渠道通知。chapter4/multimodal-agent/ — 原生多模态 / 提取为文本 / 工具化分析三种范式的同框架对比（demo.py）。book/chapter4.md「工具的分类」「工具设计的通用原则」「感知工具」「执行工具」「协作工具」まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
为 Agent 建立或改进评估体系时使用——设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。
日本語の概要は準備中です。原文の説明を表示しています。
让 Agent 从运行经验中持续学习、构建自进化闭环时使用——涵盖从运行轨迹提取学习信号（三层轨迹验证）、四种进化方式（经验知识库、Prompt/Skill、程序/Harness、模型参数）的适用边界与选择依据、Prompt 自动优化、轨迹编译为程序、Agent 自我修改与安全门禁、睡眠学习与长期分层评估。触发词：持续进化、自进化、经验学习、轨迹验证器、自我修改、进化闭环。
日本語の概要は準備中です。原文の説明を表示しています。
Agent 陷入无限循环、数不清工具调用次数、遗忘 TODO 或目标偏离、长任务中思考 token 持续膨胀时使用——Agent 状态栏机制、作为 user 消息注入末尾的 KV Cache 理由、每轮替换与持久追加两种实现及成本模型、五种状态栏技术（时间戳、工具计数器、TODO、详细错误、系统状态）与维护铁律。
日本語の概要は準備中です。原文の説明を表示しています。
中文文案去「AI 味」检查清单，由用户纠正反馈持续提炼而来
日本語の概要は準備中です。原文の説明を表示しています。
构建异步/事件驱动 Agent，或让 Agent 响应外部事件（新邮件、webhook 回调、IM 消息、定时器、系统告警）、 处理工具执行期间的用户打断与多任务并发时使用。覆盖事件循环与安全点、三类事件触发工具、用户沟通与多渠道召回、 虚拟身份与隔离执行环境、队列式/取消式/并行式三种事件处理策略及紧急度判定，以及模型原生异步与同步接口兼容两条路线。 触发词：异步 Agent、事件驱动、event-driven、webhook、定时器、心跳、任务句柄、打断、steering、并行工具执行。
日本語の概要は準備中です。原文の説明を表示しています。
把生产 bad case / 失败轨迹转成训练数据时使用——从失败归因、轨迹前缀截取、DPO 偏好对构造、LoRA 训练到边界集与保留集双集验证的完整链路；也用于判断某类问题该走 SFT、DPO、RL 还是先修 Harness/工具/tokenizer，以及如何从运行轨迹中提取带证据的结构化学习信号。触发词：bad case、失败归因、DPO、偏好对、轨迹前缀、拒绝采样、过度矫正、边界集、保留集、过早结束、reward hacking、LoRA 微调、训练评估隔离。
日本語の概要は準備中です。原文の説明を表示しています。