系列连载：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 或系统配置里。

工具 1：calculator（本地计算器）

Agent 的数学计算经常出现幻觉，我们需要一个稳定的外部计算器。

• 定位：纯计算，无副作用。
• 输入 Schema：

{
  "expression": {
    "type": "string",
    "description": "需要计算的数学表达式，例如 '(15 + 20) * 3'"
  }
}

• 权限边界：read_only（只读/无状态操作）。
• 人工介入：不需要。全自动放行。

工具 2：search_docs（企业知识库搜索）

让 Agent 能够自己去查阅公司内部文档，而不是盲猜。

• 定位：数据读取，边界限定。
• 输入 Schema：

{
  "query": {
    "type": "string",
    "description": "搜索关键词或语义短句"
  },
  "limit": {
    "type": "integer",
    "description": "返回的文档片段数量，最大不可超过 5",
    "default": 3
  }
}

• 权限边界：仅限 docs/public 目录的读取权限。隔离敏感薪资数据。
• 人工介入：不需要。

工具 3：create_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 会挤占核心逻辑的上下文。

正确的姿势：

1. 能做成 Resource 的坚决不做成 Tool。静态数据就乖乖挂载为上下文。
2. 高风险写操作必须拦截。像上面的 create_todo，把拦截器做在工具调用的中转层，这是 Agent 走向生产环境的及格线。