系列连载100 天系统学习 AI Agent 开发当前阶段Agent 基础与环境搭建今日目标真正理解并设计 Agent 工具调用的输入、输出与权限边界。前几天我们的精力都集中在“搞脑子”上——怎么写好 Prompt怎么让大模型做计划。但一个只能在终端里跟你聊天的程序充其量只是个 Chatbot。真正的 Agent 必须具备介入真实工作流的能力查数据库、调 API、读写文件、操作业务系统。今天我们就给 Agent 安上“手脚”。但核心不是盲目堆砌能力而是弄明白一件事如何给每一个工具画定清晰的权限和输入输出边界。1. 为什么边界比能力更重要很多新手刚接触 Agent 时喜欢直接把整个系统 API 扔给大模型结果 Demo 跑得很炫酷一上生产环境就出了大事故比如误删库、发错邮件。在现代的 Agent 架构比如基于 MCP - Model Context Protocol 标准中我们必须严格区分系统暴露给 AI 的能力Resource资源负责提供上下文比如读取一份本地的 API 文档或者查看当前的数据库表结构。Tool工具负责执行动作带有副作用或计算逻辑比如创建一条工单、执行一段搜索。Prompt提示词作为可复用的工作流入口。如果我们把“读取 500MB 日志文件”设计成了一个 Tool每次让大模型去调用并等待返回这就属于设计失误——它应该是一个 Resource。弄混这三者就会导致 Agent 的上下文爆炸或者权限失控。2. 实战练习设计三个标准工具为了不流于表面概念今天我们直接落实到一个具体的产物为 Agent 设计三个基础工具。这可以直接抄作业放到你的项目README或系统配置里。工具 1calculator本地计算器Agent 的数学计算经常出现幻觉我们需要一个稳定的外部计算器。定位纯计算无副作用。输入 Schema{expression:{type:string,description:需要计算的数学表达式例如 (15 20) * 3}}权限边界read_only只读/无状态操作。人工介入不需要。全自动放行。工具 2search_docs企业知识库搜索让 Agent 能够自己去查阅公司内部文档而不是盲猜。定位数据读取边界限定。输入 Schema{query:{type:string,description:搜索关键词或语义短句},limit:{type:integer,description:返回的文档片段数量最大不可超过 5,default:3}}权限边界仅限docs/public目录的读取权限。隔离敏感薪资数据。人工介入不需要。工具 3create_todo创建任务日程这是一个典型的“写入”操作也是最容易失控的环节。定位状态修改高风险操作。输入 Schema{task_title:{type:string,description:任务的简短标题},priority:{type:string,enum:[low,medium,high],description:任务优先级}}权限边界write_only仅限写入当前用户的日程表禁止修改或删除历史日程。人工介入必须Human-in-the-loop。工具生成 payload 后必须弹窗向用户请求确认“Agent 请求创建一条高优先级任务 [沟通新方案]是否允许”用户点击确认后才实际调用底层 API。3. 安全底线统一的审计记录只限制权限还不够。工具调用的每一步都必须留下不可篡改的“案底”。这里我定了一个基础的审计数据结构后面所有的 Tool 调用都会封装这个日志{timestamp:2026-07-08T10:00:00Z,agent_id:assistant_v1,tool_name:create_todo,action_type:execute,input_payload:{task_title:测试任务,priority:high},execution_status:pending_human_approval,// 关键记录当前卡点状态audit_event:record_request_and_result_status}4. 今日复盘与踩坑记录以前的误区认为给 Agent 接的工具越多越好恨不得把后台所有 API 封装成 Tool 丢给它。真实的教训工具太多会导致大模型“选择困难症”甚至乱调工具。大模型每次请求都会消耗 Token 去阅读 Tool 的描述太多的 Tool 会挤占核心逻辑的上下文。正确的姿势能做成 Resource 的坚决不做成 Tool。静态数据就乖乖挂载为上下文。高风险写操作必须拦截。像上面的create_todo把拦截器做在工具调用的中转层这是 Agent 走向生产环境的及格线。
系列连载100 天系统学习 AI Agent 开发当前阶段Agent 基础与环境搭建今日目标真正理解并设计 Agent 工具调用的输入、输出与权限边界。前几天我们的精力都集中在“搞脑子”上——怎么写好 Prompt怎么让大模型做计划。但一个只能在终端里跟你聊天的程序充其量只是个 Chatbot。真正的 Agent 必须具备介入真实工作流的能力查数据库、调 API、读写文件、操作业务系统。今天我们就给 Agent 安上“手脚”。但核心不是盲目堆砌能力而是弄明白一件事如何给每一个工具画定清晰的权限和输入输出边界。1. 为什么边界比能力更重要很多新手刚接触 Agent 时喜欢直接把整个系统 API 扔给大模型结果 Demo 跑得很炫酷一上生产环境就出了大事故比如误删库、发错邮件。在现代的 Agent 架构比如基于 MCP - Model Context Protocol 标准中我们必须严格区分系统暴露给 AI 的能力Resource资源负责提供上下文比如读取一份本地的 API 文档或者查看当前的数据库表结构。Tool工具负责执行动作带有副作用或计算逻辑比如创建一条工单、执行一段搜索。Prompt提示词作为可复用的工作流入口。如果我们把“读取 500MB 日志文件”设计成了一个 Tool每次让大模型去调用并等待返回这就属于设计失误——它应该是一个 Resource。弄混这三者就会导致 Agent 的上下文爆炸或者权限失控。2. 实战练习设计三个标准工具为了不流于表面概念今天我们直接落实到一个具体的产物为 Agent 设计三个基础工具。这可以直接抄作业放到你的项目README或系统配置里。工具 1calculator本地计算器Agent 的数学计算经常出现幻觉我们需要一个稳定的外部计算器。定位纯计算无副作用。输入 Schema{expression:{type:string,description:需要计算的数学表达式例如 (15 20) * 3}}权限边界read_only只读/无状态操作。人工介入不需要。全自动放行。工具 2search_docs企业知识库搜索让 Agent 能够自己去查阅公司内部文档而不是盲猜。定位数据读取边界限定。输入 Schema{query:{type:string,description:搜索关键词或语义短句},limit:{type:integer,description:返回的文档片段数量最大不可超过 5,default:3}}权限边界仅限docs/public目录的读取权限。隔离敏感薪资数据。人工介入不需要。工具 3create_todo创建任务日程这是一个典型的“写入”操作也是最容易失控的环节。定位状态修改高风险操作。输入 Schema{task_title:{type:string,description:任务的简短标题},priority:{type:string,enum:[low,medium,high],description:任务优先级}}权限边界write_only仅限写入当前用户的日程表禁止修改或删除历史日程。人工介入必须Human-in-the-loop。工具生成 payload 后必须弹窗向用户请求确认“Agent 请求创建一条高优先级任务 [沟通新方案]是否允许”用户点击确认后才实际调用底层 API。3. 安全底线统一的审计记录只限制权限还不够。工具调用的每一步都必须留下不可篡改的“案底”。这里我定了一个基础的审计数据结构后面所有的 Tool 调用都会封装这个日志{timestamp:2026-07-08T10:00:00Z,agent_id:assistant_v1,tool_name:create_todo,action_type:execute,input_payload:{task_title:测试任务,priority:high},execution_status:pending_human_approval,// 关键记录当前卡点状态audit_event:record_request_and_result_status}4. 今日复盘与踩坑记录以前的误区认为给 Agent 接的工具越多越好恨不得把后台所有 API 封装成 Tool 丢给它。真实的教训工具太多会导致大模型“选择困难症”甚至乱调工具。大模型每次请求都会消耗 Token 去阅读 Tool 的描述太多的 Tool 会挤占核心逻辑的上下文。正确的姿势能做成 Resource 的坚决不做成 Tool。静态数据就乖乖挂载为上下文。高风险写操作必须拦截。像上面的create_todo把拦截器做在工具调用的中转层这是 Agent 走向生产环境的及格线。
