企业官网建设流程全解析

1. 先搞清楚Tool Calling到底解决什么问题

做AI应用开发最常听到的一个词就是Tool Calling。这个词直译是工具调用，也叫Function Calling、函数调用。它解决的是大语言模型一个天生的硬伤：模型只能基于训练数据和输入上下文生成文字，它没法自己去查数据库、调接口、执行命令，也没法感知真实世界的实时状态。很多刚接触Agent开发的朋友会把Tool Calling理解成“模型能自己执行程序”，其实不是。模型真正做的是给出一份结构化的指令，告诉你的程序“我想调用某个工具，参数是什么”，真正执行工具的是你自己的代码。这个区分很重要，它决定了整个Agent系统的架构和安全边界。

如果你正在做AI Agent，或者想给现有业务系统接入一个能用自然语言操作数据的助手，这篇文章比较合适。我会把Tool Calling的原理、数据格式、工程实现和调优方法拆开讲，既有能直接跑的代码，也有我在生产环境里踩过的坑。

1.1 LLM的能力缺口：知识有限，行动为零

我们可以把LLM类比成一位知识渊博但手脚受限的专家。你问它某个理论，它可以讲得头头是道；但你让它查一下明天的机票价格、当前仓库库存、某个用户的订单状态，它就只能靠训练数据里可能早已过期的信息“编”一个答案。原因是LLM在训练时被固化在某个时间点，而且模型本身没有连接外部系统的通道。工具调用相当于给这位专家配了一个能联网、能操作软件的助理：模型负责判断该做什么，助理负责执行，然后把结果反馈回来，模型再继续分析。这个“判断—执行—反馈—再判断”的闭环，就是Agent应用的基础。

也是因为这个缺口，单纯的“聊天机器人”和“AI Agent”之间有一条明显分界线。聊天机器人只要输出文字就够了；Agent必须能对外部世界产生影响，哪怕只是查一下天气、创建一个工单、计算一个折扣。没有Tool Calling，模型再聪明也只是“纸上谈兵”，永远无法真正处理实时数据或执行业务动作。

1.2 让AI写代码和让AI调用工具是两回事

很多产品经理会提一个需求：能不能让AI自动写脚本然后自己跑？这是一个更复杂的能力，通常由代码解释器或沙箱环境实现。Tool Calling比它更轻量，也更可控。你不需要让模型在一个环境里为所欲为，而是预先定义好一组允许他使用的“按钮”，比如查询订单、发送邮件、计算运费。这样既能让AI完成动作，又不至于把整个系统完全交给黑盒。

对多数业务系统来说，工具调用是第一步，也是最稳妥的一步。举个例子，客服机器人需要查订单，你不需要给它写SQL权限，只需要定义一个query_order(order_id)工具，里面控制好数据权限和返回字段。模型能选择的动作完全由你定义，超出了工具清单它就做不了。这种约束不是限制，反而是安全感的来源。

1.3 一个完整的Tool Calling闭环长什么样

用一句话说明完整链路：用户提问，模型看到可用工具清单后决定要调用某个工具，你的程序执行这个工具，把执行结果作为新消息回传给模型，模型再基于结果生成最终回答。如果一次结果不够，这个循环可以继续，直到模型认为问题已经解决，输出最终回答为止。

听起来简单，实际工程里的难点全在细节：工具清单怎么定义才容易被模型选中；参数怎么校验才不会让模型“编数字”；工具执行报错怎样反馈给模型才能让它自我修复；多轮调用怎么防止死循环。下面几个章节就围绕这些难点展开。

2. 理解Function Calling协议：数据格式是地基

要真正掌握Tool Calling，不能只停留在“调用一个库”的层面，得先把协议层的东西看清楚。市面上绝大多数模型接口都兼容OpenAI定义的Function Calling协议，理解了它，换模型时基本无痛。

2.1 一次tool_call消息长什么样

在OpenAI兼容接口里，工具调用不走特殊通道，也是通过消息流完成的。当模型决定调用工具时，它的返回值里会多一个tool_calls数组。我把结构简化成下面这样：

{ "choices": [ { "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"北京\", \"date\": \"2025-06-01\"}" } } ] } } ] }

注意其中两个关键点。第一，arguments是一个JSON字符串，不是对象。很多新手直接拿它当dict用，结果报错，原因就在这。第二，每条tool_call都有独立的id，这个id在回填结果时必须要用。拿到这段返回后，你的程序需要根据name去路由到对应函数，用解析后的参数调用它。

执行完工具以后，要把结果回填给模型。回填时使用一条role为tool的消息，并且带上对应的tool_call_id。回填后的一段完整消息序列大致是：user消息、assistant的tool_calls消息、tool结果消息。然后再次调用模型，模型就能基于工具结果继续组织回答，或者继续调用下一个工具。这个过程不是一次性结束的，所以工程上通常用一个循环来管理。

2.2 用JSON Schema描述一个工具

落到代码上，工具清单就是一组字典。我写一个商品搜索工具的示例：

tools = [ { "type": "function", "function": { "name": "search_products", "description": "根据关键词和价格区间查询商品列表。当用户询问商品、库存、价格时使用。", "parameters": { "type": "object", "properties": { "keyword": { "type": "string", "description": "商品名称或关键词，比如'无线耳机'" }, "min_price": { "type": "number", "description": "最低价格，单位元，不传则忽略" }, "max_price": { "type": "number", "description": "最高价格，单位元，不传则忽略" }, "sort": { "type": "string", "enum": ["sales", "price_asc", "price_desc"], "description": "排序方式，默认按销量" } }, "required": ["keyword"], "additionalProperties": False } } } ]

name是模型用来区分工具的标识，建议动词开头、用下划线连接。description是给模型看的说明书，要写清楚“什么时候该用”和“能拿到什么结果”，而不是复制一行代码注释。parameters里每个字段都要有明确的类型和描述，尤其是枚举值，一定要列全。

实际生产里，工具描述不是给人看的，是给模型看的。模型没有机会运行你的代码，它只能靠这个话题描述来做判断。所以description里写“当用户提到昨天、最近、历史记录时使用”这种话，比单纯写“查询订单”要好得多。

2.3 参数设计里的说明书思维

我见过很多团队把工具参数描述写得很随意，比如get_weather的城市参数只写“城市”，结果模型经常传拼音、传别名、甚至传一个完整地址。更稳的写法是给出范例：城市名，比如北京、上海，不要带“市”字。另外，参数类型尽量贴合外部接口。如果外部接口要求int，Schema里就写integer；如果金额可能带小数，就用number，不要混用。模型对类型比较敏感，一旦类型定义模糊，产生的参数就需要你在代码里做额外转换。

另一个容易忽略的点是必要参数。有些参数不是必须的，你却把它放进required，模型就会编一个默认值，反而引入脏数据。比如价格区间，用户没提，你就应该让它可选。反向情况也一样：如果一个参数不传会直接导致接口报错，就一定要放进required，并且在description里写明“必填”。

还要注意字段之间的约束关系。比如某个工具要求date必须在start_date和end_date之间，这种情况下你再怎么描述，模型也可能传错。最好的办法是在参数不进工具前先做程序校验，校验失败就把错误信息回传给模型，让它自己修正。也就是说，Schema负责引导，代码负责兜底。

2.4 用tool_choice控制模型的行为

多数接口默认让模型自己决定是否调用工具，这个模式叫auto。如果你已经确定当前场景必须调用某个工具，可以用tool_choice强制指定。例如：

tool_choice = {"type": "function", "function": {"name": "search_products"}}

还有一种情况是你希望系统要么调用工具、要么不回答，可以把tool_choice设置成"required"，强迫模型在后续每一轮都选择调用工具。实际使用时要小心：强制调用不等于参数正确。强制模式下，模型可能用空参数调用，照样需要校验和兜底。

tool_choice是调优的好帮手，但不要滥用。每次强制都会压缩模型自由决策的空间，如果用户问题本身跟你的工具无关，强扭的瓜不甜，优先让模型在auto模式下做出自然选择，比硬绑一个工具更合理。

3. 把Tool Calling变成可运行系统：从手写循环到LangGraph

原理说清楚了，开始写代码。我建议第一次做Agent不要直接上全套框架，先手写一个循环。代码很短，但能让你把tool_calls、tool消息、终止条件全部看明白。之后再切到LangChain、LangGraph这样的工具链，你才清楚每个封装背后在做什么。

3.1 第一版：手写while循环建立完整认知

下面这段代码基于OpenAI SDK，展示一个最基本的Agent循环：

import json from openai import OpenAI client = OpenAI() messages = [{"role": "user", "content": "北京今天适合晨跑吗？"}] tools = [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市指定日期的天气情况，适合判断户外活动。", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名，比如北京"}, "date": {"type": "string", "description": "日期，格式YYYY-MM-DD，不传默认今天"} }, "required": ["city"] } } } ] def get_weather(city: str, date: str = None) -> dict: # 实际项目里在这里接天气API return {"city": city, "date": date or "今天", "weather": "晴", "temp": 25} for _ in range(5): # 最多迭代5轮，防死循环 response = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=tools, ) message = response.choices[0].message if not message.tool_calls: print("final answer:", message.content) break messages.append(message.model_dump()) for tc in message.tool_calls: fn_name = tc.function.name fn_args = json.loads(tc.function.arguments) if fn_name == "get_weather": result = get_weather(fn_args["city"], fn_args.get("date")) else: result = {"error": f"unknown tool: {fn_name}"} messages.append({ "role": "tool", "tool_call_id": tc.id, "content": json.dumps(result, ensure_ascii=False) })

这里面有几个细节容易出错。第一，message对象必须先转成字典再加回messages，不能直接把对象丢回去。第二，工具结果content是字符串，如果结果本身是dict，要用json.dumps序列化。第三，循环次数上限很重要，没有上限的话，一个异常场景可能让模型反复调用工具直到token耗尽。

这个循环看起来简单，但它已经具备Agent的核心能力：决策、调用、反馈、再决策。你完全可以基于这个结构扩展出更复杂的业务系统。

3.2 用LangChain的@tool简化工具接入

手写循环适合理解机制，但在工具数量变多后，手动维护路由表非常痛苦。用LangChain的@tool装饰器可以把函数直接变成工具对象，自动生成Schema，省掉大量模板代码：

from langchain_core.tools import tool from langchain_openai import ChatOpenAI @tool def get_weather(city: str, date: str | None = None) -> str: """查询指定城市在指定日期的天气情况，返回温度和天气现象。""" # 在这里调用真实天气服务API return f"{city} {date or '今天'}: 晴, 25℃, 空气质量良" llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) llm_with_tools = llm.bind_tools([get_weather]) resp = llm_with_tools.invoke("北京今天适合晨跑吗？") print(resp.tool_calls)

装饰器会根据函数签名和docstring自动生成Tool Calling协议里的JSON Schema。所以在LangChain生态里，docstring就是工具描述，一定要写到参数级别。比如“city”参数要写清楚格式和例子，否则生成的description还是空的。

有一点要注意：bind_tools只是让模型“看得见”工具，并不会自动执行。执行仍然需要Agent循环。LangChain提供了AgentExecutor，但如果你刚开始尝试，我建议先自己接管执行逻辑，这样出错时知道问题在哪。

3.3 用LangGraph把Agent流程变成可控状态图

当业务流程里出现“先查库存，再计算运费，再生成下单指令”这种多步依赖时，手写循环就不够灵活了。这里就轮到LangGraph登场。LangGraph把每一步变成图上的节点，节点之间用条件边连接，特别适合描述Agent的多阶段决策流程。

下面是一段基于LangGraph的简化实现，核心逻辑是：agent节点让模型决策，tools节点执行工具，执行完回到agent继续决策：

from typing import TypedDict, Literal from langgraph.graph import StateGraph, END from langgraph.prebuilt import ToolNode class AgentState(TypedDict): messages: list def call_model(state): response = llm_with_tools.invoke(state["messages"]) return {"messages": [response]} def route_after_model(state) -> Literal["tools", "end"]: last = state["messages"][-1] if getattr(last, "tool_calls", None): return "tools" return "end" graph = StateGraph(AgentState) graph.add_node("agent", call_model) graph.add_node("tools", ToolNode([get_weather])) graph.add_conditional_edges( "agent", route_after_model, {"tools": "tools", "end": END} ) graph.add_edge("tools", "agent") app = graph.compile()

这个流程中，最重要的不是代码本身，而是“可控”两个字。你可以在执行写操作前插入一个人工确认节点，也可以给某个工具单独设置重试策略。相比纯手写循环，LangGraph把控制流显式化了，流程一复杂，这种显式化的价值就非常明显。

当年我第一次用LangGraph时很困惑，为什么非要把流程画成图？后来接了十几个工具和四五个子流程后才发现，没有这种“地图”，每次改一个分支都要翻半天代码。把Agent当成一个有状态的工作流来管理，长期维护会轻松很多。

3.4 多工具场景下的路由与组织

工具数量变多后，模型的选择准确率会明显下降。如果一次对话里塞了三四十个工具的完整定义，模型容易在高相似工具之间犯迷糊。我的经验有两个办法。

第一个办法是按业务域分组，先用一个轻量分类器或规则选出领域，再让主模型只看到该领域下的工具清单。比如有“订单域”“物流域”“售后域”三组工具，用户问物流问题，模型就只看物流组，选择空间小了，准确率自然高。

第二个办法是合并同类小工具。把get_weather、get_air_quality、get_wind这类查询合并成一个get_weather_and_environment工具，减少模型的选择面。工具不是越多越好，能让模型一次选中正确工具，比功能拆分得更细更重要。命名也要差异化，query_order和get_order_info这种看着就差一点的命名会让模型选错，工具名最好统一风格。

4. 生产环境中的排查与调优：这些坑我替你踩过了

Tool Calling的官方文档都很简单，但生产环境里各种问题层出不穷。这一章我整理几个高频问题、解决方法，以及我平时的一些习惯。

4.1 模型不调用、乱调用、死循环怎么处理

“该调用却不调用”最常见的场景是天气、新闻、股票这类实时信息。如果你不给工具描述，模型会倾向于用自己记住的知识直接回答，因为生成文字比调用工具省力。遇到这种问题，最有效的一招是改系统提示词，让模型明确知道“我的知识不是最新的，遇到实时信息必须先调用工具”。其次是调低temperature，让模型更偏好确定性路径。

“死循环”则是Agent开发里最烧钱的坑。我在一个项目里遇到过模型反复调用同一工具，每次参数都一样，就是因为没有设置迭代上限。后来我不仅加了最大轮数，还在提示词里告诉模型“如果一次调用没有解决问题，向用户说明当前获取不到足够信息，不要反复重试”。提示词和代码双重约束，基本能避免失控。

4.2 JSON解析与参数幻觉

模型在生成arguments时，虽然格式是标准JSON，但内容不一定完全符合Schema。参数要求number，模型可能传字符串"25"；要求enum，模型可能传一个不在枚举里的值。原因是模型对类型的理解仍然可能受到用户语言的影响，用户说“价格高一点”，模型就可能真的传一个“高”字。

我通常会在解析后加一层二次校验，最轻量的方式是直接使用jsonschema：

import json import jsonschema fn_args = json.loads(tc.function.arguments) try: jsonschema.validate(instance=fn_args, schema=parameters) except jsonschema.ValidationError as e: result = { "error": f"参数校验失败: {e.message}", "hint": "请根据错误信息修正参数后重试" }

这段代码看起来基础，但价值非常大。校验失败后，工具结果会作为一条tool消息回给模型。模型看到“参数校验失败”这样的明确错误，通常会重新组织参数再调用，而不是直接放弃。如果校验出错后你不回传，而是静默忽略，Agent的行为会变得很奇怪，甚至直接答非所问。

4.3 工具执行失败后，如何优雅恢复

我最开始写Agent时，工具一报错就直接让整个流程崩溃，后来发现这是最不应该做的事。工具执行失败的场景太多了：数据库连接超时、第三方接口限流、文件不存在。如果让这些错误直接抛给用户，体验非常差。正确做法是把异常信息转换成一条tool消息，返回给模型，让模型决定下一步。

实现上就是在execute_tool外面包一层try/except：

try: result = execute_tool(fn_name, fn_args) except Exception as e: result = { "error": str(e), "hint": "工具执行失败，请根据错误信息向用户说明原因" }

关键点：返回给模型的错误信息不要太长，模型理解晦涩的堆栈很吃力。最好在业务代码里自己捕获异常并转换成人话，例如“数据库连接超时，请稍后重试”。模型看到这个信息后，大概率会组织一句“当前服务暂时不可用，建议过几分钟再试”这样的回答，比直接甩一个Traceback要自然得多。

我见过一套比较成熟的方案是给每个工具定义错误码和恢复策略。比如网络类错误重试一次，参数错误直接提示模型修正，业务规则错误则明确告诉用户原因。把恢复策略做成配置，Agent的行为会稳定很多。

4.4 并发、超时与安全边界

一次模型回复里可能包含多个tool_calls。只要这些工具之间没有依赖关系，就可以并行执行，减少整体延迟。用asyncio.gather或者ThreadPoolExecutor把工具执行并行化，效果很明显。但每个工具必须单独设置超时，尤其是HTTP请求，默认3到10秒比较合理，避免一个慢接口拖死整个Agent。

安全边界是比性能更重要的工程话题。工具调用让模型有了“手”，这双手必须被锁在业务规则里。我的原则是：查询类工具可以放开给模型自动调用；写操作、删除、转账、发消息这类工具，必须经过用户确认或者至少经过二次审核。可以给工具定义is_risky标记，在LangGraph流程里为风险工具插入人工确认节点。

还有幂等性。工具的实现在可能重试时最好设计成幂等，或者至少可以撤销。否则模型因为超时重试一次，可能造成重复下单、重复扣款等严重事故。如果是写入型工具，最好在参数里带上request_id或操作唯一键，让后端可以做去重。

4.5 用日志和评测集验收工具调用效果

Build工具容易，验证工具调得好不好才是长期难题。我在项目里维护了一份工具评测集，大约50条用户原话，覆盖每个工具的高频说法和容易混淆的边界情况。每次修改工具定义或更换模型后，直接跑一遍，统计三个指标：工具选择准确率、参数抽取准确率、多余调用率。没有评测集，你很难知道一次prompt调整到底是在变好还是变坏。

日志方面，我会记录每次tool_calls的原始请求、参数、执行结果和最终回复，按日期存成JSON Lines。复盘时把真实业务问题和工具调用轨迹对应起来，几乎所有顽固bug都能从日志里找到线索。比如某个用户反复触发同一个错误工具，一看日志就知道是description里哪个词引发的误判，改掉那个词就行。

最后再分享一个我自己的调试习惯：给模型加新工具之前，先不要写正式代码，直接在模型对话里贴工具定义，用几条真实用户说法去试一遍，看模型会不会选错工具、会不会填错参数。这个方法只需要几分钟，但能提前发现大半方案问题。Tool Calling这块，原理和接口文档都容易找，真正拉开差距的其实是这些细节。做透了之后，你会发现Agent的可靠性能像普通后端服务一样被管理起来。