AI Agent入门：从零构建可运行的最小认知闭环

1. 别被“Agent”三个字吓住这其实是个“会拆任务的聪明助手”不是玄学“AI Agent 入门新手和转行者先学什么别一上来就啃框架”——这个标题我看到的第一反应是太对了。去年带过几个从行政、设计、教培行业转过来的学员清一色上来就问“LangChain和LlamaIndex哪个好用”“AutoGen怎么配多智能体”结果代码还没跑通人已经在报错日志里迷失方向。他们不是不努力是用力点错了地方。就像想学开车先去研究发动机曲轴间隙和ECU刷写协议而不是先摸方向盘、踩离合、挂挡。AI Agent的本质是让大模型具备目标导向的自主行动能力它要能理解你的真实意图、把大目标拆成小步骤、调用工具查资料、修正错误、最终交出结果。这个过程里大模型是“大脑”但光有大脑不会走路——它得有“眼睛”输入解析、“手”工具调用、“记事本”记忆管理、“复盘本”反思机制。而市面上90%的入门教程一上来就把“手”和“记事本”的图纸塞给你却没告诉你怎么先让大脑看懂一句话。所以这篇不是讲LangChain源码也不是教你怎么部署Ollama而是还原一个真实的学习路径从你第一次在终端敲下pip install之前该建立什么认知框架从你写出第一行能真正完成任务的代码时背后到底发生了什么以及为什么跳过某些环节后面三个月都在填坑。核心关键词“AI Agent”“新手”“转行者”“框架”已经划出了边界我们不谈学术论文里的Agent架构分类不对比ReAct和Plan-and-Execute的token效率差异只聚焦于“一个零基础的人如何在30天内独立写出一个能自动查天气、总结新闻、生成周报的可运行Agent”。这个目标听起来不小但拆解下来它只需要三块砖你能准确描述问题Prompt工程 你能让它调用一次外部API工具集成 你能让它记住上一步干了啥状态管理。其余全是这三块砖的组合与加固。很多人卡在第一步以为Prompt就是“请帮我写个周报”结果模型回你一篇散文也有人卡在第二步调用API时连HTTP状态码401和403都分不清更别说处理rate limit还有人卡在第三步让Agent连续问三个问题后它突然忘了第一个问题的背景。这些问题跟框架选型关系极小跟底层原理关系也不大全是你动手前该扫清的认知盲区。所以这篇的起点不是代码而是你打开编辑器前脑子里该有的那张地图。2. 内容整体设计与思路拆解为什么必须绕开框架先建“最小可行认知闭环”2.1 框架不是起点而是封装后的终点我见过太多人花两周时间配置LangChain的ChatMessageHistory结果连requests.get()返回的JSON结构都看不懂。LangChain这类框架的价值在于它把“调用工具→解析响应→喂给大模型→提取下一步指令”这一整条链路用类和方法包装成了.invoke()和.agent_executor.run()。这极大提升了开发效率但代价是你失去了对每个环节的控制感和调试能力。就像汽车的ABS系统它能在刹车时自动点刹防抱死但如果你连“刹车踏板踩下去车轮为什么会转”都不清楚一旦ABS故障报警灯亮起你只能干瞪眼。AI Agent的学习路径必须反着来先手动实现一遍ABS的机械原理手动调用API、手动拼接prompt、手动保存上下文再去看电子控制单元框架是怎么把它自动化、标准化的。这样当你用框架时遇到ToolException: Failed to parse tool response这种报错你立刻能定位到是工具返回的JSON字段名和prompt里要求的不一致而不是在框架源码里逐行翻找。这个“最小可行认知闭环”的设计逻辑非常朴素任何Agent的核心循环无非是“思考→行动→观察→反思”四步。我们不追求一步到位而是用最原始的方式把这四步走通一次。比如做一个“查今日北京天气并推荐穿衣”的Agent它的闭环是思考用户说“今天穿什么”我需要知道北京当前温度、湿度、风速行动调用天气API如OpenWeatherMap获取数据观察拿到JSON响应提取main.temp、weather[0].description等字段反思把温度数字和“多云”描述翻译成“建议穿长袖衬衫薄外套”。这四步里第1步靠Prompt写清楚第2步靠requests库第3步靠Python字典操作第4步靠大模型生成。没有框架没有异步没有向量数据库甚至不需要本地部署大模型——用免费的OpenAI API或国内某平台的API就能跑通。这个闭环跑通后你再去看LangChain的Tool类就会发现它不过是把第2、3步封装成一个对象再去看AgentExecutor就会明白它只是把第1、4步的prompt模板化了。这种“先造轮子再用轮胎”的路径看似慢实则快。因为后续所有框架的学习你都在做“映射”工作这个参数对应我手动写的哪一行这个异常堆栈对应我当时手写时哪个环节漏了try-except这种映射能力才是转行者最稀缺的底层能力。2.2 新手最大的陷阱混淆“能运行”和“能理解”转行者常犯的一个致命错误是把“代码跑通了”等同于“我学会了”。我辅导过一位从前做UI设计的学员她用LangChain官方示例代码五分钟就搭出了一个能查股票的Agent。她很兴奋觉得“Agent不过如此”。但当我问“如果API返回的数据格式变了比如price字段从数字变成了字符串你的Agent会报错吗错在哪一行怎么改”她愣住了。后来我们一行行debug发现她根本没看过JsonOutputParser的源码也不知道tool的args_schema是怎么校验输入的。她的“能运行”是复制粘贴的结果不是理解驱动的结果。这种状态下的学习就像用胶带把两块木板绑在一起——看着连上了一受力就散。所以我们的整体设计强制要求每一个环节都“可打断、可观察、可修改”。比如在“行动”环节我们不用框架的tool.run()而是手动写import requests def get_weather(city: str) - dict: url fhttp://api.openweathermap.org/data/2.5/weather?q{city}appidYOUR_KEY response requests.get(url) if response.status_code 200: data response.json() return { temp: round(data[main][temp] - 273.15, 1), # 转摄氏度 condition: data[weather][0][description] } else: raise Exception(fWeather API error: {response.status_code})这段代码里requests.get()的返回值、response.json()的结构、data[main][temp]的取值路径全部暴露在你眼皮底下。你改一个字段名马上能看到KeyError你少写一个括号IDE立刻标红。这种“所见即所得”的反馈是建立直觉的唯一途径。而框架的黑盒性恰恰切断了这种反馈。因此整个学习路径的设计哲学就是用最笨的办法获得最扎实的肌肉记忆。当你的手指已经条件反射地敲出response.json().get(data, {}).get(items, [])时你再去学框架的JsonOutputParser就不是在背API而是在优化自己的肌肉记忆。2.3 转行者的独特优势别把“非技术背景”当短板它是天然的Prompt工程师很多转行者焦虑自己没写过代码但恰恰忽略了自己最大的隐藏资产对真实业务场景的深刻理解。一个做过三年HR的人比纯程序员更清楚“员工离职率分析报告”里该包含哪些维度、数据口径怎么统一、管理层最关注哪三个指标。一个教了十年数学的老师比算法工程师更懂“如何用生活化例子解释梯度下降”。这些不是技术却是构建高质量Agent的黄金燃料。因为Agent的终极价值从来不是“它能调用多少个API”而是“它能解决多复杂的现实问题”。所以我们的内容设计刻意强化这种优势的转化。比如在Prompt工程环节我们不教“用|endoftext|分隔指令”而是带你看一份真实的销售日报邮件然后一起拆解“老板说‘看看上月转化率’他真正想要的是什么是总转化率各渠道转化率还是新老客户转化率对比邮件里提到的‘活动A效果不佳’这个‘不佳’怎么量化是低于8%还是环比降了15%”这种拆解本质上就是把业务语言翻译成机器可执行的指令。而这项能力资深从业者闭着眼都能做但刚毕业的CS学生反而要专门训练。因此整个路径的第二阶段核心任务是把你过去十年积累的行业经验变成Agent的“领域知识库”。我们会教你如何把一份PDF版的《客户服务SOP》提炼成10条结构化规则再写成Prompt里的system message如何把Excel里的历史投诉分类表转换成few-shot examples。这不是编程这是你最擅长的“理解需求、定义问题、组织信息”的能力迁移。框架学得再熟没有这个迁移能力你的Agent永远停留在“玩具”级别。3. 核心细节解析与实操要点从Prompt到工具调用每一步都藏着关键细节3.1 Prompt工程不是写作文是写“可执行的接口说明书”新手对Prompt最大的误解是把它当成“对AI说话”。但实际工作中Prompt是Agent与大模型之间的契约接口。它必须像API文档一样精确输入格式、输出格式、边界条件、错误处理方式全部明确定义。我曾帮某电商公司优化客服Agent的Prompt原版是“请根据用户问题友好地回答。”结果模型把“退货地址错了”回复成“亲您的心情我们完全理解呢~”完全没解决问题。改成契约式Prompt后【角色】你是一名严格遵守《电商客服SOP V3.2》的售后专员。 【输入】用户消息含订单号、问题类型、关键事实 【输出格式】JSON必须包含 - action: resolve|escalate|collect_info - reason: 简短说明不超过20字 - next_step: 具体操作如请提供订单截图、已为您生成退货单号RT2024XXXX 【约束】 - 若用户未提供订单号且问题需查单action必须为collect_info - 若问题涉及物流超时且订单创建超72小时action必须为escalate上线后首次响应准确率从42%升至89%。这个案例说明好的Prompt核心不在文采而在结构化约束。实操中必须掌握三个关键细节 第一system message不是摆设是Agent的“操作系统内核”。它决定模型的行为基线。很多新手把所有规则塞进user message导致每次调用都要重复传输既费token又易出错。正确做法是system message定义长期角色、规则、格式user message只传本次动态数据。比如天气Agent的system message应固定为你是一个专业天气顾问只回答与天气相关的问题。所有输出必须是JSON格式包含temp_c、condition、recommendation三个字段。不回答天气以外的任何问题。第二few-shot examples不是教学是“格式锚点”。新手常堆砌大量例子以为越多越好。实则2-3个高质量例子胜过20个模糊例子。关键是例子必须覆盖典型case和边界case。比如User: 北京现在几度 Assistant: {temp_c: 22.5, condition: 晴, recommendation: 适合穿短袖} User: 上海下雨吗 Assistant: {temp_c: 18.2, condition: 小雨, recommendation: 建议带伞}这两个例子直接教会模型输入是城市天气属性输出是三个固定字段的JSON。第三必须加入“失败兜底”机制。模型不是100%可靠Prompt里要预设它答错时的退路。比如加一句“若无法从输入中提取城市名输出{error: 请提供具体城市名称}”。这比事后用try-except捕获JSONDecodeError更能保障用户体验。提示别迷信“高级Prompt技巧”先确保基础契约成立。我测试过一个结构清晰、字段明确的Prompt即使用免费版Qwen也能稳定输出合规JSON而一个文采斐然但无格式约束的Prompt用GPT-4也会随机输出散文。3.2 工具调用不是“调API”是“教Agent理解世界”工具调用Tool Calling常被简化为“写个函数注册到Agent”。但真实难点在于如何让Agent准确理解“什么时候该调用调用时传什么参数”。这需要两层对齐语义对齐Agent理解用户意图和结构对齐Agent理解API参数规范。先看语义对齐。用户说“帮我订明天下午三点的会议室”Agent要能识别出这是“预订”动作对象是“会议室”时间是“明天15:00”。这依赖于Prompt里对工具功能的精准描述。错误示范“这是一个预订会议室的工具”。正确写法tool_name: book_meeting_room tool_description: 预订指定时间的会议室。仅当用户明确要求预订如订、预约、安排且提供了时间如明天、下周三、15:00时才调用。 parameters: - room_id: 字符串会议室ID如A101、B205若用户未指定则留空 - start_time: ISO8601格式时间字符串如2024-05-20T15:00:00必须推算出绝对时间注意这里强调了触发条件“仅当...才调用”和参数约束“必须推算出绝对时间”。这相当于给Agent装了一个“决策开关”避免它把“会议室在哪”也当成预订请求。再看结构对齐。API的参数名、类型、必填项必须和Agent的认知严格一致。常见坑是API文档写start_time: string但实际要求ISO8601格式而Agent生成的参数可能是start_time: 明天下午3点。解决方案是在工具函数内部做强校验和转换而不是指望Agent一次写对。比如def book_meeting_room(room_id: str , start_time: str ): # 强制转换时间 try: dt parse_datetime(start_time) # 自定义parse_datetime函数支持明天15:00等自然语言 iso_time dt.isoformat() except: raise ValueError(start_time格式错误请使用YYYY-MM-DD HH:MM或明天/后天 HH:MM) # 调用真实API payload {room_id: room_id, start_time: iso_time} response requests.post(API_URL, jsonpayload) return response.json()这个设计的关键在于把自然语言理解的复杂性收口在工具函数内部。Agent只需负责“识别意图传递原始字符串”转换工作由工具完成。这样既降低了Agent的负担又提高了鲁棒性。我实测过这种设计下Agent对时间表达的容错率提升60%以上——它能把“下周一上午”、“3天后早上”、“本周五10点”全部交给parse_datetime处理自己只管判断“这是否是预订请求”。注意工具函数的错误处理比主流程更重要。务必用try-except包裹所有外部调用并将错误信息转化为Agent能理解的JSON格式。例如{error: 会议室A101在该时段已被预订请选择其他时间}。这样Agent才能基于错误信息向用户提出有效备选方案。3.3 状态管理不是存聊天记录是维护“任务进度图谱”新手常把状态管理等同于“保存聊天历史”。但Agent的状态远比对话记录复杂得多。它需要跟踪当前任务树的执行节点、各分支的中间结果、用户隐含的偏好、未满足的依赖条件。比如一个“规划旅行行程”的Agent状态可能包括主任务生成7天京都行程子任务1查询5月京都樱花期已完成结果4月10日-20日子任务2筛选符合预算的酒店进行中已排除3家用户偏好拒绝连锁酒店倾向传统町屋依赖条件需等待子任务2结果才能开始子任务3规划每日路线这种结构化状态用简单的messages.append()根本无法承载。实操中我推荐采用“轻量级状态机”模式用Python字典定义状态结构class AgentState: def __init__(self): self.task_tree { root: {status: running, result: None}, subtask_1: {status: completed, result: {bloom_period: 2024-04-10 to 2024-04-20}}, subtask_2: {status: running, result: []} } self.user_preferences {hotel_type: machiya, budget_max: 20000} self.dependencies {subtask_3: [subtask_1, subtask_2]} def update_subtask(self, subtask_id: str, status: str, resultNone): self.task_tree[subtask_id][status] status if result is not None: self.task_tree[subtask_id][result] result def can_run(self, subtask_id: str) - bool: deps self.dependencies.get(subtask_id, []) return all(self.task_tree[d][status] completed for d in deps)这个设计的优势在于状态变更可审计、可预测、可回滚。每次调用update_subtask()你都知道确切改变了哪个字段每次判断can_run()你都能清晰看到依赖关系。相比直接序列化整个messages列表这种结构化状态让调试变得极其简单——当Agent卡在某步时你直接print(state.task_tree)就能看到所有子任务的实时状态而不是在几百行聊天记录里大海捞针。更关键的是这种状态设计天然支持“中断续办”。用户中途问“酒店选好了吗”Agent能立即从state.task_tree[subtask_2][result]里提取已筛选的酒店列表无需重新执行整个流程。我在某教育项目中应用此模式后多轮对话的上下文准确率从63%提升至91%因为Agent不再“失忆”而是始终带着一张动态更新的“任务进度图谱”。4. 实操过程与核心环节实现手把手带你跑通第一个可交付Agent4.1 第一步搭建“思考-行动-观察”最小闭环30分钟我们以“自动汇总今日科技新闻”为实战目标全程不依赖任何框架只用requests和openai或国内某平台SDK。目标输入“汇总今日AI领域新闻”输出包含3条新闻标题、来源、摘要的JSON。Step 1选择新闻API推荐使用免费的NewsAPIhttps://newsapi.org/注册后获取API Key。它支持按日期、类别筛选响应结构清晰。注意免费版有速率限制100次/天够学习用。Step 2手动实现“行动”环节工具函数import requests import json from datetime import datetime def fetch_ai_news() - list: 获取今日AI领域新闻返回结构化列表 today datetime.now().strftime(%Y-%m-%d) url fhttps://newsapi.org/v2/everything?qartificialintelligencefrom{today}to{today}sortBypublishedAtapiKeyYOUR_API_KEY try: response requests.get(url, timeout10) response.raise_for_status() # 抛出HTTP错误 data response.json() # 结构化提取关键避免后续解析失败 articles [] for item in data.get(articles, [])[:3]: # 只取前3条 articles.append({ title: item.get(title, N/A), source: item.get(source, {}).get(name, N/A), summary: item.get(description, N/A)[:100] ... # 截断防超长 }) return articles except requests.exceptions.RequestException as e: return [{error: fNews API request failed: {str(e)}}] except Exception as e: return [{error: fNews parsing failed: {str(e)}}] # 测试工具函数 if __name__ __main__: print(json.dumps(fetch_ai_news(), indent2, ensure_asciiFalse))实操心得这里try-except的粒度很重要。我把网络请求和JSON解析分开捕获因为前者是外部服务问题后者是数据结构问题修复策略完全不同。另外[:100]截断是防止大模型处理超长文本这是新手常忽略的性能细节。Step 3设计“思考”环节的Promptsystem userSYSTEM_PROMPT 你是一个专业的科技新闻编辑负责将原始新闻数据整理成简洁、准确的摘要。所有输出必须是JSON格式包含一个news_summary字段其值为包含3个对象的列表。每个对象必须有title、source、summary三个字符串字段。不添加任何额外字段或解释。 USER_PROMPT_TEMPLATE 以下是今日AI领域的新闻数据 {news_data} 请严格按以下JSON格式输出摘要 {{ news_summary: [ {{ title: 新闻标题1, source: 来源1, summary: 摘要1不超过100字 }}, ... ] }}Step 4组装“观察”环节调用大模型import openai def generate_summary(news_data: list) - dict: 将新闻数据喂给大模型生成结构化摘要 news_str json.dumps(news_data, ensure_asciiFalse, indent2) user_prompt USER_PROMPT_TEMPLATE.format(news_datanews_str) try: response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_prompt} ], temperature0.3, # 降低随机性保证格式稳定 max_tokens500 ) # 解析模型输出关键必须处理可能的非JSON响应 raw_output response.choices[0].message.content.strip() if raw_output.startswith(json): raw_output raw_output[7:-3].strip() # 去除代码块标记 return json.loads(raw_output) except json.JSONDecodeError as e: print(fJSON解析失败: {e}, 原始输出: {raw_output}) return {error: 模型输出格式错误请重试} except Exception as e: return {error: f大模型调用失败: {str(e)}} # 运行完整闭环 if __name__ __main__: news fetch_ai_news() print(【工具调用结果】, news) summary generate_summary(news) print(【最终输出】, json.dumps(summary, indent2, ensure_asciiFalse))运行后你会看到一个真正的、可交付的新闻汇总Agent。它不炫酷但每一步都透明可控。这个闭环的价值在于你亲手触摸了Agent的每一根神经——从API请求的timeout设置到Prompt里temperature0.3的取舍再到JSON解析的容错处理。这种“亲手造轮子”的体验是任何框架教程都无法替代的。4.2 第二步加入“反思”能力让Agent学会自我纠错2小时上一步的Agent有个硬伤如果NewsAPI返回空数据它只会输出{error: News API request failed...}然后结束。但真实场景中它应该尝试备选方案比如换关键词搜索或告知用户“今日暂无AI新闻是否查看机器学习领域”这就是“反思”Reflection环节。我们通过在Prompt中加入“错误处理协议”来实现REFLECTION_SYSTEM_PROMPT 你是一个具备自我反思能力的新闻编辑。当收到错误信息时不要直接返回错误而是 1. 分析错误原因是API不可用还是无数据 2. 提出1个具体、可执行的备选方案 3. 用JSON格式输出包含error_analysis、alternative_action、suggested_query三个字段 示例 { error_analysis: News API返回空结果可能因当日无AI相关新闻, alternative_action: 切换至机器学习领域搜索, suggested_query: 机器学习 } def handle_error(error_msg: str) - dict: 当fetch_ai_news或generate_summary返回error时触发反思 try: response openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[ {role: system, content: REFLECTION_SYSTEM_PROMPT}, {role: user, content: f错误信息{error_msg}} ], temperature0.1, max_tokens200 ) raw_output response.choices[0].message.content.strip() if raw_output.startswith(json): raw_output raw_output[7:-3].strip() return json.loads(raw_output) except Exception as e: return {error_analysis: 反思模块故障, alternative_action: 重试, suggested_query: } # 在主流程中加入错误处理 def run_news_agent(): news fetch_ai_news() if isinstance(news, list) and len(news) 0 and error not in news[0]: return generate_summary(news) else: # 触发反思 reflection handle_error(str(news)) print(【反思结果】, reflection) # 这里可以基于reflection[suggested_query]发起新搜索... return reflection这个改进让Agent从“单次执行”升级为“任务流”。它不再是被动响应而是主动诊断、主动决策。我在某金融项目中应用类似逻辑后Agent的任务完成率从72%提升至89%因为很多失败不是因为能力不足而是缺乏“换个思路试试”的灵活性。实操心得反思Prompt的示例example必须真实。我最初用虚构示例模型经常生成“联系管理员”这种无效方案。换成真实错误日志后它才学会区分“网络超时”和“数据为空”的不同应对策略。这印证了前面说的few-shot的质量远胜于数量。4.3 第三步用状态机串联多任务构建真实工作流半天现在我们把单任务Agent升级为多任务Agent输入“帮我规划下周技术分享会”它要依次完成1查下周可用会议室2查团队成员下周空闲时间3综合推荐3个候选时段。这需要状态机协调。Step 1定义状态结构复用前面的AgentStateclass TechEventState: def __init__(self): self.tasks { find_rooms: {status: pending, result: []}, check_availability: {status: pending, result: {}}, generate_slots: {status: pending, result: []} } self.context { event_purpose: 技术分享会, attendees: [张三, 李四, 王五], duration_hours: 2 } def next_pending_task(self) - str: 按依赖顺序返回下一个待执行任务 order [find_rooms, check_availability, generate_slots] for task in order: if self.tasks[task][status] pending: return task return NoneStep 2编写任务执行器Task Executordef execute_task(state: TechEventState, task_name: str) - TechEventState: 根据任务名执行对应逻辑 if task_name find_rooms: rooms find_available_rooms() # 伪代码实际调用会议室API state.tasks[find_rooms] {status: completed, result: rooms} elif task_name check_availability: # 基于state.tasks[find_rooms][result]和state.context[attendees] avail check_team_availability(state.tasks[find_rooms][result], state.context[attendees]) state.tasks[check_availability] {status: completed, result: avail} elif task_name generate_slots: slots generate_time_slots( state.tasks[find_rooms][result], state.tasks[check_availability][result], state.context[duration_hours] ) state.tasks[generate_slots] {status: completed, result: slots} return state # 主循环状态机驱动 def run_event_planner(): state TechEventState() while True: next_task state.next_pending_task() if not next_task: break print(f执行任务: {next_task}) state execute_task(state, next_task) # 输出最终结果 final_result { recommended_slots: state.tasks[generate_slots][result], used_rooms: state.tasks[find_rooms][result][:3], confirmed_attendees: len(state.context[attendees]) } return final_result这个设计的精妙之处在于任务执行逻辑与状态流转逻辑完全解耦。execute_task()只关心“这个任务怎么做”TechEventState只关心“现在该做什么”。这种分离让代码极易维护——新增一个“发送日程邀请”任务只需在execute_task()里加一个elif分支状态机自动识别并调度。我在某企业内部系统中用此模式将原本3000行的硬编码工作流重构为不到500行的可配置状态机后续新增审批环节只改了20行代码。注意状态机的next_pending_task()方法必须定义清晰的执行顺序。实际项目中我会用DAG有向无环图替代线性顺序支持并行任务如“查会议室”和“查人员空闲”可同时进行。但对新手线性顺序足够建立概念。5. 常见问题与排查技巧实录那些没人告诉你的“血泪教训”5.1 “模型不按Prompt格式输出”——不是模型问题是你的Prompt没锁死现象明明写了“输出JSON格式”模型却回复“好的这是您要的摘要{...}”开头多了废话。根本原因大模型的“遵循指令”能力高度依赖Prompt的结构强度。松散的指令如“请用JSON格式”会被忽略而强约束指令如“必须输出且仅输出JSON不带任何前缀、后缀、解释”才能生效。独家排查技巧加“格式锚点”在Prompt末尾加一行--- OUTPUT START ---并在解析时只取这行之后的内容。实测可提升格式合规率40%。用代码块标记强制在system prompt里写“请将最终答案放在json和之间”然后解析时只取代码块内内容。这是最简单有效的方案。温度值必须设为0.0-0.3高于0.5时模型会“发挥创意”故意不守格式。这不是bug是它的设计特性。避坑心得我曾为某政务项目写一个“政策解读Agent”反复调试一周都没解决格式问题。最后发现是system prompt里有一句“请用通俗易懂的语言解释”这句话激活了模型的“解释欲”导致它在JSON前加了一段说明。删掉这句话问题立刻消失。所以对格式敏感的Agentsystem prompt里禁止出现任何“解释”“说明”“阐述”类动词。5.2 “工具调用总是失败”——90%的情况是参数没对齐现象book_meeting_room(room_idA101, start_time明天15:00)报错KeyError: start_time。真相不是代码写错了是API文档和你的认知有gap。比如某会议室API实际要求start_time是Unix时间戳而你传了字符串或者要求room_id必须是数字ID而你传了A101。系统化排查表排查步骤操作方法为什么有效1. 查原始API文档打开API官网找到book_meeting_room的POST请求示例逐字比对字段名、类型、是否必填90%的失败源于文档没读全比如忽略了timezone是必填参数2. 抓包验证用Postman或curl完全复现你的参数调用看返回结果绕过所有代码层直接验证API本身是否正常3. 日志打点在工具函数开头加print(f调用参数: {locals()})确认传入值很多时候你以为传了start_time实际是