大模型工具调用新范式：代码优先策略提升AI代理准确性

这次我们来看一个关于大模型工具调用范式转变的研究发现。核心结论很直接：在测试的14个主流大模型中，有11个在“代码优先”的工具调用方式下表现更优，超过了传统的“JSON模式”调用。这意味着，如果你正在开发基于大模型的AI代理或助手，并且需要模型调用外部工具（如搜索、计算、API），那么用代码（尤其是Python）来描述工具和使用方式，可能比精心设计JSON Schema更有效。

这个发现对开发者来说很实用。它不涉及复杂的模型训练或高昂的硬件成本，而是一种使用策略的优化。无论你用的是云端API（如GPT-4、Claude）还是本地部署的开源模型，都可以尝试这种方法来提升工具调用的准确性和可靠性。本文将重点拆解“代码优先”是什么、为什么有效、以及如何在你自己的项目中实践，包括环境准备、代码示例和效果对比。

1. 核心能力速览

2. 适用场景与使用边界

“代码优先”的工具调用策略主要适用于以下场景和人群：

适合谁：

1. AI Agent/助手开发者：正在构建能够自动调用搜索、计算、数据库查询等工具的智能体。
2. 提示工程师：需要优化大模型在复杂任务中的表现，特别是涉及多步骤推理和工具使用的场景。
3. 全栈/后端工程师：希望将大模型能力更可靠地集成到现有业务系统和工作流中。

能解决什么问题：

• 工具调用不准：模型错误理解JSON Schema中的参数要求，导致调用失败或参数错误。
• 复杂逻辑表述困难：用JSON难以清晰表达工具使用的条件、循环或异常处理逻辑。
• 提示词冗长低效：复杂的JSON结构使得提示词臃肿，可能干扰模型的核心推理。
• 提升开发体验：对于开发者而言，用熟悉的代码（Python）来定义工具，比编写和调试复杂的JSON更直观。

不适合什么场景：

• 模型完全不懂代码：如果使用的模型对代码理解能力极弱，“代码优先”将失去优势。
• 极度简单的工具调用：仅有一两个固定参数的工具，传统JSON模式可能已足够简洁。
• 严格受限的上下文长度：代码描述可能比精简的JSON占用更多Token，在上下文窗口非常紧张时需权衡。

合规与边界：

• 该方法仅改变与模型交互的“描述方式”，不涉及模型本身的黑盒操作或数据窃取。
• 在定义工具时，需确保工具本身的用途合法合规，避免描述可用于攻击、侵权或破坏系统的功能。
• 应用于生产环境前，应在测试环境中充分验证其稳定性和准确性。

3. 环境准备与前置条件

实施“代码优先”工具调用，不需要特殊的部署环境，它主要依赖于你的现有大模型服务。以下是通用的准备清单：

1. 大模型访问权限：

   • 闭源模型：确保你拥有如 OpenAI GPT系列、Anthropic Claude、Google Gemini 等模型的API Key和有效的调用权限。
   • 开源本地模型：确保你的本地或自有服务器已成功部署了如 Llama 3、Qwen、DeepSeek 等支持代码理解能力的模型，并配置好推理接口（如 OpenAI 兼容的 API 端点）。

2. 开发环境：

   • Python 环境：推荐 Python 3.8+。这是“代码优先”的核心，因为我们将用Python代码作为工具描述语言。
   • 包管理工具：pip或conda。
   • 代码编辑器：VS Code, PyCharm 等。

3. 必要的Python库：

   • 大模型SDK：根据你使用的模型选择，例如openai,anthropic,litellm等。
   • 基础工具包：requests(用于调用外部API类工具)、json、re等。

4. 一个清晰的测试目标：准备一个具体的、需要调用工具才能完成的任务。例如：“查询北京今天的天气，然后计算如果下雨，我开车和坐地铁哪种方式更省时间？”

4. “代码优先”范式详解与部署思路

“部署”在此处指的是将这种范式集成到你的项目代码库中。核心是重构你与模型交互的提示词（Prompt）和工具定义部分。

4.1 传统JSON模式回顾

在OpenAI的Function Calling或类似机制中，我们通常以JSON数组的形式向模型描述工具。

[ { "type": "function", "function": { "name": "get_weather", "description": "获取指定城市的天气信息", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "城市名称，如：北京" }, "date": { "type": "string", "description": "日期，格式YYYY-MM-DD，默认为今天" } }, "required": ["location"] } } } ]

然后将这个JSON数组作为tools参数传递给模型API。模型需要理解这个JSON结构并选择调用。

4.2 “代码优先”模式定义

“代码优先”模式放弃将工具定义为纯粹的JSON Schema，而是将其编写成一段结构化的、注释清晰的伪代码或真实代码片段，并放入系统提示词（System Prompt）或用户消息中。

核心思路：你不是在告诉模型“有一个工具，它的JSON结构长这样”，而是在告诉模型“这里有一些可用的Python函数，它们的签名和功能如下，你可以在思考中决定是否及如何调用它们”。

下面是一个“代码优先”的工具定义示例：

# 可用工具定义 (Available Tools Definition) # 你可以在思考中决定调用以下函数来获取信息或执行操作。 # 调用时，请遵循函数的参数说明。 import datetime from typing import Optional def get_weather(location: str, date: Optional[str] = None) -> str: """ 获取指定城市的天气信息。 Args: location (str): 城市名称，例如：“北京”、“上海”。 date (Optional[str], optional): 查询日期，格式为 ‘YYYY-MM-DD‘。默认为今天。 Returns: str: 返回天气情况的文本描述，例如：“北京，2023-10-27，晴，15-22°C”。 Example: >>> get_weather(“北京”) “北京，2023-10-27，晴，15-22°C” >>> get_weather(“上海”, “2023-10-28”) “上海，2023-10-28，多云，18-24°C” """ # 函数体内部实现对外部API的调用，此部分对模型不可见，仅作说明。 # 实际调用时，模型只需生成包含函数名和参数的代码块或指令。 pass def calculate_travel_time(distance_km: float, transport_mode: str) -> float: """ 根据距离和交通方式计算行程时间。 Args: distance_km (float): 距离，单位公里。 transport_mode (str): 交通方式，可选 ‘driving‘, ‘subway‘, ‘biking‘。 Returns: float: 预计时间，单位分钟。 Example: >>> calculate_travel_time(10, “driving”) 25.5 """ # 内部实现逻辑... pass

4.3 如何集成到API调用中

你不需要真的让模型去执行这段Python代码（除非你构建了代码执行环境）。通常的做法是：

1. 将上述代码文本作为系统提示词的一部分，让模型在上下文中知晓这些“可用函数”。
2. 在用户提问后，期望模型在回复中，以清晰的格式（如标记代码块）输出它想要调用的函数及参数。
3. 你的后端程序解析模型的回复，提取出函数名和参数。
4. 你的后端程序真正执行对应的函数（调用真实API或进行计算）。
5. 将函数执行的结果作为新的上下文信息再次发送给模型，让模型基于结果生成最终回答给用户。

这个过程与JSON模式的“Function Calling”在流程上相似，但交互的“语言”从JSON变成了更自然的代码注释和类型提示。

5. 功能测试与效果验证

我们设计一个测试任务来对比两种模式的效果。任务：“帮我查一下杭州明天下午是否适合户外跑步，如果下雨，推荐一个室内的健身活动。”

5.1 测试环境搭建

假设我们使用 OpenAI 的gpt-4o-mini模型进行测试。

import openai import json import re # 设置你的API Key client = openai.OpenAI(api_key="your-api-key-here") # 真实工具函数（模拟） def get_weather(location: str, date: str = None) -> str: # 模拟API返回 weather_data = { "杭州": { "2024-05-28": "小雨，18-24°C", "2024-05-29": "多云，20-28°C" } } date = date or "2024-05-29" return f"{location}，{date}，{weather_data.get(location, {}).get(date, '数据缺失')}" def recommend_indoor_activity(weather_condition: str) -> str: if "雨" in weather_condition: return "推荐室内活动：瑜伽、健身环大冒险、跳绳或室内游泳。" else: return "天气良好，户外跑步更佳。"

5.2 JSON模式测试

我们按照传统方式定义工具并调用。

def test_json_mode(): tools_json = [ { "type": "function", "function": { "name": "get_weather", "description": "获取城市天气", "parameters": { "type": "object", "properties": { "location": {"type": "string"}, "date": {"type": "string"} }, "required": ["location"] } } }, { "type": "function", "function": { "name": "recommend_indoor_activity", "description": "根据天气情况推荐室内活动", "parameters": { "type": "object", "properties": { "weather_condition": {"type": "string"} }, "required": ["weather_condition"] } } } ] response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "帮我查一下杭州明天下午是否适合户外跑步，如果下雨，推荐一个室内的健身活动。"}], tools=tools_json, tool_choice="auto", ) # 解析模型返回的工具调用请求 tool_calls = response.choices[0].message.tool_calls print("JSON模式 - 模型返回的工具调用:", json.dumps([tc.function.model_dump() for tc in tool_calls], indent=2, ensure_ascii=False)) # 执行测试 test_json_mode()

预期结果与判断：模型应正确返回一个调用get_weather的请求，参数包含location: “杭州”。成功的关键是参数准确，且能根据返回的天气结果，决定是否继续调用第二个工具。

5.3 代码优先模式测试

我们将工具定义以代码注释形式放入系统提示词。

def test_code_first_mode(): system_prompt = """你是一个智能助手，可以调用以下Python工具来帮助用户。请根据用户问题，思考是否需要调用工具，并在回复中清晰地写出你要调用的代码。 可用工具： ```python def get_weather(location: str, date: str = None) -> str: \""" 获取指定城市的天气信息。 Args: location: 城市名，如‘杭州‘。 date: 日期，格式‘YYYY-MM-DD‘，默认明天。 Returns: 天气描述字符串。 \""" pass def recommend_indoor_activity(weather_condition: str) -> str: \""" 根据天气情况推荐室内活动。 Args: weather_condition: 天气描述字符串，应包含‘晴‘、‘雨‘、‘多云‘等关键词。 Returns: 活动推荐字符串。 \""" pass

当你决定调用工具时，请在你的回复中，用以下格式包裹调用代码：

# 工具调用 result = get_weather(‘杭州‘, ‘2024-05-29‘) # 调用结束

我会执行你写的代码，并将结果告诉你。请基于结果进行下一步分析或回答。 """

response = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": "帮我查一下杭州明天下午是否适合户外跑步，如果下雨，推荐一个室内的健身活动。"} ], ) assistant_reply = response.choices[0].message.content print("代码优先模式 - 模型回复原文:") print(assistant_reply) print("\n" + "="*50) # 尝试从回复中提取代码块 code_block_pattern = r"```python\n(.*?)\n```" matches = re.findall(code_block_pattern, assistant_reply, re.DOTALL) if matches: print("提取到的代码块:") for code in matches: print(code) else: # 如果没有标准代码块，查找包含函数调用的行 print("未找到标准代码块，尝试查找函数调用行...") for line in assistant_reply.split('\n'): if 'get_weather' in line: print(line)

执行测试

test_code_first_mode()

**预期结果与判断**：模型应在回复中生成类似 `get_weather(‘杭州‘, ‘2024-05-29‘)` 的代码调用。成功的关键是模型生成的调用语法正确（参数格式、函数名），并且能根据你的后续提示（模拟执行结果）进行逻辑判断，决定是否调用第二个函数。 ### 5.4 效果对比验证点 运行上述测试后，可以从以下几个维度对比效果： 1. **调用准确性**：模型是否选择了正确的工具？参数是否完整、格式是否正确？ 2. **逻辑连贯性**：在“代码优先”模式下，模型是否更倾向于在回复中展示其“思考过程”（例如，“我需要先获取天气，然后判断...”），这有助于调试。 3. **复杂任务处理**：对于需要多个工具顺序调用或有条件分支的任务，“代码优先”的描述是否让模型更容易理解执行流程？ 4. **抗干扰性**：在提示词中加入一些无关信息时，哪种模式下的模型更不容易被干扰？ 根据原研究结论，在多数模型上，“代码优先”模式在这些维度上表现更稳健。 ## 6. 接口API与批量任务集成 “代码优先”范式可以无缝集成到现有的AI Agent框架或批量任务处理系统中。 ### 6.1 构建一个简单的代码优先Agent服务 下面是一个使用FastAPI构建的简易服务端示例，它接收用户问题，采用“代码优先”提示词与模型交互，解析模型输出的代码，执行对应工具，并返回最终结果。 ```python # app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel import openai import re import sys from typing import Dict, Any import json app = FastAPI() client = openai.OpenAI(api_key="your-api-key") # 工具函数库 (实际实现) tool_lib = { “get_weather”: get_weather, # 引用前面定义的函数 “recommend_indoor_activity”: recommend_indoor_activity, “calculate”: lambda x, y, op: eval(f”x {op} y”), # 示例计算工具 } # 代码优先的系统提示词模板 CODE_FIRST_SYSTEM_PROMPT = “”” 你是一个AI助手，可以调用以下Python工具： ```python {工具定义代码}

请根据用户问题，如果需要调用工具，就在回复中写出完整的Python调用代码块（用```python包裹）。我会执行它。 “””

class UserQuery(BaseModel): question: str model: str = “gpt-4o-mini”

def extract_and_execute_code(reply: str, context: Dict[str, Any]) -> Any: “””从模型回复中提取并执行Python代码，安全地处理。””” code_pattern = r”python\n(.*?)\n” matches = re.findall(code_pattern, reply, re.DOTALL) if not matches: return None code_to_run = matches[0] # 非常关键：在实际生产环境中，这里必须使用沙箱或严格的白名单机制来执行代码，防止任意代码执行。 # 此处为演示，仅做简单匹配执行。 for func_name, func in tool_lib.items(): if func_name in code_to_run: # 使用正则表达式提取参数（这是一个简化示例，生产环境需要更严谨的解析器） # 例如匹配 get_weather(‘杭州‘) arg_pattern = rf”{func_name}((.*?))” arg_match = re.search(arg_pattern, code_to_run) if arg_match: args_str = arg_match.group(1) # 简易参数解析（实际应用建议使用ast.literal_eval） try: args = eval(f”({args_str},)”) if args_str else () result = func(*args) return result except Exception as e: return f”工具执行错误: {e}” return “未找到可执行的有效工具调用。”

@app.post(“/ask”) async def ask_agent(query: UserQuery): # 1. 构建包含工具定义的完整提示词 tools_code = “”” def get_weather(location: str, date: str = None) -> str: \“\“\“获取天气\“\“\“ pass def calculate(a: float, b: float, operator: str) -> float: \“\“\“计算，operator in [‘+‘, ‘-‘, ‘*‘, ‘/‘]\“\“\“ pass “”” system_msg = CODE_FIRST_SYSTEM_PROMPT.format(工具定义代码=tools_code)

# 2. 调用大模型 try: response = client.chat.completions.create( model=query.model, messages=[ {“role”: “system”, “content”: system_msg}, {“role”: “user”, “content”: query.question} ], temperature=0.1, ) assistant_reply = response.choices[0].message.content # 3. 提取并执行代码 tool_result = extract_and_execute_code(assistant_reply, {}) # 4. 将结果返回给用户（或可以再次喂给模型生成最终回复） return { “original_reply”: assistant_reply, “tool_execution_result”: tool_result, “final_answer”: f”根据工具执行结果‘{tool_result}‘，答案是…” if tool_result else assistant_reply } except Exception as e: raise HTTPException(status_code=500, detail=str(e))

ifname== “main”: import uvicorn uvicorn.run(app, host=“0.0.0.0”, port=8000)

启动服务后，即可通过 `POST /ask` 接口进行问答。 ### 6.2 批量任务处理 对于批量处理任务列表，可以构建一个任务队列。 ```python # batch_processor.py import asyncio import aiohttp import json from typing import List async def process_batch_questions(questions: List[str], api_url: str = “http://localhost:8000/ask"): “””并发处理一批问题。””” async with aiohttp.ClientSession() as session: tasks = [] for q in questions: task = asyncio.create_task( session.post(api_url, json={“question”: q, “model”: “gpt-4o-mini”}) ) tasks.append(task) responses = await asyncio.gather(*tasks, return_exceptions=True) results = [] for q, resp in zip(questions, responses): if isinstance(resp, Exception): results.append({“question”: q, “error”: str(resp)}) else: result_data = await resp.json() results.append({“question”: q, “result”: result_data}) return results # 示例批量问题 batch_questions = [ “杭州明天天气如何？”, “计算一下 125 乘以 38 等于多少？”, “如果明天下雨，上海适合去公园吗？” ] # 运行批量处理（需在异步环境中） # asyncio.run(process_batch_questions(batch_questions))

7. 资源占用与性能观察

“代码优先”范式本身不增加额外的显存或算力消耗，其性能影响主要体现在以下方面：

1. Token消耗：代码描述通常比等价的、高度压缩的JSON Schema占用更多的Token。这会导致：

   • 单次请求成本略微增加：对于按Token收费的API，成本会上升。
   • 有效上下文长度减少：在有限的上下文窗口内，能容纳的历史对话轮次或工具数量会变少。
   • 观察方法：在API响应中查看usage.prompt_tokens字段，对比两种提示词模式下的差异。

2. 推理时间：更长的提示词可能略微增加模型的推理时间（Latency），但这通常不是瓶颈。主要瓶颈仍是模型自身的计算速度。

3. 开发与维护成本：

   • 优势：对于开发者，用熟悉的代码和类型提示来定义工具，可读性和可维护性更高，调试更方便。
   • 劣势：需要编写一个轻量级的“代码解释器”或“调用提取器”来解析模型的输出，这比直接使用SDK内置的tool_calls解析要复杂一些。

建议：在决定采用“代码优先”前，可以在你的典型任务上做一个简单的A/B测试，权衡Token增加带来的成本/上下文压力与工具调用准确率提升带来的收益。

8. 常见问题与排查方法

9. 最佳实践与使用建议

1. 从简单开始：先用一个工具、一个简单任务验证“代码优先”在你的目标模型上是否有效，再逐步复杂化。
2. 提示词工程：
   • 明确指令：在系统提示词开头就声明角色和能力。“你是一个可以调用Python工具来解决问题的AI助手。”
   • 格式化要求：严格要求输出格式，例如“将调用代码放在```python代码块中”。
   • 提供示例：在提示词中给出一到两个完整的“用户问题-模型思考-代码调用”的示例（Few-shot Learning），效果提升显著。
3. 安全第一：绝对不要在未经验证和安全隔离的情况下，直接eval()或exec()模型生成的任意代码。必须使用白名单机制，只允许执行预定义好的、安全的函数，并对参数进行严格校验和清洗。
4. 混合使用：不必完全抛弃JSON模式。对于参数结构固定、描述简单的工具，JSON可能更简洁。可以将“代码优先”用于逻辑复杂的工具或核心流程，JSON用于辅助工具。
5. 持续评估：建立评估基准，定期测试不同提示策略下工具调用的成功率和质量。用数据驱动决策。
6. 利用类型提示：Python的类型提示（Type Hints）和文档字符串（Docstrings）是极佳的工具描述语言，模型能很好地理解它们。

“代码优先”工具调用范式为提升大模型Agent的可靠性提供了一种新思路。它利用了现代大模型在代码理解上的强大能力，将工具交互从“数据格式约定”提升到了“语义描述与逻辑表达”的层面。对于面临复杂工具调用挑战的开发者而言，值得花时间进行实验和评估。建议你选择一个当前效果不满意的工具调用场景，用本文提供的方法进行对比测试，很可能获得意想不到的改进。