为什么你的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_apiread_customer_account(account_id)代替update_databasedraft_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_emailprepare_refund→issue_refundpropose_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考