一、什么是 Tool Calling?
Tool Calling(工具调用)是指大模型根据当前任务和可用工具定义,判断是否需要调用外部能力,并生成符合指定结构的调用请求,由 Agent Runtime 或工具执行引擎完成实际操作。
大模型本身主要负责理解、推理和生成内容,并不天然具备直接访问数据库、执行代码、调用 API 或操作浏览器的能力。
Tool Calling 为模型提供了一种受控的外部能力调用机制。
例如,用户提出:
查询北京今天的天气,并判断是否适合户外跑步。
Agent 可能需要调用两个工具:
- 天气查询工具:获取当前天气、温度、湿度和风速。
- 天气分析工具:根据天气条件评估户外运动是否合适。
整个过程涉及模型决策、参数生成、工具调用、结果返回和后续推理。
1. Tool Calling 的核心组成
| 组成 | 职责 |
|---|---|
| Tool Definition | 定义工具名称、描述和参数结构 |
| Tool Registry | 注册和管理可用工具 |
| Tool Selection | 判断应该调用哪个工具 |
| Argument Generation | 生成工具调用参数 |
| Argument Validation | 校验参数合法性 |
| Permission Check | 检查调用权限 |
| Tool Executor | 执行实际工具操作 |
| Result Handler | 处理工具返回结果 |
| Agent Runtime | 管理整个调用生命周期 |
需要区分两个概念:
- Tool Calling:模型决定调用什么工具,以及生成什么参数。
- Tool Execution:运行时真正执行工具,并处理执行结果。
模型生成调用请求,不代表工具已经执行成功。
二、Tool Calling 的整体工作流程
典型的工具调用过程可以分为以下阶段:
- 注册工具:将工具定义提供给模型和运行时。
- 用户输入:接收用户任务。
- 工具选择:模型判断是否需要调用工具。
- 参数生成:模型生成结构化参数。
- 请求校验:验证工具名称、参数格式和业务约束。
- 权限检查:确认当前用户和 Agent 是否有权执行。
- 工具执行:调用 API、数据库、代码执行环境等。
- 结果处理:解析返回值,处理异常和超时。
- 结果反馈:将工具结果交给模型。
- 后续推理:模型根据结果继续执行或生成最终回答。
1. 完整调用流程
flowchart TD
A["用户提交任务"] --> B["Agent Runtime"]
B --> C["构建模型上下文"]
C --> D["LLM 推理"]
D --> E{"是否需要调用工具"}
E -->|"否"| F["生成最终回答"]
E -->|"是"| G["生成 Tool Call"]
G --> H["解析工具名称与参数"]
H --> I["参数 Schema 校验"]
I --> J{"参数是否合法"}
J -->|"否"| K["返回参数错误"]
K --> D
J -->|"是"| L["权限与安全检查"]
L --> M{"是否允许执行"}
M -->|"否"| N["拒绝调用或请求审批"]
M -->|"是"| O["Tool Executor"]
O --> P["执行外部工具"]
P --> Q["处理工具结果"]
Q --> R["Tool Result"]
R --> S["写入对话上下文"]
S --> D
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style F fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style G fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style H fill:#EAF3EC,stroke:#83A995,color:#315D49
style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
style L fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style M fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style N fill:#F7EAE7,stroke:#C98D7C,color:#754438
style O fill:#EAF3EC,stroke:#83A995,color:#315D49
style P fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style Q fill:#EAF3EC,stroke:#83A995,color:#315D49
style R fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style S fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
这里最重要的是:LLM 负责生成调用意图和参数,Agent Runtime 负责解析和调度,Tool Executor 负责真正执行。
三者职责分离,可以避免将模型生成的内容直接当作可信操作指令。
三、工具定义:Tool Definition
模型需要知道当前有哪些工具可以使用,以及每个工具的作用和参数要求。
因此,Agent 需要为工具提供标准化定义。
一个工具通常包含:
name:工具名称。description:工具功能描述。parameters:参数结构。required:必填参数。returns:返回数据结构。permissions:调用权限。timeout:执行超时时间。
1. 工具定义示例
假设需要定义一个天气查询工具:
{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "城市名称"
},
"date": {
"type": "string",
"description": "查询日期,格式为 YYYY-MM-DD"
}
},
"required": [
"city"
],
"additionalProperties": false
}
}
}
这类定义通常采用 JSON Schema 风格描述参数结构。
其中:
| 字段 | 含义 |
|---|---|
| type | 参数数据类型 |
| properties | 参数字段定义 |
| required | 必填字段 |
| description | 字段语义说明 |
| enum | 限定可选值 |
| additionalProperties | 是否允许额外字段 |
2. 为什么需要 Schema?
如果只向模型提供:
你可以查询天气。
模型虽然知道工具的作用,但无法可靠地确定调用参数的结构。
使用 Schema 后,模型能够根据定义生成结构化参数:
{
"city": "北京",
"date": "2026-11-20"
}
Schema 主要解决结构约束问题,但不代表参数在业务层面一定正确。
例如:
{
"city": "不存在的城市"
}
这个参数符合字符串类型要求,却可能无法通过真实业务校验。
因此,参数验证通常需要分为多个层次:
- 语法校验:JSON 是否能够正确解析。
- Schema 校验:字段、类型和必填项是否符合定义。
- 语义校验:参数含义是否合理。
- 业务校验:是否满足具体业务规则。
- 权限校验:当前调用者是否有权使用这些参数。
四、模型如何选择工具?
Tool Selection 是 Tool Calling 中最关键的决策环节之一。
当模型接收到用户任务和工具定义后,需要判断:
- 当前任务是否需要外部能力。
- 哪个工具最适合当前任务。
- 是否需要调用多个工具。
- 工具调用顺序是什么。
- 是否需要先收集更多信息。
1. 工具选择的基本机制
假设系统提供以下工具:
| 工具 | 功能 |
|---|---|
| get_weather | 查询天气 |
| search_web | 搜索网页 |
| query_database | 查询数据库 |
| send_email | 发送邮件 |
| execute_python | 执行 Python 代码 |
用户提出:
查询今天北京的天气。
模型根据任务语义选择 get_weather。
用户提出:
查询最近三个月的销售额,并计算每个月的增长率。
模型可能需要依次调用数据库查询和 Python 数据分析工具。
工具选择并不一定是简单的关键词匹配,而是结合工具描述、参数结构、上下文和当前任务状态进行判断。
2. 工具选择策略
常见策略包括:
模型驱动选择
由 LLM 根据工具定义自主选择。
优点是语义理解能力强,适合复杂和开放式任务。
缺点是存在选择错误、参数错误和调用不稳定的问题。
规则驱动选择
根据规则、关键词、业务路由或明确条件选择工具。
例如:
def select_tool(intent):
if intent == "weather":
return "get_weather"
if intent == "database_query":
return "query_database"
if intent == "email":
return "send_email"
return None
优点是确定性强,适合固定业务场景。
缺点是灵活性较低,难以覆盖复杂语义。
混合选择
先由规则进行工具范围过滤,再由 LLM 在候选工具中进行选择。
例如:
用户任务
↓
意图识别
↓
规则过滤工具
↓
LLM 选择候选工具
↓
参数生成
↓
工具调用
这种方式可以减少模型面对大量工具时的选择负担,也能降低错误调用概率。
3. 工具数量过多的问题
当 Agent 注册了大量工具时,可能出现:
- 工具描述过长。
- 工具之间功能重叠。
- 模型选择困难。
- 上下文 Token 消耗增加。
- 错误工具调用概率上升。
工程上可以使用工具分组、按需加载和分层路由。
例如:
Tool Registry
├── 数据工具
│ ├── 数据库查询
│ ├── 数据清洗
│ └── 数据分析
├── 搜索工具
│ ├── 网页搜索
│ └── 文档搜索
├── 通信工具
│ ├── 发送邮件
│ └── 发送消息
└── 系统工具
├── 文件操作
└── 代码执行
Agent 可以先判断任务领域,再向模型提供对应类别的工具定义,而不是每次暴露全部工具。
五、Tool Call 的数据结构
模型生成工具调用时,通常会返回一个结构化调用对象。
以通用格式表示:
{
"id": "call_001",
"type": "function",
"function": {
"name": "get_weather",
"arguments": {
"city": "北京",
"date": "2026-11-20"
}
}
}
实际模型 API 的调用格式可能略有不同,例如部分接口会将 arguments 表示为 JSON 字符串。
1. Tool Call ID
id 用于标识一次工具调用。
它非常重要,因为一次模型响应可能包含多个工具调用。
执行完成后,运行时必须将每个工具结果与对应的调用 ID 关联起来。
否则,当多个工具并行执行时,可能出现结果错配。
2. Function Name
name 指定需要执行的工具。
运行时不能直接执行模型返回的任意函数名称,而应该从 Tool Registry 中查找已经注册的工具。
如果工具不存在,应拒绝执行并返回明确错误。
3. Arguments
arguments 是模型生成的工具参数。
它需要经过解析和校验,不能直接传递给底层工具。
尤其需要注意:
- 参数可能缺失。
- 参数类型可能错误。
- 参数可能超出允许范围。
- 参数可能包含额外字段。
- 参数可能违反业务规则。
- 参数可能包含恶意或不可信内容。
4. 多工具调用
模型一次响应可能包含多个工具调用。
例如:
{
"tool_calls": [
{
"id": "call_001",
"function": {
"name": "get_weather",
"arguments": {
"city": "北京"
}
}
},
{
"id": "call_002",
"function": {
"name": "get_weather",
"arguments": {
"city": "上海"
}
}
}
]
}
如果两个工具调用相互独立,可以并行执行。
但不能仅凭模型同时返回多个调用,就认定它们一定可以安全并行。运行时仍然需要检查依赖关系、资源限制和副作用。
六、Tool Executor:工具执行引擎
Tool Executor 是 Agent Runtime 中负责实际执行工具的核心组件。
它接收模型生成的 Tool Call,完成工具查找、参数处理、权限验证、调用分发和结果封装。
1. 执行引擎的核心职责
| 模块 | 职责 |
|---|---|
| Tool Resolver | 根据工具名称查找工具 |
| Argument Parser | 解析调用参数 |
| Schema Validator | 验证参数结构 |
| Permission Manager | 检查调用权限 |
| Execution Dispatcher | 分发执行请求 |
| Timeout Controller | 管理超时 |
| Retry Manager | 管理重试 |
| Result Serializer | 统一结果格式 |
| Error Handler | 处理执行异常 |
| Audit Logger | 记录调用审计信息 |
2. 执行过程
flowchart TD
A["接收 Tool Call"] --> B["解析调用对象"]
B --> C["查询 Tool Registry"]
C --> D{"工具是否存在"}
D -->|"否"| E["返回 TOOL_NOT_FOUND"]
D -->|"是"| F["解析 Arguments"]
F --> G["Schema 校验"]
G --> H{"参数是否有效"}
H -->|"否"| I["返回 INVALID_ARGUMENT"]
H -->|"是"| J["权限与风险检查"]
J --> K{"是否允许执行"}
K -->|"否"| L["拒绝调用或请求审批"]
K -->|"是"| M["选择执行器"]
M --> N["执行工具"]
N --> O{"是否执行成功"}
O -->|"是"| P["序列化执行结果"]
O -->|"否"| Q["错误分类与恢复"]
P --> R["返回 Tool Result"]
Q --> S{"是否允许重试"}
S -->|"是"| N
S -->|"否"| T["封装执行错误"]
T --> R
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#EAF3EC,stroke:#83A995,color:#315D49
style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style E fill:#F7EAE7,stroke:#C98D7C,color:#754438
style F fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style I fill:#F7EAE7,stroke:#C98D7C,color:#754438
style J fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style K fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style L fill:#F7EAE7,stroke:#C98D7C,color:#754438
style M fill:#EAF3EC,stroke:#83A995,color:#315D49
style N fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style O fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style P fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style Q fill:#F7EAE7,stroke:#C98D7C,color:#754438
style R fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style S fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style T fill:#F7EAE7,stroke:#C98D7C,color:#754438
3. 为什么需要独立的执行引擎?
如果将模型生成的工具调用直接映射到底层函数,系统会面临较大的安全和稳定性风险。
例如:
# 不推荐:直接根据模型输出查找并执行任意函数
tool_name = model_response["name"]
arguments = model_response["arguments"]
globals()[tool_name](**arguments)
这种实现存在严重问题:
- 模型可能生成未授权函数名称。
- 可能调用不应该暴露的内部函数。
- 参数没有经过校验。
- 缺少权限控制。
- 缺少执行超时。
- 缺少审计记录。
- 异常处理不可控。
正确做法是使用显式注册表,只允许执行预先注册且经过授权的工具。
七、Tool Registry:工具注册与管理
Tool Registry 负责维护 Agent 可使用的工具集合。
工具注册表可以理解为一个受控的工具目录。
每个工具都需要有唯一标识和对应的执行实现。
1. 工具注册示例
from dataclasses import dataclass
from typing import Callable, Any
@dataclass
class Tool:
name: str
description: str
handler: Callable[..., Any]
permissions: set[str]
class ToolRegistry:
def __init__(self):
self.tools = {}
def register(self, tool: Tool):
if tool.name in self.tools:
raise ValueError(
f"Tool already exists: {tool.name}"
)
self.tools[tool.name] = tool
def get(self, name: str):
return self.tools.get(name)
def list_tools(self):
return list(self.tools.values())
注册工具:
def get_weather(city: str):
return {
"city": city,
"temperature": 18,
"condition": "晴"
}
registry = ToolRegistry()
registry.register(
Tool(
name="get_weather",
description="查询指定城市天气",
handler=get_weather,
permissions={"weather:read"}
)
)
2. 工具注册表需要解决的问题
生产级 Tool Registry 还需要考虑:
- 工具名称唯一性。
- 工具版本管理。
- 工具描述与 Schema 管理。
- 工具权限配置。
- 工具生命周期管理。
- 工具健康状态。
- 工具调用统计。
- 工具动态加载与卸载。
工具定义和执行实现应该保持一致。
如果模型看到的参数 Schema 与真实工具实现不一致,就可能产生大量无效调用。
八、参数解析与校验机制
参数校验是工具执行前的重要安全边界。
模型生成的参数不能被视为可信输入,即使它们来自模型,也可能包含错误或不符合业务约束的内容。
1. JSON 解析
如果模型 API 返回的参数是 JSON 字符串,需要先解析:
import json
arguments_text = '{"city": "北京"}'
arguments = json.loads(arguments_text)
解析失败时,应返回明确的参数格式错误,而不是直接执行工具。
2. Schema 校验
可以使用 JSON Schema 或 Pydantic 等工具验证参数结构。
例如:
from pydantic import BaseModel, Field
class WeatherArgs(BaseModel):
city: str = Field(min_length=1, max_length=50)
date: str | None = None
校验:
args = WeatherArgs.model_validate({
"city": "北京"
})
如果参数类型或约束不符合定义,校验过程会抛出异常。
3. 业务校验
Schema 只能约束数据结构,无法完整表达业务规则。
例如:
def validate_weather_args(args):
allowed_cities = {
"北京",
"上海",
"深圳",
"杭州"
}
if args.city not in allowed_cities:
raise ValueError("Unsupported city")
实际系统可以将结构校验和业务校验分开,便于维护和复用。
4. 参数校验分层
flowchart TD
A["模型生成参数"] --> B["JSON 解析"]
B --> C{"JSON 是否有效"}
C -->|"否"| D["格式错误"]
C -->|"是"| E["Schema 校验"]
E --> F{"结构是否正确"}
F -->|"否"| G["参数结构错误"]
F -->|"是"| H["语义校验"]
H --> I{"参数语义是否合理"}
I -->|"否"| J["语义错误"]
I -->|"是"| K["业务规则校验"]
K --> L{"是否满足业务约束"}
L -->|"否"| M["业务校验失败"]
L -->|"是"| N["进入执行阶段"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style C fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style D fill:#F7EAE7,stroke:#C98D7C,color:#754438
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style G fill:#F7EAE7,stroke:#C98D7C,color:#754438
style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style J fill:#F7EAE7,stroke:#C98D7C,color:#754438
style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style M fill:#F7EAE7,stroke:#C98D7C,color:#754438
style N fill:#DCEFE5,stroke:#4F8B70,color:#24563F
九、工具执行结果与模型上下文
工具执行完成后,执行引擎需要将结果返回给 Agent Runtime,再由 Runtime 将结果写入模型上下文。
模型根据工具结果继续推理。
1. Tool Result 的基本结构
建议统一封装工具结果:
{
"tool_call_id": "call_001",
"tool_name": "get_weather",
"status": "success",
"data": {
"city": "北京",
"temperature": 18,
"condition": "晴"
},
"error": null,
"metadata": {
"duration_ms": 120
}
}
其中:
tool_call_id:关联原始工具调用。tool_name:标识执行工具。status:执行状态。data:业务结果。error:异常信息。metadata:执行耗时、调用次数等元信息。
工具结果应当尽量保持结构化,避免把复杂数据全部拼接成一段自然语言。
2. 工具结果如何反馈给模型?
以天气查询为例,模型生成工具调用后,运行时执行工具并返回结果。
工具结果:
{
"city": "北京",
"temperature": 18,
"condition": "晴",
"wind_speed": 2
}
Runtime 将其作为工具响应写入对话上下文。
模型获得结果后,可以继续分析:
- 天气是否适合户外跑步。
- 温度是否合适。
- 风速是否过大。
- 是否需要提醒用户防晒或补水。
工具结果不是最终回答,而是模型后续推理的输入。
3. 工具调用与模型推理的闭环
flowchart TD
A["用户任务"] --> B["LLM 推理"]
B --> C["生成工具调用"]
C --> D["Runtime 执行工具"]
D --> E["获取工具结果"]
E --> F["写入模型上下文"]
F --> G["LLM 再次推理"]
G --> H{"是否还需要工具"}
H -->|"是"| C
H -->|"否"| I["生成最终回答"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style D fill:#EAF3EC,stroke:#83A995,color:#315D49
style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAE8FA,stroke:#A49BD5,color:#51477D
style H fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F
这就是 Agent 中常见的 Tool Calling Loop。
它与普通函数调用的区别在于:调用决策和后续任务判断由模型参与,而工具执行由受控的运行时负责。
十、同步、异步与并行工具调用
不同工具具有不同的执行特征。
例如:
- 本地计算通常执行时间较短。
- 数据库查询可能需要等待网络和磁盘操作。
- 网页搜索可能需要数秒。
- 大文件处理可能持续数分钟。
- 外部任务可能需要异步轮询才能获得最终结果。
因此,工具执行机制需要支持不同的执行模式。
1. 同步调用
同步调用是指调用方等待工具执行完成后再继续。
def execute_tool(tool, arguments):
return tool.handler(**arguments)
result = execute_tool(
weather_tool,
{"city": "北京"}
)
适合:
- 执行时间较短的工具。
- 本地函数调用。
- 简单计算。
- 对响应时间有明确要求的操作。
缺点是长时间任务会占用调用线程或执行资源。
2. 异步调用
异步调用允许程序在等待工具执行时处理其他任务。
import asyncio
async def get_weather(city: str):
await asyncio.sleep(1)
return {
"city": city,
"temperature": 18
}
async def main():
result = await get_weather("北京")
print(result)
asyncio.run(main())
适合网络请求、数据库访问和其他 I/O 密集型操作。
异步并不意味着任务一定并行执行。它主要解决等待期间的资源利用问题。
3. 并行调用
当多个工具调用互不依赖时,可以并行执行。
例如同时查询北京、上海和深圳的天气。
import asyncio
async def get_weather(city):
await asyncio.sleep(1)
return {
"city": city,
"temperature": 18
}
async def main():
cities = ["北京", "上海", "深圳"]
results = await asyncio.gather(
*[
get_weather(city)
for city in cities
]
)
print(results)
asyncio.run(main())
三个任务可以同时等待各自的 I/O 操作,缩短整体响应时间。
4. 并行执行的依赖条件
并行执行前必须确认:
- 工具调用之间没有数据依赖。
- 不存在未处理的共享状态冲突。
- 不会发生重复写入。
- 外部 API 允许相应并发量。
- 系统资源足够。
- 失败后能够正确处理部分成功的情况。
例如两个工具同时读取数据通常没有问题,但两个工具同时修改同一条记录,就需要考虑锁、版本控制或事务机制。
十一、工具执行中的异常处理
生产环境中的工具调用无法保证每次成功。
常见异常包括:
- 工具不存在。
- 参数格式错误。
- 参数超出业务范围。
- 权限不足。
- 网络连接失败。
- API 超时。
- 外部服务限流。
- 返回数据格式异常。
- 工具执行成功但结果不符合预期。
1. 错误分类
建议使用标准错误码:
| 错误码 | 含义 | 处理方式 |
|---|---|---|
| TOOL_NOT_FOUND | 工具不存在 | 检查工具注册 |
| INVALID_ARGUMENT | 参数不合法 | 修正参数 |
| PERMISSION_DENIED | 权限不足 | 拒绝执行或申请授权 |
| TOOL_TIMEOUT | 工具超时 | 按策略重试 |
| RATE_LIMITED | 请求被限流 | 延迟重试 |
| TOOL_UNAVAILABLE | 工具不可用 | 切换备用工具 |
| EXECUTION_FAILED | 执行失败 | 分类处理 |
| RESULT_INVALID | 返回结果不符合要求 | 验证或重新执行 |
2. 异常处理策略
重试
适用于临时网络错误、短暂服务不可用等问题。
降级
当主要工具不可用时,使用能力相近的备用工具。