手把手构建体验智能体：工具调用与决策循环实战解析

1. 早该聊聊的智能体：这轮体验到底在做什么

先把这个标题拆开说。20260310_110015这串字符不是随机编号，是我本地工作区里某个交互实验项目的自动命名，时间戳记录了那次会话启动的时刻。核心词其实只有四个字：体验智能体。所谓“体验智能体”，不是让你去用别人做好的聊天机器人，而是指这类以“工具调用+自主决策”为核心形态的小型 AI 应用——用户丢给它一个模糊目标，它自己拆解任务、挑选工具、执行动作、返回结果。这类东西在国内技术社区里也被叫 Agent、AI 代理、智能助手工作流，叫法很多，本质是一回事。

这轮开发的出发点很朴素：我想验证一下，在不开源大模型、不加复杂训练流程的前提下，单靠一个高亮 API 和一套清晰的工具注册机制，能不能做出一个“真的能干活”的智能体——比如帮我把一堆散落的经验笔记按主题重新归档，或者自动拉取某个页面的信息并生成摘要。这个方向现在非常热，但热度集中在概念和演示上，真正沉下来把调用链路捋清楚、把错误处理做扎实的文章很少。这篇就想补上这块，适合两类人：一是刚开始接触 Agent 开发、想上手但不知道从哪里搭骨架的初学者；二是已经跑过几个 Demo、正在为“功能有了但一跑真实任务就崩”而头疼的开发者。

先说结论：智能体开发的门槛真不高，两三天时间足够跑通一个端到端的 Demo；但真正的分水岭在于你有没有把“工具、记忆、决策循环”这三件事想透。这篇博文会从设计思路、参数计算、完整代码骨架到避坑清单都过一遍，你看完可以直接照着落到自己的项目里。

2. 先想清楚两件事：技术路线和智能体形态

2.1 技术选型：为什么是“大模型 API + 工具函数”而不是微调

开始写代码之前，我必须先做一个关键决策：到底用哪种方式构建智能体的“大脑”。市面上有三条主流路线，我逐一对比过：

说下为什么选第三条。微调路线的核心误区在于：很多人以为让模型学会“调用工具”的最好方式是给它看几千条调用样例。但实际上，主流大模型在预训练阶段已经见过大量函数调用数据，工具调用的“理解能力”是现成的。你真正缺的只是两样东西：一个是把外部能力暴露给模型的“工具描述层”，另一个是处理模型输出中工具调用指令的“执行器”。换句话说，你需要做的是“接口适配”，不是“重新教育模型”。

这就引出一个更底层的问题：工具调用到底是怎么实现的？现在国内开发者常用的大模型 API 基本都支持 Function Calling（函数调用）或 Tool Use（工具使用）协议，底层机制大同小异。你发送请求时，在消息里附加一个tools参数，里面用 JSON Schema 描述每个工具的名称、功能说明、参数结构；模型看完你的对话历史后，如果判断某个工具能帮助完成当前目标，就会在返回内容里带一个tool_calls字段，里面是它“想要调用”的工具名和参数字典；你的代码接住这个字段，执行真实函数，再把执行结果作为一条新的消息追加回对话，模型就能看到工具的执行效果，决定下一步是继续调用还是给用户最终答案。这一来一回，就是智能体最基本的“感知-决策-执行”闭环。

2.2 形态界定：我要做的是“单轮任务型智能体”而不是“多轮闲聊型”

选定了技术路线，接下来要明确智能体的交互形态。很多人一上来就想做“能聊天能干活的全能助理”，结果被多轮对话的上下文管理拖垮。我的建议是：第一个项目一定做单轮任务型，也就是用户一次提交目标，智能体自己循环处理直到完成，输出一份结果，然后本次会话结束。

我这次做的具体场景是：用户提供一批本地笔记文件路径，智能体读取内容、分析主题、生成新的归档方案，并输出一份整理后的目录建议。这个场景有几大好处：

• 目标明确，成功标准清晰：最后输出的归档方案质量好不好，一眼就能判断。
• 工具调用链完整但不复杂：总共需要 2-3 个工具，正好覆盖“读文件-分析-写结果”的完整链路。
• 对上下文长度要求低：单轮任务通常十几轮 tool call 就能完成，不会出现上下文爆炸。

如果是做多轮闲聊型（比如“帮我查天气，再帮我订个餐厅，什么时候有空位告诉我”），你还要处理会话历史截断、用户意图中途改变、任务暂停恢复等一堆复杂问题。这些不是入门该碰的。先把单轮任务跑通，你理解了工具调用的本质，再做多轮型只是加一个会话管理外壳而已。

3. 核心机制拆解：工具注册、决策循环与参数设计

3.1 工具描述层：模型不认识你的函数，只认识 JSON Schema

整个智能体系统里，最容易被低估的就是工具描述层。你的工具函数写得再好，如果描述写得含糊不清，模型就不知道什么时候该调它、参数该怎么填。我总结了一个描述编写三原则：

第一，功能描述要说清楚“什么时候用、什么时候不用”。比如读取文件的工具，我在描述里写的是“读取本地文件内容，当用户提到非结构化文本、笔记、文档时使用；如果用户要求下载网页内容，使用 fetch_url 工具而非本工具”。这样模型在做意图判断时不会选错。

第二，参数描述要写枚举值和边界。比如我做了一个analyze_sentiment（情感分析）工具，参数定义里我明确写了text参数的最大长度是 800 字符，超过部分会被截断。这一步看似多余，实际上避免了模型传一个超长文本进来，工具执行直接报错。

第三，避免对模型能力的无效假设。一开始我天真地认为模型会“理解”我的中文工具描述里的隐含逻辑，比如我在设置参数时写“folder_path 的格式应为 /path/to/folder”，结果模型真的传了一个~/notes/这种带波浪号的路径，我的工具函数没有做展开处理，直接报错。后来我在描述里补了一句“不支持 ~ 符号，请使用绝对路径”，问题就解决了。

下面是我这次体验中使用的实际工具注册代码，语言用的是 Python，框架直接裸调 API，没有用 LangChain 之类的封装库。原因很简单：第一次做智能体开发，应该清楚地看到请求-响应-执行这一整条链路，而不是被框架的抽象层挡住视线。等你理解了原理，再引入框架提升效率。

import json import os from datetime import datetime def read_file(filepath: str) -> str: """读取指定文本文件的内容。当用户提到笔记、文档、txt文件、本地内容时使用。 参数 filepath 必须为绝对路径，不支持 ~ 符号。 """ with open(os.path.expanduser(filepath), 'r', encoding='utf-8') as f: return f.read() def list_files(directory: str) -> list: """列出指定目录下的所有文件。当用户需要了解某个文件夹里有什么时使用。""" return os.listdir(directory) def write_summary(content: str, output_path: str) -> str: """将分析结果写入指定路径。仅当用户明确要求保存结果时使用。""" os.makedirs(os.path.dirname(output_path), exist_ok=True) with open(output_path, 'w', encoding='utf-8') as f: f.write(content) return f"已写入 {output_path}" # 工具注册表：这是模型唯一能看到的信息 TOOLS = [ { "type": "function", "function": { "name": "read_file", "description": "读取本地文本文件的内容，返回文件原文。当用户提到笔记、文档、报错日志等本地内容时使用。filepath 必须为绝对路径，不支持 ~ 符号。", "parameters": { "type": "object", "properties": { "filepath": {"type": "string", "description": "文件的绝对路径，例如 /home/xx/note.txt"} }, "required": ["filepath"] } } }, { "type": "function", "function": { "name": "list_files", "description": "列出指定目录下的所有文件名。当用户需要查看某个文件夹包含哪些文件时使用。", "parameters": { "type": "object", "properties": { "directory": {"type": "string", "description": "目录的绝对路径"} }, "required": ["directory"] } } }, { "type": "function", "function": { "name": "write_summary", "description": "将一段文本写入本地文件。仅当用户明确要求保存分析结果、写报告、输出整理方案时使用。", "parameters": { "type": "object", "properties": { "content": {"type": "string", "description": "要写入的完整文本内容"}, "output_path": {"type": "string", "description": "输出文件的绝对路径"} }, "required": ["content", "output_path"] } } } ]

这段代码看起来只是几个函数，但里面有一个非常重要的设计决策：我把“工具注册表”和“实际函数实现”分开了。TOOLS列表里的 JSON 结构是给模型看的，而真实的read_file()函数是给我自己用的。这样做的好处是，模型永远只看到精简后的工具描述，不会因为我们函数内部有复杂的默认参数或装饰器而困惑。

3.2 决策循环：外层循环 + 内层判停，一个都不能少

智能体的核心执行逻辑其实是个循环。我画不出专业流程图（你可以理解为类似 while 循环的思路），逻辑如下：

import requests import time # 这里的高亮 API 用 OpenAI 兼容协议，国内大部分大模型都支持这套格式 API_URL = "https://api.example.com/v1/chat/completions" API_KEY = "your-api-key" MODEL_NAME = "your-model-name" def call_model(messages, tools): """调用大模型，传入对话历史和工具定义，返回模型响应。""" resp = requests.post( API_URL, headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}, json={"model": MODEL_NAME, "messages": messages, "tools": tools} ) resp.raise_for_status() return resp.json()["choices"][0]["message"] def run_agent(user_goal: str, max_rounds: int = 8): """智能体主循环。max_rounds 是最大工具调用轮数，防止死循环。""" messages = [{"role": "user", "content": user_goal}] tool_map = {"read_file": read_file, "list_files": list_files, "write_summary": write_summary} for round_index in range(max_rounds): # 第一步：让模型决定下一步动作 model_message = call_model(messages, TOOLS) messages.append(model_message) # 第二步：检查模型是否需要调用工具 if not model_message.get("tool_calls"): # 模型没有调用工具，说明它认为任务已完成，输出最终答案 print("任务完成，最终回复：", model_message["content"]) return model_message["content"] # 第三步：执行工具调用，把结果追加到上下文 for tool_call in model_message["tool_calls"]: func_name = tool_call["function"]["name"] func_args = json.loads(tool_call["function"]["arguments"]) func = tool_map.get(func_name) if not func: raise ValueError(f"未注册的工具: {func_name}") result = func(**func_args) messages.append({ "role": "tool", "tool_call_id": tool_call["id"], "content": str(result) }) print(f"第 {round_index+1} 轮 - 调用 {func_name}，参数 {func_args}，结果摘要 {str(result)[:50]}") raise TimeoutError(f"超过 {max_rounds} 轮工具调用，终止任务")

这个循环里有几个细节值得展开说。

第一个细节是max_rounds参数的设置。我特意把它定为 8，这个数字不是拍脑袋出来的。我的任务场景是“读文件 - 分析主题 - 写报告”，理想情况下只需要 3-5 轮。设成 8 留出了多余处理空间（比如模型决定先列出目录再逐个读文件），又不会让死循环拖死整个应用。实时任务、长流程任务可以适当调高到 12-16，再加入时间层面的兜底中断（比如运行超过 60 秒强制结束）。

第二个细节是工具调用结果的追加方式。注意我用了"role": "tool"这个角色，配上了"tool_call_id"。很多初学的人栽在这里：他们把工具结果当作普通 assistant 消息传回去，模型就会把工具返回的原始文本当成“智能体自己说的话”，导致后续回答时人格混乱。正确的做法是严格按协议走——每一轮消息里，模型先发一条带tool_calls的 assistant 消息，紧接着跟几条对应的tool角色消息。这样模型能清楚区分“哪些内容是我说的，哪些内容是工具执行结果的回声”。

3.3 上下文结构设计：隐藏的上下文才是决定成败的暗线

如果只看上面那段代码，你会觉得智能体开发不过如此。但实际运行起来，你会发现决定智能体质量的很大一部分在“你怎么组织上下文信息”，而不只在于循环怎么写。

让我用一个具体例子说明。假设用户说：“帮我看看 ~/notes 文件夹里的笔记，按主题归档”。如果我不做任何预处理，直接把这句话丢给模型，模型的第一轮动作大概率是调用list_files。好，这一步没问题。问题是，工具执行完毕后，模型看到文件列表时可能只有文件名而没有内容信息，它就必须再靠猜来决定下一步读哪个文件。如果文件夹里有 20 个文件，模型会尝试逐个读取，既耗 token 又容易出现半途上下文溢出。

我踩过这个坑之后，在用户目标的预处理阶段加了一步：先让模型自己判断，拿到目标后是否需要请求补充信息或先列出全局情况。更直接的方案是，我在初始用户消息里做了结构化提示：

用户目标：帮我把 ~/notes 下的笔记按主题归档。 约束：执行第一步时，先列出目录内容再决定下一步动作。最终结果必须以 write_summary 工具保存为 markdown 格式。

这相当于给模型一个“操作路径”的锚点。由此模型不会在空地上自由发挥，而是按我预设的节奏来。你可以把这种做法理解为提示词层面的工作流编排——不把每一步都写死，但把关键路径上的地标交代清楚。

再往深一层说，上下文结构设计还包括把“一次性任务状态”放在哪里。我的做法是用一个全局字典记录已经读取过的文件、已经生成的分析结果、当前工作目录等信息，每次工具调用时把这些状态注入到系统提示词里，而不是让模型自己从长长的历史对话里回忆。这样做有两个好处：一是模型每次做决策时不需要翻看所有历史消息，直接看到“当前状态”即可，省 token；二是避免模型在多轮后忘记自己已经读过哪些文件，减少重复读取。

4. 实操过程：从写代码到跑通任务，两小时的完整现场记录

4.1 准备阶段：环境与数据

这个项目的环境其实很轻量，不需要 GPU，不需要本地推理。我用的是普通笔记本电脑，Python 3.10 环境，只装了一个requests库。如果你用的是其他语言，比如 Node.js，也一样，思路完全通用。

我自己准备的测试数据是一批杂乱的 Markdown 笔记，大概 12 个文件。为了重现真实场景，我故意把这些文件命名为a1.md、b2_tmp.md、技术-01.md这类毫无规律的名称，文件内容则是各自独立的主题——有几篇是关于 Python 异步编程的，有几篇是关于摄影构图的，还有几篇是会议记录。这种杂乱感保证了智能体必须“读取内容”才能真正理解主题，而不是靠文件名猜。

4.2 第一个可运行版本：从“盲目运行”到“看见决策”

我写的第一版代码比上面贴的还要简陋：没有 max_rounds 限制，没有工具注册表分离，参数描述也很随意。跑出来的结果很有戏剧性——模型告诉我“我已经完成了任务”，但实际上只调用了list_files一次，连一个文件都没读过，纯粹是编了个报告。这给了我一个重要教训：模型非常善于“假装任务完成”，因为它的训练目标就是让对话显得合理，而不是确保工具真的被执行到位。

怎么对抗这种情况？我做了三件事：

第一，在工具描述里强调“工具结果是可信的事实来源，不要编造任何未读取文件的内容”。这看起来像是在对模型提要求，其实是在给评估器（也就是循环代码）传递一个信号——当模型没有读取任何文件就给出了分析报告时，系统应该主动触发警告。

第二，给工具调用加“证据链”校验。这是一个非常实用的技巧：我在循环里对write_summary这个写报告工具加了前置校验——必须确认对话历史里至少存在一次成功的read_file调用，否则拒绝执行并提示模型“证据不足，请先读取文件”。这相当于给智能体装了一个护栏。

第三，是加日志。老实说，这个项目开发过程中，最具性价比的投资就是详细日志。每一轮 tool call 的参数、结果、token 消耗、耗时，全部打印到 console。第一次跑通时，我盯着日志仔细观察了模型如何一步步从“列出目录”、“读取三个文件”、“输出归档方案”，那种感觉像在看一个初入职场的实习生慢慢摸清工作流程，非常有成就感。

4.3 参数与成本计算：token 消耗和超时设计的实测分析

智能体开发有个不同于普通 Web 开发的特性——你不仅要关心代码正确性，还要关心成本。因为每一次 tool call 都是一次独立的 API 请求，多轮决策意味着 token 消耗是成倍增长的。我用实测数据说明：

第一次跑时，我选的模型上下文窗口是 32K token，看起来绰绰有余。但注意，我的智能体循环里有一个隐患：每一轮 messages 数组都在不断增长，模型每次调用 API 时要把全部历史消息发送过去。如果任务很长，比如读取 10 个大文件，历史消息很快就会逼近上下文限制。

我的应对策略是做了“压缩历史消息”的预处理器：当累计消息超过阈值时，把最早的“用户目标”和“系统提示”保留，把中间的 tool 执行结果压缩成“已完成步骤摘要”重新发给模型。这个策略对一个体验型项目来说已经足够了。如果你后续要持续开发智能体，可以研究摘要记忆、向量数据库检索记忆等方式，但这不在这次的讨论范围内。

4.4 踩坑现场：三种最有代表性的翻车实录

在开发过程中，我记录了几个最典型的失败案例，贴出来供你排查参考。

第一个坑是“幽灵工具调用”。某次运行时，模型返回了一个我根本没注册过的工具名，比如search_web。原因并非模型幻觉，而是因为我用的 API 后端的大模型训练语料里包含了对这个工具的印象——它在别的上下文里见过这个工具名，于是“想当然”地认为前端已经注册了。排查后我确认代码逻辑无误，但这个问题提醒我：在接入任何大模型 API 时，都要对tool_calls中的工具名做白名单校验，而我的循环代码里已经内置了tool_map.get(func_name)和ValueError抛错，确保模型无法调用未注册工具。

第二个坑是“参数幻觉”。有一次模型调用read_file时，把参数写成{"filepath": "D:\\notes\\a1.md"}，但我的开发环境是 Linux。不同操作系统的路径格式差异，模型经常搞混。我最终的做法是在工具描述里加了一条“当前操作系统为 Linux，请使用正斜杠 / 路径”，并在代码里注入了运行时环境信息。

第三个坑更隐蔽：工具执行结果过大导致 API 请求被拒。某次我读取一个文件时，工具返回了一整本小说的文本内容，大概 200K 字符。我原样把它塞进 messages 里发给 API，结果直接报 400 错误，提示消息内容超限。解决方法是给工具结果加截断器——超过一定长度就保留开头和结尾，中间用省略标记替代，并追加一句提示“内容过长已截断，如需完整内容请分段读取”。顺便说一句，这个截断提示非常重要，因为模型看到截断内容后，知道不能“假装看了全文”，它会主动请求分段读取或按章节提取。

5. 常见问题与排查技巧实录

5.1 终端到终端的测试方法：没有界面也可以用脚本验证

由于这个智能体没有 UI 界面，我最终的验证方式其实是写了一个模拟脚本，把 12 个笔记文件的归档结果一次性跑完，然后人工检查输出的 Markdown 归档方案是否合理。这里我强烈推荐一个“日志回放”的思路：把每次 API 请求和响应的完整 JSON 存到本地文件，之后可以用这些数据离线重现某一次执行，方便排查。这比让智能体反复重跑省钱得多——重跑一次完整任务可是要花 token 的。

5.2 几个典型问题速查

针对“异常信息返回给模型”这一点，我要多说一句。很多人的工具函数一旦报错，就直接把异常往上抛，导致整个智能体崩溃。但更优雅的做法是：在工具函数内部 catch 住异常，返回一个类似{"error": "文件不存在: /path/to/xxx"}的字符串。模型看到这个错误信息后，通常会自动调整参数重试或向用户解释情况。这个策略能极大提升智能体的健壮性。

def read_file_safe(filepath: str) -> str: """带异常捕获的工具函数。失败时返回错误信息给模型，而不是抛异常。""" try: with open(filepath, 'r', encoding='utf-8') as f: return f.read() except FileNotFoundError as e: return f"错误：文件 {filepath} 不存在，请检查路径" except UnicodeDecodeError: return f"错误：文件 {filepath} 编码不是 UTF-8，暂不支持读取"

5.3 一些关于“体验”层面的体会

最后说点代码之外的东西。这次体验智能体开发，我最深的感受是：智能体开发本质上是人机协作设计，你写的每一行提示词、每一个工具描述，都在塑造模型的行为边界。它不是传统软件开发里的“确定性逻辑”能比拟的。这也就是为什么日志和测试这么重要——你不知道模型到底会怎么做决策，只能通过大量观察来校准。

有一个小技巧值得分享：给每个工具的执行耗时做埋点，哪怕只是简单的time.time()。当智能体某一步卡住或者特别慢时，你日志里的耗时数据能帮你快速定位是模型推理慢，还是工具执行慢。我见过不少人忽略这一点，最后排查问题全靠猜。

6. 直接可以复用的最小骨架与后续扩展方向

6.1 瘦身版骨架：去掉所有装饰，只留核心

如果你看完上面的内容觉得信息量太大，这里给你一个压到最小的可运行骨架。注意，这个版本只保证能跑通，不保证业务完美：

1. 准备一个大模型 API（任意支持 function calling 的国产或国际主流模型都可）。
2. 复制第三节里的TOOLS注册表，替换成你自己的 2-3 个工具函数。
3. 复制run_agent()主循环，把tool_map换成你的函数映射。
4. 在循环里加入异常捕获和轮数上限。
5. 构造一条用户消息，启动循环，查看日志。

仅凭这五步，你就能得到一个具备“理解-决策-执行”基本能力的智能体。

6.2 顺着这个骨架能往哪些方向扩展

如果你跑通了第一个版本，下一步的扩展方向我建议按这个顺序来：

第一，加入记忆层。用向量数据库保存用户目标、工具结果摘要，让智能体在多次交互中记住已经做过的事。这一步能立刻把“体验级”提升到“实用级”。

第二，增加多工具并行调度。当前版本里模型一次可以返回多个tool_calls，但我在循环里是顺序执行的。你可以改成并行执行，特别是当多个工具之间没有依赖关系时，速度提升非常明显。

第三，引入更复杂的任务规划器。比如“先规划再执行”——模型在开始干活前，先把整个任务拆成三五个步骤清单，然后一步步执行。这对于复杂任务能显著减少模型在中途“迷失方向”的概率。

我个人在实际操作中的体会是：智能体开发是一个典型的“框架简单但细节吃人”的方向。核心循环代码可以短到一百行以内，但真正打磨一个可靠好用的智能体，需要你在提示词工程、工具设计、错误处理三个层面反复迭代。这篇里记录的沉没成本，希望你能直接跳过。

最后再分享一个小技巧：给你的智能体起一个名字，并让它在每次回答的末尾加上署名。这个看似无关紧要的动作，能让你在调试多轮对话时，快速区分哪些文本是模型生成的，哪些是工具执行结果拼接过来的。这个小细节，实测下来对开发调试效率的提升非常明显。