先说明一下背景最近我在做一个内部项目打算给一个基于大模型的 Agent 增加“动手能力”让它不只会聊天还能自己去查资料、查业务数据、读写文件。当时定下来的方向就是三个搜索、数据库、文件系统。这三样接入下去Agent 的能力边界立刻就不一样了。但整个过程远没有想象中那么顺。踩了不少坑之后我整理了一套自己的方案和注意点写出来给正在做 Agent 开发的朋友做个参考。如果你正准备接搜索 API、让 Agent 查数据库或者给它挂一个自己的“手”去操控文件这篇应该对你有用。1. 先想清楚Agent 要这三样能力到底解决什么问题一开始容易犯的错是把“接入工具”当成目的觉得给 Agent 接上搜索、数据库、文件系统就完事了。实际上这三样东西解决的是完全不同的三类问题你接之前必须分清楚因为后续的接口设计、权限控制、错误处理全都不一样。1.1 搜索解决的是“实时信息缺失”问题大模型的知识有截止日期它不知道今天发生了什么也不知道某个产品现在的价格、某个仓库最新的代码状态。搜索能力本质上是在模型和互联网之间架一根管子需要的时候实时抓取。搜索接入要解决的核心问题不是“能不能搜到”而是返回结果怎么处理才不污染模型的上下文怎么从海量结果中提炼出模型真正需要的那几段搜索质量和模型回答质量之间的平衡怎么掌握1.2 数据库解决的是“私有数据读取与写入”问题这个好理解。业务系统数据不会进模型训练集Agent 要回答“我们上个月各区域的销售额”只能实时查库。数据库接入比搜索更敏感因为涉及权限和写入——你肯定不想让 Agent 不小心 DELETE 一张生产表。1.3 文件系统解决的是“让 Agent 拥有工作空间”问题这个很多人容易忽略。Agent 不只是需要一个“问问题”的接口它执行任务的过程中可能需要读一个用户上传的 CSV 文件再分析把生成的结果保存成本地文件批量整理某个目录下的文件文件系统接入让 Agent 真正有了“身体”能操作实际存在的资源。但这一点也是最容易被安全漏洞盯上的——后面我会细讲。理清楚需求之后下一步是确定技术路线。这里我必须强调一个原则能用工具函数解决的不要强行让模型自己来。2. 搜索接入别小看一个联网检索坑全在“返回内容”上搜索接口本身接入不难难在怎么设计返回给模型的内容结构。很多初做 Agent 的人直接把搜索结果整段塞进模型上下文里结果模型被一堆广告和无关链接带偏回答质量反而下降。更糟糕的是搜索结果里混入的低质量内容可能会让模型产生严重的幻觉。2.1 接口封装从“搜到结果”到“模型能用的结果”以常见的搜索 API 为例你包装成一个web_search(query, max_results)函数后不要直接返回原始结果列表。建议做三层加工截断 title 和 snippet避免超长内容占据上下文过滤掉明显低质的页面比如一些内容农场站点把结果压缩成结构化文本按相关度排序再传给模型我自己常用的返回格式是搜索结果: 项目标题 1. 标题: xxx | 来源: xxx | 摘要: xxx 2. 标题: xxx | 来源: xxx | 摘要: xxx ...这样一个搜索结果函数返回给模型的内容最多占用不到 2000 token模型不需要自己再翻一遍原始结果做判断效率和准确率都提升不少。2.2 搜索时效窗口给模型一个“时间认知”我发现很多 Agent 接入搜索后依然答不出“最近发生了什么”原因是模型根本不知道自己现在处于什么时间点。你接入搜索后必须额外在系统提示词或上下文里注入当前日期时间否则模型会把“过去的知识”和“搜索到的信息”混在一起。我通常在 Agent 初始上下文里注入一行当前日期: 2025-02-15 (UTC) 你进行的搜索结果是实时的请优先使用搜索结果来回答涉及最新信息的问题。这样模型才能正确判断哪些知识是过时的哪些是刚查到的。2.3 多轮搜索的上下文管理还有个大坑Agent 第一次搜索后模型基于结果提出了一个追问然后触发第二次搜索此时第一轮的搜索结果要不要保留我实测下来建议只保留最近两轮的搜索结果摘要更早的搜索结果直接丢弃。因为模型可能会被陈旧的结果干扰判断力直线下降。保留太久的结果还会撑爆上下文窗口导致对话历史被提前截断。技巧是给搜索函数增加一个search_id参数每次搜索的结果连同搜索序号一起存入一个临时“信息区”并告诉模型“只有信息区中带有当前搜索序号的内容才是最新结果”。搜索只是第一步。真正让 Agent 发挥业务价值的是数据库接入。但这里面的风险比搜索高一个数量级。3. 数据库接入让 Agent 写 SQL 不是选模型是设计护栏先给结论**不是所有场景都该让 Agent 写原生 SQL。** 如果业务逻辑足够固定比如查订单、查库存用“意图识别 参数抽取 预编译查询”的方式远比“让模型自由生成 WHERE 子句”要安全高效得多。我把这两种方式分别称为“受限查询”和“自由查询”。3.1 受限查询低风险场景的首选所谓受限查询是只允许 Agent 从少量预定义的表和字段中选择配合预设的查询模板来做。好处是模型几乎不可能生成灾难性的 SQL因为它根本没有自由拼 SQL 的空间。举个例子假设你有一个学生信息表你想让 Agent 回答“xx 班有多少人”识别意图查人数抽取参数班级 “三班”拼装模板SELECT COUNT(*) FROM students WHERE class ?参数化执行模板内的查询方式是固定拼装完成的Agent 无法修改 SELECT 后面的字段也无法添加 DELETE 或 UNION。这个方式实现简单也稳定。但缺点也很明显——只能回答预设范围内的问题Agent 想查“各班男女比例”就只能报“暂时不支持”。3.2 自由查询让 Agent 写 SQL 的护栏设定有些场景确实需要 Agent 自由写 SQL比如数据分析师 Agent但你绝不应该让它直连生产库。我的方案是三层护栏第一层只读账号给 Agent 使用的数据库账号一律只授予 SELECT 权限。这是最重要的一道防线确保 Agent 搞不出 DELETE、DROP 之类的事。第二层SQL 静态检查Agent 生成 SQL 后在发送给数据库之前先用正则和关键词检查黑名单比如DELETE、DROP、ALTER、TRUNCATE、GRANT、REVOKE、--、/* */注释符等。发现就直接拦截并反馈给 Agent 要求重写。第三层LIMIT 强制注入就算模型写了SELECT * FROM students我们也要在后面自动追加LIMIT 100可配置防止返回超大数据集。不只防模型也防手滑。我还用过一个更稳妥的做法使用 SQL 解析器来解析模型生成的 SQL然后生成一个语法树只允许白名单节点类型。这个方案成本高一些但对金融、医疗这类对准确性要求极高的场景非常值。3.3 数据库 Schema 注入不能全塞也不能完全不塞有了安全护栏后要解决下一个问题模型怎么知道数据库里有什么表、有什么字段第一种做法不推荐把所有表和字段信息全塞进系统提示词看起来很直接但数据库表一多比如几百张表光 schema 描述就会占掉几千 token模型很快就“记不住”新信息了而且找一张表的准确字段需要模型在一堆噪音里挑容易出错。第二种做法推荐用“软 schema”方式按需注入系统提示词里只放核心表的概要同时在函数说明中声明参数格式引导模型先“查看表结构”再“生成查询”。具体是提供两个函数list_tables()返回数据库中所有表名describe_table(table_name)返回某张表的字段、类型、样例值注意可以故意做脱敏模型不确定字段名时会先调用 describe_table 去查再写 SQL。这样上下文占用极小还能处理复杂库表结构。我在项目里就是这样实现的模型基本不需要把整个库表结构背下来只在需要的时候去查。带来的好处是Agent 走查表结构的频率变高了虽然多了一两次函数调用但 SQL 生成的准确率大幅上升。3.4 自然语言转 SQL模型也会犯蠢重试机制是必备接入的模型再强也难免会生成错的 SQL。我测试中发现常见的错有字段名拼错比如user_name写成username表名匹配错订单表叫orders它写成order_list把字符串比较写成数值比较JOIN 条件逻辑错误为了解决这个问题我给数据库工具加了一个错误反馈回路数据库报错时把原始错误信息和执行的 SQL 片段返回给 Agent并提示“请根据错误信息修正 SQL 后重试”。实测下来第二次生成的正确率能提高不少。前面的搜索和数据库本质上是帮 Agent “读取信息”。但真正让 Agent 能够完成一个完整任务的是文件系统——它需要能落地输出、能读取用户上传的家伙。4. 文件系统接入读不到权限、写不进缓存比你想的麻烦文件系统接入是所有工具里最容易被低估的。很多开发者做 Agent 接入文件系统时只做了一件事给 Agent 四个函数read_file、write_file、list_directory、delete_file完事。结果一上线就出问题Agent 删错了文件、读到了不该读的配置、把临时文件写满了磁盘。4.1 根目录沙箱隔离一切核心策略是给 Agent 单独划定一块工作目录比如/data/agent_workspace所有文件操作只能发生在这个目录内。实现上我在工具函数底层做了一个路径归一化处理比如def safe_join(base_dir: str, relative_path: str) - str: # 将相对路径解析为绝对路径并检查是否在 base_dir 内 target os.path.abspath(os.path.join(base_dir, relative_path)) if not target.startswith(os.path.abspath(base_dir)): raise PermissionError(Access denied: path escapes workspace) return target这样无论模型传入../../etc/passwd还是/etc/passwd都会被拦住。凡是涉及文件系统的工具函数必须统一走这个安全校验一个都不能漏。4.2 函数设计拆分读、写、列表、关于我最终保留了四个核心函数但每个都有额外设计和参数list_directory(path)返回目录条目文件名、大小、修改时间、文件/目录类型read_file(path, offset, limit)支持分块读取避免一次读超大文件把上下文撑爆write_file(path, content, append)支持追加模式和覆盖模式不要默认覆盖delete_file(path)只允许删除工作目录下的文件且回收站优先而不是直接删关于 read_file 为什么加 offset/limit因为 Agent 在分析一份很大的日志文件时如果一次性全读非常消耗上下文。让它先读前 100 行试探再按需读后续部分能大幅提升成功率。你也可以做成“head/tail”式的读取函数。4.3 写文件的命名冲突写文件时有个容易被忽视的坑文件名冲突。如果 Agent 要生成一份报告第一次生成了report.md第二次可能因为缓存或者重试覆盖了第一次的内容。解决方案是在 write_file 的参数里显式支持if_exists: overwrite | append | error默认是 error——如果目标文件已存在就明确告诉 Agent 选择后续策略或换一个文件名。这些设计看似琐碎但真到用的时候能省下不少调试时间。4.4 编码和格式陷阱Agent 输入文件时编码问题很容易炸。如果你的工作场景里有 Windows 用户上传的 CSVGBK 编码而 Agent 默认按 UTF-8 读取那解析出来全是乱码进一步导致后续的分析全部错误。建议 read_file 增加一个encoding参数并且默认做“编码嗅探”。代码层面可以用 Python 的chardet库识别文件编码后再解码然后在返回值中明确附带编码信息让 Agent 知道它读到的是哪个编码下的内容。能力都接上了最后一步是把它们协调起来。这三样工具不是“各自独立”它们之间常常有依赖关系——比如 Agent 先搜索到一些数据然后写入数据库再生成一个报告文件。这时候编排层就变成了一门学问。5. 三样工具一起上编排层如何避免 Agent“拆东墙补西墙”我把这些外部能力接入后测试了一轮端到端任务发现工具之间的协调比单个工具本身的稳定性更让人头疼。5.1 工具冲突同步问题与状态共享有一个最典型的场景Agent 从数据库查了一批数据生成 CSV 写到文件系统紧接着用户让它“更新刚才那份文件”而 Agent 没有记住文件的具体路径又去工作目录列了一遍目录。这个问题本质上是状态管理缺失——模型没有记忆跨步骤的文件路径、数据库查询ID、搜索结果ID。我在系统提示词里增加了一个“工作记忆区域”的约定让 Agent在每一步之后把关键信息比如刚才写入的文件路径记录在一个结构化的记忆区里。这样后续步骤可以直接从记忆区引用而不必重新查找。5.2 编排避免冲突先查库还是先搜索我在测试中发现Agent 接搜索 数据库时会出现一种混乱情况当用户问“帮我查一下 2024 年热门的 LLM 论文”Agent 可能先查数据库里面当然没有再搜索最后把两边的结果揉在一起回答造成引用混乱。解决方案是在系统提示词里明确工具优先级规则业务数据问题销售、订单、用户- 优先数据库实时信息和外部知识 - 优先搜索不确定时 - 先搜索确认再数据库补充模型看到这些规则后工具选择逻辑会清晰很多不再“拆东墙补西墙”。5.3 一个命令完成复杂任务链式编排模式当你确认工具协同逻辑稳定后可以尝试把常见流程固化成“领域工具”。比如我将“客户需求分析”做成一个组合工具内部逻辑是调用搜索查询该公司最新公开信息调用数据库读取该客户在本企业的历史交易记录生成分析报告并保存到文件系统这样模型只需要调用一次“分析客户需求”输出是固定的结构化报告比起让模型自己编排三步准确性和稳定性都会高非常多。6. 实测一轮下来我总结的工具接入检查和评估清单到这里我把自己整个项目里每个工具的设计思路都梳理完了。最后放出我做 Agent 工具接入时用来“验收”的检查清单你可以直接照抄使用。这个清单是我踩了很多坑之后总结出来的不一定全但基本够用。检查项说明验收标准工具描述是否清晰每个工具的 description 是否准确说明用途和参数限制模型能正确选择工具而不需要通过试错参数限制是否明确搜索结果条数、文件大小、LIMIT 值等是否显式声明模型不会尝试读取一个 1GB 的文件错误反馈是否完整工具报错流程是否把原因和修正建议返回给模型可以自动重试并修正权限边界是否锁死文件系统沙箱、SQL 只读、搜索域名白名单恶意输入无法越权访问上下文占用是否可控搜索结果、查询结果、文件内容是否限制长度长对话任务不会因为上下文爆炸中断状态是否可恢复Agent 是否能记住已打开的文件、已查询的ID多轮对话可以引用前一轮的结果超时和重试网络请求和数据库连接是否设置超时单次工具调用不会挂起超过10秒6.1 上线的第一个晚上我遇到的问题和修复上线跑了一晚上第二天我查看日志发现问题基本集中在三个方向第一搜索返回了被拦截或者不适合作为依据的内容。解决办法是增加了域名白名单把搜索 API 换成支持指定站点过滤的版本同时对搜索结果做一轮内容质量评估低质结果直接不返回给模型。第二数据库连接断开导致 SQL 执行失败。Agent 可能隔很久才发起下一次查询数据库连接早已超时。后来改成每个查询都走连接池并且查询前先做心跳检测问题消除。第三文件系统空间被 Agent 的多次写文件操作占满。我在文件写入时增加了空间预检如果剩余空间不足直接提示 Agent 清理临时文件或拒绝写入。如果你也在做类似的事情我的建议是别追求一步到位先把“搜索 一个只读数据库表 一个沙箱目录”这个最小闭环跑通再逐步加能力。每加一个工具都要做完整的权限评估和上下文占用评估别让工具成为新的副作用来源。工具接入完成后真正考验的不是“能不能调用”而是“调用后稳不稳定”。多花一点时间在错误处理、状态管理、边界检查上Agent 的生产力才会真正释放出来。