为什么你的Agent工具设计很危险？agents-best-practices教你用细粒度类型化工具彻底规避

【免费下载链接】agents-best-practicesProvider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.项目地址: https://gitcode.com/gh_mirrors/ag/agents-best-practices

你的 Agent 为什么总是"一出手就出事"？答案往往藏在工具设计里。agents-best-practices是一个 Provider 中立的 Agent Skill，专为 Codex、Claude Code 等智能体运行时设计，核心之一就是教你用**细粒度类型化工具（narrow typed tools）**替代宽泛危险的接口，让 Agent 工具设计从一开始就远离安全隐患。

一、宽泛工具设计，为什么危险？

很多 Agent 项目习惯给模型几个"万能工具"：

• execute_anything(command)
• call_api(url, method, body)
• update_database(sql)
• send_message(payload)

听起来方便，实际上等于把整个系统裸奔交给模型。tools-and-permissions.md 开篇就强调：工具是模型与 harness 之间的契约，模型只能"提议"，执行权必须留在应用代码侧。宽泛工具的问题在于：

换句话说：模型提议动作，harness 负责校验、授权、执行、记录并返回观察——这就是整个项目的核心哲学。

二、细粒度类型化工具的正确打开方式

1. 用领域语义取代通用接口

同样的业务需求，换一组窄工具后风险立刻收敛：

• search_policy_docs(query, max_results)代替call_api
• read_customer_account(account_id)代替update_database
• draft_customer_email(case_id, tone)+request_refund_approval(order_id, amount, reason)代替send_message

每个工具都应该声明：名称、用途、输入/输出 schema、风险等级、副作用、资源范围、权限策略、超时、结果大小上限、重试与审计策略。这套完整契约清单就写在 tools-and-permissions.md。

2. 给每个工具打上风险分类标签

项目提供了一套 14 级风险分类法（risk taxonomy），从read_only、draft_only到financial、destructive、privileged_admin。工具注册表把风险元数据暴露给权限引擎，权限引擎返回的是明确的决策：允许、拒绝、询问用户、需要审批、需要更强认证、进沙箱执行或仅允许草稿。

3. Draft 与 Commit 必须分开

这是规避高危操作最关键的一步。把每个有风险的动作拆成"草稿 + 提交"两个独立工具：

• draft_email→send_email
• prepare_refund→issue_refund
• propose_record_update→apply_record_update

草稿工具可以自动运行，提交工具必须走提示词之外的审批记录。这样即使模型被提示注入带偏，真实副作用也不会悄悄发生。

4. 结构化结果，拒绝"巨型原始数据"

工具返回值也应该是类型化的：状态、摘要、条目列表、以及下一步合法动作（next_valid_actions）。哪怕是失败，也要返回permission_denied、timeout这类结构化错误，并告诉模型安全的下一步。checklists.md 中的 Tool checklist 要求每个工具逐项通过 schema 校验、风险分级、副作用声明、超时与输出上限检查，可直接当作落地清单使用。

三、权限矩阵：按风险等级授权，而非一刀切

项目给出的默认权限策略非常清晰 🛡️：

• 公开读取：允许
• 私有数据读取：仅限用户/会话范围内
• 草稿类操作：允许
• 外部通信：先草稿，审批后发送
• 财务动作：审批 + 强认证
• 破坏性操作：默认拒绝，或审批 + 恢复计划
• 进程执行：沙箱 + 白名单 + 超时

这套矩阵与 mvp-agent-blueprint.md 中的"最小类型化工具注册表"配合使用——MVP 阶段只保留最少的窄工具（如read_account_profile、list_support_tickets、request_approval），而不是一开始就铺满整个 API 面。

四、快速上手：3 步把技能装进你的 Agent

第 1 步：把仓库克隆到智能体可读取的 skills 目录：

git clone https://gitcode.com/gh_mirrors/ag/agents-best-practices.git

第 2 步：放入对应运行时目录，例如 Codex 的~/.codex/skills/或 Claude Code 的~/.claude/skills/，确认 SKILL.md、icon.jpeg 和references/目录完整。

第 3 步：当对话涉及工具权限、harness 设计或 Agent 审计时，技能会自动激活，帮你生成 MVP 蓝图、审计现有 harness、输出工具与权限设计。完整安装与使用说明见 README.md。

五、上线前自查：一张清单守住底线

发布前对照 checklists.md 逐条确认，重点包括：

• 最小类型化工具注册表已定义
• 权限矩阵覆盖读取、草稿、写入、外部通信、财务、破坏性与特权操作
• 高风险动作完成 draft/commit 分离
• 外部发送、财务动作、破坏性动作均受审批门控
• 计划模式在批准前阻止任何变更

总结

Agent 工具设计的安全边界，不靠提示词里的一句"注意安全"，而靠细粒度类型化工具 + 风险分类 + 运行时权限决策这套工程纪律。agents-best-practices 把这套纪律沉淀成了可直接复用的参考文档与技能：先跑通单 Agent MVP，再根据实测失败逐步加自主权——让模型负责提议，让 harness 负责把关，你的 Agent 才敢真正接入生产系统 ✅

【免费下载链接】agents-best-practicesProvider-neutral Agent Skill for Codex, Claude Code, and agentic harness design.项目地址: https://gitcode.com/gh_mirrors/ag/agents-best-practices