尧图网站建设 
大家好最近在探索大语言模型LLM的“工具调用”功能时我发现了一个非常有趣且重要的趋势传统的、依赖结构化 JSON 格式的“函数调用”模式正在被一种更灵活、更强大的“代码优先”范式所取代。有研究甚至表明在测试的 14 个主流模型中有 11 个在“代码优先”模式下表现更优。这不仅仅是 API 调用方式的变化它深刻地影响着我们如何设计 AI 代理、构建自动化流程以及集成外部服务。今天我们就来彻底搞懂这个转变并通过 Python 实战让你亲手体验“代码优先”工具调用的强大之处。无论你是正在构建 AI 助手的开发者还是希望更高效利用大模型能力的工程师理解并掌握“代码优先”的方法都将让你在设计和实现上领先一步。本文将带你从概念理解到环境搭建再到一个完整的、可运行的本地 AI 代理助手项目实战最后深入探讨最佳实践和避坑指南。1. 背景与核心概念从“函数调用”到“代码优先”在深入代码之前我们必须先厘清几个关键概念明白我们为什么要做出这样的转变。1.1 什么是工具调用工具调用简单来说就是让大语言模型如 GPT-4、Claude、DeepSeek 等能够识别用户请求中的意图并决定是否需要调用一个外部工具如计算器、搜索引擎、数据库、自定义 API来完成任务然后将工具执行的结果整合进最终的回复中。例如用户问“北京今天的天气怎么样”模型本身并不知道实时天气但它可以“调用”一个“获取天气”的工具一个 API获取数据后再生成回答“北京今天晴气温 25°C。”1.2 传统的“函数调用”模式及其痛点最初OpenAI 等厂商定义了“函数调用”的范式。其核心流程是定义开发者需要预先、精确地以 JSON Schema 格式定义好每个工具函数的名称、描述、参数及其类型。{ name: get_weather, description: 获取指定城市的天气, parameters: { type: object, properties: { location: { type: string, description: 城市名例如北京 } }, required: [location] } }调用将用户问题和这些函数定义一起发送给模型。模型返回一个结构化的 JSON指明它想调用哪个函数以及具体的参数。{ function: get_weather, arguments: {\location\: \北京\} }执行你的程序解析这个 JSON找到对应的本地函数get_weather(“北京”)并执行。回复将执行结果返回给模型模型生成最终回答。这种模式的痛点僵化工具必须在对话前完全定义好难以动态增删。复杂JSON Schema 编写繁琐容易出错特别是嵌套结构。依赖严重依赖模型对特定 JSON 格式的理解和生成能力。不自然不符合开发者“写代码”的直觉更像是配置而非编程。1.3 新兴的“代码优先”范式及其优势“代码优先”范式应运而生。其核心思想是让模型直接生成可执行代码通常是 Python 代码片段来调用工具而不是生成一个描述调用的 JSON。它的流程更像是准备你告诉模型可用的工具库例如requests库可以发 HTTP 请求pandas可以处理数据或者你自定义的函数。生成模型根据你的问题直接生成一段包含工具调用逻辑的 Python 代码。# 模型生成的代码 import requests response requests.get(https://api.weather.com/v1/city/北京) weather_data response.json() current_temp weather_data[current][temp]执行在一个安全的沙箱环境中运行这段代码获取结果。回复将代码执行的结果或结果摘要提供给模型生成最终回答。“代码优先”的优势灵活强大代码可以表达复杂的逻辑循环、条件判断、多步操作而 JSON 只能描述静态结构。开发者友好直接用 Python 等语言描述工具更符合开发习惯。动态性工具集可以更容易地动态加载和扩展。表现更优正如研究指出的许多模型生成代码的能力优于生成特定结构的 JSON因此在“代码优先”模式下工具调用的准确率和成功率更高。简单来说从“JSON 配置驱动”转向“代码生成驱动”是工具调用领域一次重要的范式升级。2. 环境准备与版本说明接下来我们将通过一个实战项目来体验“代码优先”的魅力。我们将构建一个本地运行的 AI 代理助手它可以调用 Python 代码来解决问题。2.1 项目目标创建一个命令行 AI 助手能够理解自然语言指令并自动编写/执行 Python 代码来完成诸如计算、数据处理、获取网络信息模拟、文件操作等任务。2.2 环境与工具操作系统Windows 10/11, macOS, 或 Linux (本文以 macOS/Linux 命令行示例为主Windows 用户建议使用 WSL 或 Git Bash)。Python版本 3.8。我们将使用一些较新的语法特性。包管理工具pip。核心库openai用于调用大语言模型 API。我们将使用 OpenAI 兼容的 API例如来自Groq、Together AI或本地部署的Ollama提供的兼容接口。python-dotenv管理环境变量安全存储 API 密钥。可选/备用本地模型库ollama。如果你想完全在本地运行可以使用 Ollama 部署开源模型如llama3.2、qwen2.5等它们也支持类似的功能。代码执行沙箱我们将实现一个简单的、安全的代码执行器。2.3 项目结构初始化首先创建一个项目文件夹并初始化虚拟环境这是管理 Python 依赖的最佳实践。# 创建项目目录 mkdir ai_code_agent cd ai_code_agent # 创建虚拟环境 (Python 3.8) python3 -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 创建必要的文件 touch main.py tool_library.py safe_executor.py .env requirements.txt2.4 安装依赖编辑requirements.txt文件填入以下内容openai1.0.0 python-dotenv1.0.0 requests2.28.0 # 用于我们的示例网络工具 pandas2.0.0 # 用于示例数据处理工具然后安装它们pip install -r requirements.txt如果你的网络环境需要配置请使用可靠的网络连接。至此基础环境就准备好了。3. 核心组件拆解构建“代码优先”代理的三要素一个基本的“代码优先”AI代理通常包含三个核心部分工具库、代码生成器LLM和安全执行器。3.1 工具库让 AI 知道它能用什么在“代码优先”模式下我们不是用 JSON 定义工具而是准备一个真实的 Python 模块其中包含一些函数并赋予它们清晰的功能描述。这些描述将作为“系统提示词”的一部分教给模型。创建tool_library.py# tool_library.py import requests import pandas as pd import json import math from datetime import datetime from typing import Any, Dict, List # 示例工具 1: 数学计算 def calculate(expression: str) - float: 计算一个数学表达式。 注意使用 eval在实际生产环境中应对输入进行严格检查或使用更安全的替代方案如 ast.literal_eval。 参数: expression (str): 数学表达式例如 3 5 * 2, sqrt(16) 返回: float: 计算结果 # 为表达式添加常用的数学函数 safe_dict {k: v for k, v in math.__dict__.items() if not k.startswith(_)} safe_dict[abs] abs # 警告此处为示例简化eval 有安全风险 result eval(expression, {__builtins__: None}, safe_dict) return float(result) # 示例工具 2: 获取模拟的天气数据避免真实 API 调用 def get_mock_weather(city: str) - Dict[str, Any]: 获取指定城市的模拟天气数据。 参数: city (str): 城市名称 返回: dict: 包含天气信息的字典例如 {city: 北京, temp: 22, condition: 晴朗} # 模拟数据 mock_data { 北京: {temp: 22, condition: 晴朗}, 上海: {temp: 25, condition: 多云}, 广州: {temp: 28, condition: 阵雨}, 深圳: {temp: 27, condition: 阴天}, } return {city: city, **mock_data.get(city, {temp: 20, condition: 未知})} # 示例工具 3: 获取网页标题模拟 def fetch_webpage_title(url: str) - str: 获取给定 URL 的网页标题模拟版。 在实际应用中这里会使用 requests 和 BeautifulSoup 解析真实网页。 参数: url (str): 网页 URL 返回: str: 网页标题如果失败则返回错误信息。 # 模拟响应 mock_titles { https://www.example.com: Example Domain, https://www.csdn.net: CSDN - 专业开发者社区, https://github.com: GitHub: Let’s build from here } return mock_titles.get(url, f无法获取 {url} 的标题模拟模式) # 示例工具 4: 简单的数据过滤 def filter_data(data: List[Dict], key: str, value: Any) - List[Dict]: 过滤字典列表返回指定键等于给定值的所有项。 参数: data (List[Dict]): 字典列表 key (str): 用于过滤的键 value (Any): 匹配的值 返回: List[Dict]: 过滤后的列表 return [item for item in data if item.get(key) value] # 我们可以导出一个工具描述列表用于构建系统提示词 TOOL_DESCRIPTIONS 你可以使用以下 Python 工具来帮助用户 1. calculate(expression): 计算数学表达式如 calculate(3 5 * 2)。 2. get_mock_weather(city): 获取城市的模拟天气信息如 get_mock_weather(北京)。 3. fetch_webpage_title(url): 获取模拟的网页标题如 fetch_webpage_title(https://www.example.com)。 4. filter_data(data, key, value): 过滤字典列表如 filter_data([{name:a},{name:b}], name, a)。 此外你还可以使用标准库如 json, datetime, math和已安装的第三方库如 pandas 作为 pd, requests。 当你需要完成一个任务时请直接生成可运行的 Python 代码片段。代码应该专注于获取结果并最终将核心结果赋值给一个名为 final_result 的变量。 关键点TOOL_DESCRIPTIONS变量包含了所有工具的自然语言描述这将被插入到给 LLM 的系统提示词中告诉模型“你能做什么以及如何调用”。这就是“代码优先”中“工具定义”的形态。3.2 安全执行器在沙箱中运行模型生成的代码允许模型生成并执行任意代码是极其危险的。我们必须创建一个受限制的执行环境。创建safe_executor.py# safe_executor.py import sys import io import traceback from contextlib import redirect_stdout, redirect_stderr from typing import Tuple, Any # 定义允许访问的模块白名单 ALLOWED_MODULES { math, datetime, json, random, re, collections, itertools, typing, pandas, numpy, requests # 根据你的工具库添加 } class SafeExecutor: def __init__(self, allowed_modulesNone): self.allowed_modules allowed_modules or ALLOWED_MODULES self._imported_modules {} def _safe_import(self, name, *args, **kwargs): 自定义的导入函数只允许导入白名单中的模块 if name in self.allowed_modules: # 实际导入模块 module __import__(name) # 处理子模块导入如 from pandas import DataFrame if args: # 这里简化处理实际可能需要更复杂的逻辑 return getattr(module, args[0], None) return module else: raise ImportError(f模块 {name} 不在允许列表中禁止导入。) def execute_code(self, code: str, global_vars: dict None, local_vars: dict None) - Tuple[bool, Any, str]: 在受限制的环境中执行一段 Python 代码。 参数: code (str): 要执行的 Python 代码字符串 global_vars (dict): 全局变量字典可用于传入工具函数 local_vars (dict): 局部变量字典 返回: Tuple[bool, Any, str]: (执行是否成功, 执行结果, 输出/错误信息) if global_vars is None: global_vars {} if local_vars is None: local_vars {} # 创建一个安全的全局命名空间 safe_globals { __builtins__: { print: print, len: len, str: str, int: int, float: float, list: list, dict: dict, range: range, __import__: self._safe_import, # 替换默认的 import }, **global_vars # 将工具函数等注入进来 } # 重定向标准输出和错误以便捕获 stdout_capture io.StringIO() stderr_capture io.StringIO() result None success False full_output try: with redirect_stdout(stdout_capture), redirect_stderr(stderr_capture): # 执行代码 exec(code, safe_globals, local_vars) # 尝试从局部或全局变量中获取名为 final_result 的结果 result local_vars.get(final_result, safe_globals.get(final_result)) success True except Exception as e: # 捕获所有异常并获取详细的错误信息 error_trace traceback.format_exc() stderr_capture.write(error_trace) # 合并输出和错误信息 stdout_output stdout_capture.getvalue() stderr_output stderr_capture.getvalue() full_output stdout_output stderr_output return success, result, full_output.strip()安全核心替换__import__我们覆盖了内置的导入函数只允许导入白名单ALLOWED_MODULES中的模块。这可以防止导入os,sys,subprocess等危险模块。限制__builtins__我们只提供了少数几个安全的 built-in 函数移除了open,eval,exec,__import__已被替换等。沙箱执行使用exec在隔离的命名空间中运行代码。结果捕获代码执行后我们期望它将主要结果赋值给变量final_result执行器会尝试提取它。同时所有print输出和错误信息都会被捕获并返回。重要警告这个执行器是基础示例并非绝对安全。生产环境需要更严格的沙箱如使用docker容器隔离、PyPy沙箱或专门的库如RestrictedPython。此处主要用于演示原理。3.3 代码生成器与大语言模型对话这是代理的大脑。我们将使用 OpenAI 兼容的 API并设计一个特定的提示词引导模型生成解决问题的代码。4. 完整实战案例构建本地 AI 代码代理助手现在我们将把上述组件组装起来创建main.py。4.1 配置 API 密钥与环境首先在项目根目录创建.env文件用于存储你的 API 密钥。如果你使用 OpenAI格式如下。如果你使用 Groq、Together AI 或本地 Ollama请参考其文档修改BASE_URL和MODEL。# .env OPENAI_API_KEYsk-your-actual-api-key-here # 如果使用其他兼容服务例如 Groq # OPENAI_BASE_URLhttps://api.groq.com/openai/v1 # OPENAI_MODELllama3-70b-8192注意.env文件包含敏感信息务必将其添加到.gitignore中不要提交到版本控制系统。4.2 编写主程序逻辑编辑main.py# main.py import os import sys from openai import OpenAI from dotenv import load_dotenv from tool_library import TOOL_DESCRIPTIONS, calculate, get_mock_weather, fetch_webpage_title, filter_data from safe_executor import SafeExecutor # 加载环境变量 load_dotenv() class CodeFirstAgent: def __init__(self): # 初始化 OpenAI 客户端 api_key os.getenv(OPENAI_API_KEY) if not api_key: print(错误未找到 OPENAI_API_KEY。请在 .env 文件中设置。) sys.exit(1) self.client OpenAI( api_keyapi_key, # 如果你使用非 OpenAI 官方端点取消下面的注释并设置 # base_urlos.getenv(OPENAI_BASE_URL, https://api.openai.com/v1) ) self.model os.getenv(OPENAI_MODEL, gpt-4o-mini) # 可根据需要调整模型 # 初始化安全执行器并注入我们的工具函数 self.executor SafeExecutor() self.tool_globals { calculate: calculate, get_mock_weather: get_mock_weather, fetch_webpage_title: fetch_webpage_title, filter_data: filter_data, final_result: None, # 预留结果变量 } # 构建系统提示词 - 这是引导模型生成代码的关键 self.system_prompt f你是一个强大的 AI 助手能够通过编写和执行 Python 代码来解决用户问题。 你的核心能力是“代码优先”工具调用。 {TOOL_DESCRIPTIONS} **你的工作流程** 1. 仔细分析用户的问题。 2. 判断是否需要使用上述工具或 Python 库来解决问题。 3. **如果需要生成一段简洁、完整、可独立运行的 Python 代码片段。** 4. 代码的目标是计算出用户问题的答案。 5. 代码的最后请将最终答案一个字符串、数字、列表或字典赋值给一个名为 final_result 的变量。 6. 如果问题很简单无需额外工具可以直接推理回答则不必生成代码。 **代码生成示例** 用户计算圆周率乘以 10 的平方。 助手python import math final_result math.pi * (10 ** 2)用户北京和上海哪个温度高 助手python weather_beijing get_mock_weather(北京) weather_shanghai get_mock_weather(上海) if weather_beijing[temp] weather_shanghai[temp]: final_result 北京温度更高。 elif weather_beijing[temp] weather_shanghai[temp]: final_result 上海温度更高。 else: final_result 两地温度相同。现在请开始帮助用户。如果生成代码请将代码包裹在 python 代码块中。 def generate_code(self, user_query: str) - str: 调用 LLM根据用户查询生成 Python 代码 try: response self.client.chat.completions.create( modelself.model, messages[ {role: system, content: self.system_prompt}, {role: user, content: user_query} ], temperature0.1, # 低温度使输出更确定专注于代码生成 max_tokens1500 ) return response.choices[0].message.content except Exception as e: return f调用模型 API 时出错{e} def extract_code_from_response(self, response: str) - str: 从模型的响应中提取 python 代码块内的内容 lines response.split(\n) in_code_block False code_lines [] for line in lines: if line.strip().startswith(python): in_code_block True continue elif line.strip().startswith() and in_code_block: in_code_block False break elif in_code_block: code_lines.append(line) return \n.join(code_lines).strip() def run(self): 运行代理的主循环 print( AI 代码优先代理助手 ) print(输入您的问题输入 quit 或 exit 退出) print(- * 40) while True: try: user_input input(\n您: ).strip() if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input: continue print(助手: 思考中...) # 1. 生成响应可能包含代码 llm_response self.generate_code(user_input) # 2. 尝试提取并执行代码 code_to_execute self.extract_code_from_response(llm_response) if code_to_execute: print(f生成代码:\npython\n{code_to_execute}\n) print(执行代码...) success, result, output self.executor.execute_code( code_to_execute, global_varsself.tool_globals ) if success: if output: print(f代码输出:\n{output}) if result is not None: print(f执行结果: {result}) # 可以将结果反馈给模型进行总结这里简化处理直接输出 print(f\n答案: {result}) else: print(代码已执行但未设置 final_result 变量。) # 显示模型的原始回复中非代码部分 non_code_part llm_response.replace(fpython\n{code_to_execute}\n, ).strip() if non_code_part: print(f模型补充说明: {non_code_part}) else: print(f代码执行失败\n错误信息:\n{output}) print(f模型的原始回复:\n{llm_response}) else: # 如果没有提取到代码直接显示模型的回复可能是纯文本回答 print(f{llm_response}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f发生未知错误: {e}) if __name__ __main__: agent CodeFirstAgent() agent.run()4.3 运行与验证现在让我们启动助手并进行测试。确保你的虚拟环境已激活并且.env文件中的 API 密钥已正确设置。在终端运行python main.py你将看到提示符可以开始输入问题。测试用例 1数学计算您: 计算 3 的 4 次方加上 10 除以 2。 助手: 思考中... 生成代码: python import math final_result (3 ** 4) (10 / 2)执行代码... 执行结果: 86.0 答案: 86.0**测试用例 2使用自定义工具**您: 北京和广州的天气怎么样哪个更热 助手: 思考中... 生成代码:weather_bj get_mock_weather(北京) weather_gz get_mock_weather(广州) result_bj f{weather_bj[city]}: {weather_bj[temp]}°C, {weather_bj[condition]} result_gz f{weather_gz[city]}: {weather_gz[temp]}°C, {weather_gz[condition]} if weather_bj[temp] weather_gz[temp]: hotter 北京更热。 elif weather_bj[temp] weather_gz[temp]: hotter 广州更热。 else: hotter 两地温度相同。 final_result f{result_bj}\n{result_gz}\n{hotter}执行代码... 执行结果: 北京: 22°C, 晴朗 广州: 28°C, 阵雨 广州更热。 答案: 北京: 22°C, 晴朗 广州: 28°C, 阵雨 广州更热。**测试用例 3复杂逻辑与库使用**您: 我有一个数据列表[{name:Alice,age:30},{name:Bob,age:25},{name:Charlie,age:30}]请帮我找出所有年龄等于30的人的名字。 助手: 思考中... 生成代码:data [{name:Alice,age:30},{name:Bob,age:25},{name:Charlie,age:30}] filtered filter_data(data, age, 30) names [item[name] for item in filtered] final_result names执行代码... 执行结果: [Alice, Charlie] 答案: [Alice, Charlie]### 4.4 结果说明 通过这个实战项目我们成功构建了一个“代码优先”的 AI 代理。它能够 * **理解自然语言需求**。 * **自主规划**并生成调用我们预定义工具或标准库的 **Python 代码**。 * **在安全沙箱中执行**生成的代码。 * **返回结构化的结果**。 这完美诠释了“工具调用转向代码优先”的理念。模型不再输出 {function: “get_weather”, “arguments”: ...} 这样的 JSON而是输出一段解决问题的 **程序逻辑**。这大大增强了其处理复杂、多步骤任务的能力。 ## 5. 常见问题与排查思路 在实际使用和扩展这个代理时你可能会遇到以下问题 | 问题现象 | 常见原因 | 解决思路 | | :--- | :--- | :--- | | **ModuleNotFoundError 或导入错误** | 1. ALLOWED_MODULES 白名单未包含所需库。br2. 生成的代码尝试导入危险模块如 os。 | 1. 检查 safe_executor.py 中的 ALLOWED_MODULES添加缺失的库名如 numpy。br2. 这是安全机制在起作用。需要优化系统提示词明确告知模型可用的库或引导其使用已注入的工具函数。 | | **代码执行成功但 final_result 为 None** | 1. 模型生成的代码没有给 final_result 变量赋值。br2. 代码逻辑错误结果存到了其他变量。 | 1. 强化系统提示词明确要求“将最终答案赋值给 final_result”。br2. 在执行后打印 local_vars 和 safe_globals 查看所有变量或在提示词中要求模型打印关键结果。 | | **模型不生成代码只进行文本回答** | 1. 问题太简单模型认为无需代码。br2. 系统提示词不够清晰模型未进入“代码生成”模式。 | 1. 这是正常行为对于简单问题文本回答更高效。br2. 在提示词中增加更多强制性的指令例如“对于涉及计算、数据获取或处理的问题**必须**生成代码。” | | **生成的代码有语法错误或逻辑错误** | 1. 模型本身存在“幻觉”或代码生成能力不足。br2. 提示词中对工具的描述有歧义。 | 1. 尝试使用代码能力更强的模型如 GPT-4, Claude-3.5-Sonnet, DeepSeek-Coder。br2. 在 TOOL_DESCRIPTIONS 中提供更精确、无歧义的工具函数签名和示例。 | | **API 调用失败网络、鉴权** | 1. .env 文件中的 OPENAI_API_KEY 未设置或错误。br2. 网络连接问题。br3. 使用的 base_url 或 model 名称不正确。 | 1. 检查 .env 文件路径和内容确保密钥正确。br2. 检查网络如果使用其他服务商确认其 API 状态和可用性。br3. 查阅对应服务商的文档确认端点和模型名。 | | **执行超时或卡死** | 1. 模型生成了死循环代码。br2. 代码执行了非常耗时的操作如下载大文件。 | 1. 在执行器 execute_code 中加入超时机制例如使用 signal 或 multiprocessing 限制执行时间。br2. 在提示词中告诫模型避免生成无限循环或耗时操作。 | ## 6. 最佳实践与工程建议 将“代码优先”代理用于实际项目时请遵循以下建议以确保其鲁棒性、安全性和可维护性。 ### 6.1 安全是第一要务 * **强化沙箱**示例中的 SafeExecutor 是极简版。生产环境务必使用更隔离的方案例如 * **Docker 容器**为每次代码执行启动一个崭新的、无网络、只读文件系统的临时容器。 * **专用沙箱库**评估使用 RestrictedPython、PyPy 沙箱模式等。 * **系统调用拦截**在操作系统层面使用 seccomp、ptrace 等限制系统调用。 * **严格的白名单**仅允许执行任务所必需的最小权限模块和函数。定期审计 ALLOWED_MODULES。 * **资源限制**对代码执行时间、内存使用量、CPU 时间进行严格限制。 * **输入审查**虽然模型生成代码但用户输入也可能包含恶意指令试图“提示注入”模型。对用户输入进行基本的恶意模式过滤。 ### 6.2 优化提示词工程 * **清晰的角色与约束**系统提示词必须明确、无歧义地定义代理的角色、可用工具、输出格式代码块和结果变量final_result。 * **提供高质量示例**在提示词中包含 3-5 个覆盖不同工具和场景的 **高质量示例**Few-Shot Learning能极大提升模型生成代码的准确率和格式符合度。 * **迭代与测试**针对你的特定领域任务收集一批测试用例不断优化提示词直到模型能稳定生成正确代码。 ### 6.3 设计健壮的工具库 * **工具函数应幂等、无副作用**理想情况下工具函数不应修改外部状态数据库、文件除非这是其明确目的。这使调试和回滚更容易。 * **完善的错误处理**工具函数内部应有 try-except返回结构化的错误信息而不是抛出异常导致整个代理崩溃。执行器也应能捕获并报告工具错误。 * **类型注解与文档**如示例所示为每个工具函数编写清晰的文档字符串docstring和类型注解这不仅能帮助开发者也能让 LLM 更好地理解工具用途。 ### 6.4 架构与可扩展性 * **动态工具加载**不要像示例中那样硬编码 TOOL_DESCRIPTIONS。可以设计一个工具注册机制自动扫描特定目录下的 Python 文件提取函数和文档来动态构建提示词。 * **结果验证与后处理**模型生成的代码可能产生非预期格式的结果。可以设计一套后处理规则对 final_result 进行类型检查、格式转换或摘要生成再呈现给用户。 * **会话与状态管理**当前的代理是无状态的。复杂的任务可能需要多轮对话。你需要维护会话历史并在提示词中包含相关上下文让模型能引用之前代码执行的结果。 * **Fallback 机制**如果代码执行失败或者模型多次生成错误代码应有降级策略例如切换到一个更简单的“文本回答”模式或者请求人工干预。 ### 6.5 性能与成本 * **缓存**对于相同或相似的查询可以缓存模型生成的代码片段和执行结果避免重复调用昂贵的 LLM API 和执行相同计算。 * **模型选择**代码生成任务上专门的代码模型如 Claude-3.5-Sonnet、DeepSeek-Coder、GPT-4通常比通用聊天模型表现更好。根据任务复杂度、成本和延迟要求进行选择。 * **本地模型部署**对于数据敏感或高并发场景考虑使用 Ollama、vLLM 等工具在本地部署开源代码模型如 CodeLlama、Qwen2.5-Coder可以彻底控制数据和成本。 “代码优先”的范式为大语言模型的应用打开了新的大门使其从“聊天机器人”真正向“自主代理”迈进。通过本次从零到一的实战希望你不仅理解了其原理也掌握了构建一个基础但功能完整的代码优先 AI 代理的方法。记住核心在于**安全的代码执行**、**清晰的工具描述**和**精准的提示词引导**。接下来你可以尝试为你的代理添加更多强大的工具如数据库查询、发送邮件、调用内部 API或将其集成到你的 Web 应用、自动化流程中解锁更多可能性。如果在实践中遇到问题欢迎在评论区交流探讨。 大语言模型工具调用：从JSON函数调用到代码优先范式的实战指南
大家好最近在探索大语言模型LLM的“工具调用”功能时我发现了一个非常有趣且重要的趋势传统的、依赖结构化 JSON 格式的“函数调用”模式正在被一种更灵活、更强大的“代码优先”范式所取代。有研究甚至表明在测试的 14 个主流模型中有 11 个在“代码优先”模式下表现更优。这不仅仅是 API 调用方式的变化它深刻地影响着我们如何设计 AI 代理、构建自动化流程以及集成外部服务。今天我们就来彻底搞懂这个转变并通过 Python 实战让你亲手体验“代码优先”工具调用的强大之处。无论你是正在构建 AI 助手的开发者还是希望更高效利用大模型能力的工程师理解并掌握“代码优先”的方法都将让你在设计和实现上领先一步。本文将带你从概念理解到环境搭建再到一个完整的、可运行的本地 AI 代理助手项目实战最后深入探讨最佳实践和避坑指南。1. 背景与核心概念从“函数调用”到“代码优先”在深入代码之前我们必须先厘清几个关键概念明白我们为什么要做出这样的转变。1.1 什么是工具调用工具调用简单来说就是让大语言模型如 GPT-4、Claude、DeepSeek 等能够识别用户请求中的意图并决定是否需要调用一个外部工具如计算器、搜索引擎、数据库、自定义 API来完成任务然后将工具执行的结果整合进最终的回复中。例如用户问“北京今天的天气怎么样”模型本身并不知道实时天气但它可以“调用”一个“获取天气”的工具一个 API获取数据后再生成回答“北京今天晴气温 25°C。”1.2 传统的“函数调用”模式及其痛点最初OpenAI 等厂商定义了“函数调用”的范式。其核心流程是定义开发者需要预先、精确地以 JSON Schema 格式定义好每个工具函数的名称、描述、参数及其类型。{ name: get_weather, description: 获取指定城市的天气, parameters: { type: object, properties: { location: { type: string, description: 城市名例如北京 } }, required: [location] } }调用将用户问题和这些函数定义一起发送给模型。模型返回一个结构化的 JSON指明它想调用哪个函数以及具体的参数。{ function: get_weather, arguments: {\location\: \北京\} }执行你的程序解析这个 JSON找到对应的本地函数get_weather(“北京”)并执行。回复将执行结果返回给模型模型生成最终回答。这种模式的痛点僵化工具必须在对话前完全定义好难以动态增删。复杂JSON Schema 编写繁琐容易出错特别是嵌套结构。依赖严重依赖模型对特定 JSON 格式的理解和生成能力。不自然不符合开发者“写代码”的直觉更像是配置而非编程。1.3 新兴的“代码优先”范式及其优势“代码优先”范式应运而生。其核心思想是让模型直接生成可执行代码通常是 Python 代码片段来调用工具而不是生成一个描述调用的 JSON。它的流程更像是准备你告诉模型可用的工具库例如requests库可以发 HTTP 请求pandas可以处理数据或者你自定义的函数。生成模型根据你的问题直接生成一段包含工具调用逻辑的 Python 代码。# 模型生成的代码 import requests response requests.get(https://api.weather.com/v1/city/北京) weather_data response.json() current_temp weather_data[current][temp]执行在一个安全的沙箱环境中运行这段代码获取结果。回复将代码执行的结果或结果摘要提供给模型生成最终回答。“代码优先”的优势灵活强大代码可以表达复杂的逻辑循环、条件判断、多步操作而 JSON 只能描述静态结构。开发者友好直接用 Python 等语言描述工具更符合开发习惯。动态性工具集可以更容易地动态加载和扩展。表现更优正如研究指出的许多模型生成代码的能力优于生成特定结构的 JSON因此在“代码优先”模式下工具调用的准确率和成功率更高。简单来说从“JSON 配置驱动”转向“代码生成驱动”是工具调用领域一次重要的范式升级。2. 环境准备与版本说明接下来我们将通过一个实战项目来体验“代码优先”的魅力。我们将构建一个本地运行的 AI 代理助手它可以调用 Python 代码来解决问题。2.1 项目目标创建一个命令行 AI 助手能够理解自然语言指令并自动编写/执行 Python 代码来完成诸如计算、数据处理、获取网络信息模拟、文件操作等任务。2.2 环境与工具操作系统Windows 10/11, macOS, 或 Linux (本文以 macOS/Linux 命令行示例为主Windows 用户建议使用 WSL 或 Git Bash)。Python版本 3.8。我们将使用一些较新的语法特性。包管理工具pip。核心库openai用于调用大语言模型 API。我们将使用 OpenAI 兼容的 API例如来自Groq、Together AI或本地部署的Ollama提供的兼容接口。python-dotenv管理环境变量安全存储 API 密钥。可选/备用本地模型库ollama。如果你想完全在本地运行可以使用 Ollama 部署开源模型如llama3.2、qwen2.5等它们也支持类似的功能。代码执行沙箱我们将实现一个简单的、安全的代码执行器。2.3 项目结构初始化首先创建一个项目文件夹并初始化虚拟环境这是管理 Python 依赖的最佳实践。# 创建项目目录 mkdir ai_code_agent cd ai_code_agent # 创建虚拟环境 (Python 3.8) python3 -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 创建必要的文件 touch main.py tool_library.py safe_executor.py .env requirements.txt2.4 安装依赖编辑requirements.txt文件填入以下内容openai1.0.0 python-dotenv1.0.0 requests2.28.0 # 用于我们的示例网络工具 pandas2.0.0 # 用于示例数据处理工具然后安装它们pip install -r requirements.txt如果你的网络环境需要配置请使用可靠的网络连接。至此基础环境就准备好了。3. 核心组件拆解构建“代码优先”代理的三要素一个基本的“代码优先”AI代理通常包含三个核心部分工具库、代码生成器LLM和安全执行器。3.1 工具库让 AI 知道它能用什么在“代码优先”模式下我们不是用 JSON 定义工具而是准备一个真实的 Python 模块其中包含一些函数并赋予它们清晰的功能描述。这些描述将作为“系统提示词”的一部分教给模型。创建tool_library.py# tool_library.py import requests import pandas as pd import json import math from datetime import datetime from typing import Any, Dict, List # 示例工具 1: 数学计算 def calculate(expression: str) - float: 计算一个数学表达式。 注意使用 eval在实际生产环境中应对输入进行严格检查或使用更安全的替代方案如 ast.literal_eval。 参数: expression (str): 数学表达式例如 3 5 * 2, sqrt(16) 返回: float: 计算结果 # 为表达式添加常用的数学函数 safe_dict {k: v for k, v in math.__dict__.items() if not k.startswith(_)} safe_dict[abs] abs # 警告此处为示例简化eval 有安全风险 result eval(expression, {__builtins__: None}, safe_dict) return float(result) # 示例工具 2: 获取模拟的天气数据避免真实 API 调用 def get_mock_weather(city: str) - Dict[str, Any]: 获取指定城市的模拟天气数据。 参数: city (str): 城市名称 返回: dict: 包含天气信息的字典例如 {city: 北京, temp: 22, condition: 晴朗} # 模拟数据 mock_data { 北京: {temp: 22, condition: 晴朗}, 上海: {temp: 25, condition: 多云}, 广州: {temp: 28, condition: 阵雨}, 深圳: {temp: 27, condition: 阴天}, } return {city: city, **mock_data.get(city, {temp: 20, condition: 未知})} # 示例工具 3: 获取网页标题模拟 def fetch_webpage_title(url: str) - str: 获取给定 URL 的网页标题模拟版。 在实际应用中这里会使用 requests 和 BeautifulSoup 解析真实网页。 参数: url (str): 网页 URL 返回: str: 网页标题如果失败则返回错误信息。 # 模拟响应 mock_titles { https://www.example.com: Example Domain, https://www.csdn.net: CSDN - 专业开发者社区, https://github.com: GitHub: Let’s build from here } return mock_titles.get(url, f无法获取 {url} 的标题模拟模式) # 示例工具 4: 简单的数据过滤 def filter_data(data: List[Dict], key: str, value: Any) - List[Dict]: 过滤字典列表返回指定键等于给定值的所有项。 参数: data (List[Dict]): 字典列表 key (str): 用于过滤的键 value (Any): 匹配的值 返回: List[Dict]: 过滤后的列表 return [item for item in data if item.get(key) value] # 我们可以导出一个工具描述列表用于构建系统提示词 TOOL_DESCRIPTIONS 你可以使用以下 Python 工具来帮助用户 1. calculate(expression): 计算数学表达式如 calculate(3 5 * 2)。 2. get_mock_weather(city): 获取城市的模拟天气信息如 get_mock_weather(北京)。 3. fetch_webpage_title(url): 获取模拟的网页标题如 fetch_webpage_title(https://www.example.com)。 4. filter_data(data, key, value): 过滤字典列表如 filter_data([{name:a},{name:b}], name, a)。 此外你还可以使用标准库如 json, datetime, math和已安装的第三方库如 pandas 作为 pd, requests。 当你需要完成一个任务时请直接生成可运行的 Python 代码片段。代码应该专注于获取结果并最终将核心结果赋值给一个名为 final_result 的变量。 关键点TOOL_DESCRIPTIONS变量包含了所有工具的自然语言描述这将被插入到给 LLM 的系统提示词中告诉模型“你能做什么以及如何调用”。这就是“代码优先”中“工具定义”的形态。3.2 安全执行器在沙箱中运行模型生成的代码允许模型生成并执行任意代码是极其危险的。我们必须创建一个受限制的执行环境。创建safe_executor.py# safe_executor.py import sys import io import traceback from contextlib import redirect_stdout, redirect_stderr from typing import Tuple, Any # 定义允许访问的模块白名单 ALLOWED_MODULES { math, datetime, json, random, re, collections, itertools, typing, pandas, numpy, requests # 根据你的工具库添加 } class SafeExecutor: def __init__(self, allowed_modulesNone): self.allowed_modules allowed_modules or ALLOWED_MODULES self._imported_modules {} def _safe_import(self, name, *args, **kwargs): 自定义的导入函数只允许导入白名单中的模块 if name in self.allowed_modules: # 实际导入模块 module __import__(name) # 处理子模块导入如 from pandas import DataFrame if args: # 这里简化处理实际可能需要更复杂的逻辑 return getattr(module, args[0], None) return module else: raise ImportError(f模块 {name} 不在允许列表中禁止导入。) def execute_code(self, code: str, global_vars: dict None, local_vars: dict None) - Tuple[bool, Any, str]: 在受限制的环境中执行一段 Python 代码。 参数: code (str): 要执行的 Python 代码字符串 global_vars (dict): 全局变量字典可用于传入工具函数 local_vars (dict): 局部变量字典 返回: Tuple[bool, Any, str]: (执行是否成功, 执行结果, 输出/错误信息) if global_vars is None: global_vars {} if local_vars is None: local_vars {} # 创建一个安全的全局命名空间 safe_globals { __builtins__: { print: print, len: len, str: str, int: int, float: float, list: list, dict: dict, range: range, __import__: self._safe_import, # 替换默认的 import }, **global_vars # 将工具函数等注入进来 } # 重定向标准输出和错误以便捕获 stdout_capture io.StringIO() stderr_capture io.StringIO() result None success False full_output try: with redirect_stdout(stdout_capture), redirect_stderr(stderr_capture): # 执行代码 exec(code, safe_globals, local_vars) # 尝试从局部或全局变量中获取名为 final_result 的结果 result local_vars.get(final_result, safe_globals.get(final_result)) success True except Exception as e: # 捕获所有异常并获取详细的错误信息 error_trace traceback.format_exc() stderr_capture.write(error_trace) # 合并输出和错误信息 stdout_output stdout_capture.getvalue() stderr_output stderr_capture.getvalue() full_output stdout_output stderr_output return success, result, full_output.strip()安全核心替换__import__我们覆盖了内置的导入函数只允许导入白名单ALLOWED_MODULES中的模块。这可以防止导入os,sys,subprocess等危险模块。限制__builtins__我们只提供了少数几个安全的 built-in 函数移除了open,eval,exec,__import__已被替换等。沙箱执行使用exec在隔离的命名空间中运行代码。结果捕获代码执行后我们期望它将主要结果赋值给变量final_result执行器会尝试提取它。同时所有print输出和错误信息都会被捕获并返回。重要警告这个执行器是基础示例并非绝对安全。生产环境需要更严格的沙箱如使用docker容器隔离、PyPy沙箱或专门的库如RestrictedPython。此处主要用于演示原理。3.3 代码生成器与大语言模型对话这是代理的大脑。我们将使用 OpenAI 兼容的 API并设计一个特定的提示词引导模型生成解决问题的代码。4. 完整实战案例构建本地 AI 代码代理助手现在我们将把上述组件组装起来创建main.py。4.1 配置 API 密钥与环境首先在项目根目录创建.env文件用于存储你的 API 密钥。如果你使用 OpenAI格式如下。如果你使用 Groq、Together AI 或本地 Ollama请参考其文档修改BASE_URL和MODEL。# .env OPENAI_API_KEYsk-your-actual-api-key-here # 如果使用其他兼容服务例如 Groq # OPENAI_BASE_URLhttps://api.groq.com/openai/v1 # OPENAI_MODELllama3-70b-8192注意.env文件包含敏感信息务必将其添加到.gitignore中不要提交到版本控制系统。4.2 编写主程序逻辑编辑main.py# main.py import os import sys from openai import OpenAI from dotenv import load_dotenv from tool_library import TOOL_DESCRIPTIONS, calculate, get_mock_weather, fetch_webpage_title, filter_data from safe_executor import SafeExecutor # 加载环境变量 load_dotenv() class CodeFirstAgent: def __init__(self): # 初始化 OpenAI 客户端 api_key os.getenv(OPENAI_API_KEY) if not api_key: print(错误未找到 OPENAI_API_KEY。请在 .env 文件中设置。) sys.exit(1) self.client OpenAI( api_keyapi_key, # 如果你使用非 OpenAI 官方端点取消下面的注释并设置 # base_urlos.getenv(OPENAI_BASE_URL, https://api.openai.com/v1) ) self.model os.getenv(OPENAI_MODEL, gpt-4o-mini) # 可根据需要调整模型 # 初始化安全执行器并注入我们的工具函数 self.executor SafeExecutor() self.tool_globals { calculate: calculate, get_mock_weather: get_mock_weather, fetch_webpage_title: fetch_webpage_title, filter_data: filter_data, final_result: None, # 预留结果变量 } # 构建系统提示词 - 这是引导模型生成代码的关键 self.system_prompt f你是一个强大的 AI 助手能够通过编写和执行 Python 代码来解决用户问题。 你的核心能力是“代码优先”工具调用。 {TOOL_DESCRIPTIONS} **你的工作流程** 1. 仔细分析用户的问题。 2. 判断是否需要使用上述工具或 Python 库来解决问题。 3. **如果需要生成一段简洁、完整、可独立运行的 Python 代码片段。** 4. 代码的目标是计算出用户问题的答案。 5. 代码的最后请将最终答案一个字符串、数字、列表或字典赋值给一个名为 final_result 的变量。 6. 如果问题很简单无需额外工具可以直接推理回答则不必生成代码。 **代码生成示例** 用户计算圆周率乘以 10 的平方。 助手python import math final_result math.pi * (10 ** 2)用户北京和上海哪个温度高 助手python weather_beijing get_mock_weather(北京) weather_shanghai get_mock_weather(上海) if weather_beijing[temp] weather_shanghai[temp]: final_result 北京温度更高。 elif weather_beijing[temp] weather_shanghai[temp]: final_result 上海温度更高。 else: final_result 两地温度相同。现在请开始帮助用户。如果生成代码请将代码包裹在 python 代码块中。 def generate_code(self, user_query: str) - str: 调用 LLM根据用户查询生成 Python 代码 try: response self.client.chat.completions.create( modelself.model, messages[ {role: system, content: self.system_prompt}, {role: user, content: user_query} ], temperature0.1, # 低温度使输出更确定专注于代码生成 max_tokens1500 ) return response.choices[0].message.content except Exception as e: return f调用模型 API 时出错{e} def extract_code_from_response(self, response: str) - str: 从模型的响应中提取 python 代码块内的内容 lines response.split(\n) in_code_block False code_lines [] for line in lines: if line.strip().startswith(python): in_code_block True continue elif line.strip().startswith() and in_code_block: in_code_block False break elif in_code_block: code_lines.append(line) return \n.join(code_lines).strip() def run(self): 运行代理的主循环 print( AI 代码优先代理助手 ) print(输入您的问题输入 quit 或 exit 退出) print(- * 40) while True: try: user_input input(\n您: ).strip() if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input: continue print(助手: 思考中...) # 1. 生成响应可能包含代码 llm_response self.generate_code(user_input) # 2. 尝试提取并执行代码 code_to_execute self.extract_code_from_response(llm_response) if code_to_execute: print(f生成代码:\npython\n{code_to_execute}\n) print(执行代码...) success, result, output self.executor.execute_code( code_to_execute, global_varsself.tool_globals ) if success: if output: print(f代码输出:\n{output}) if result is not None: print(f执行结果: {result}) # 可以将结果反馈给模型进行总结这里简化处理直接输出 print(f\n答案: {result}) else: print(代码已执行但未设置 final_result 变量。) # 显示模型的原始回复中非代码部分 non_code_part llm_response.replace(fpython\n{code_to_execute}\n, ).strip() if non_code_part: print(f模型补充说明: {non_code_part}) else: print(f代码执行失败\n错误信息:\n{output}) print(f模型的原始回复:\n{llm_response}) else: # 如果没有提取到代码直接显示模型的回复可能是纯文本回答 print(f{llm_response}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f发生未知错误: {e}) if __name__ __main__: agent CodeFirstAgent() agent.run()4.3 运行与验证现在让我们启动助手并进行测试。确保你的虚拟环境已激活并且.env文件中的 API 密钥已正确设置。在终端运行python main.py你将看到提示符可以开始输入问题。测试用例 1数学计算您: 计算 3 的 4 次方加上 10 除以 2。 助手: 思考中... 生成代码: python import math final_result (3 ** 4) (10 / 2)执行代码... 执行结果: 86.0 答案: 86.0**测试用例 2使用自定义工具**您: 北京和广州的天气怎么样哪个更热 助手: 思考中... 生成代码:weather_bj get_mock_weather(北京) weather_gz get_mock_weather(广州) result_bj f{weather_bj[city]}: {weather_bj[temp]}°C, {weather_bj[condition]} result_gz f{weather_gz[city]}: {weather_gz[temp]}°C, {weather_gz[condition]} if weather_bj[temp] weather_gz[temp]: hotter 北京更热。 elif weather_bj[temp] weather_gz[temp]: hotter 广州更热。 else: hotter 两地温度相同。 final_result f{result_bj}\n{result_gz}\n{hotter}执行代码... 执行结果: 北京: 22°C, 晴朗 广州: 28°C, 阵雨 广州更热。 答案: 北京: 22°C, 晴朗 广州: 28°C, 阵雨 广州更热。**测试用例 3复杂逻辑与库使用**您: 我有一个数据列表[{name:Alice,age:30},{name:Bob,age:25},{name:Charlie,age:30}]请帮我找出所有年龄等于30的人的名字。 助手: 思考中... 生成代码:data [{name:Alice,age:30},{name:Bob,age:25},{name:Charlie,age:30}] filtered filter_data(data, age, 30) names [item[name] for item in filtered] final_result names执行代码... 执行结果: [Alice, Charlie] 答案: [Alice, Charlie]### 4.4 结果说明 通过这个实战项目我们成功构建了一个“代码优先”的 AI 代理。它能够 * **理解自然语言需求**。 * **自主规划**并生成调用我们预定义工具或标准库的 **Python 代码**。 * **在安全沙箱中执行**生成的代码。 * **返回结构化的结果**。 这完美诠释了“工具调用转向代码优先”的理念。模型不再输出 {function: “get_weather”, “arguments”: ...} 这样的 JSON而是输出一段解决问题的 **程序逻辑**。这大大增强了其处理复杂、多步骤任务的能力。 ## 5. 常见问题与排查思路 在实际使用和扩展这个代理时你可能会遇到以下问题 | 问题现象 | 常见原因 | 解决思路 | | :--- | :--- | :--- | | **ModuleNotFoundError 或导入错误** | 1. ALLOWED_MODULES 白名单未包含所需库。br2. 生成的代码尝试导入危险模块如 os。 | 1. 检查 safe_executor.py 中的 ALLOWED_MODULES添加缺失的库名如 numpy。br2. 这是安全机制在起作用。需要优化系统提示词明确告知模型可用的库或引导其使用已注入的工具函数。 | | **代码执行成功但 final_result 为 None** | 1. 模型生成的代码没有给 final_result 变量赋值。br2. 代码逻辑错误结果存到了其他变量。 | 1. 强化系统提示词明确要求“将最终答案赋值给 final_result”。br2. 在执行后打印 local_vars 和 safe_globals 查看所有变量或在提示词中要求模型打印关键结果。 | | **模型不生成代码只进行文本回答** | 1. 问题太简单模型认为无需代码。br2. 系统提示词不够清晰模型未进入“代码生成”模式。 | 1. 这是正常行为对于简单问题文本回答更高效。br2. 在提示词中增加更多强制性的指令例如“对于涉及计算、数据获取或处理的问题**必须**生成代码。” | | **生成的代码有语法错误或逻辑错误** | 1. 模型本身存在“幻觉”或代码生成能力不足。br2. 提示词中对工具的描述有歧义。 | 1. 尝试使用代码能力更强的模型如 GPT-4, Claude-3.5-Sonnet, DeepSeek-Coder。br2. 在 TOOL_DESCRIPTIONS 中提供更精确、无歧义的工具函数签名和示例。 | | **API 调用失败网络、鉴权** | 1. .env 文件中的 OPENAI_API_KEY 未设置或错误。br2. 网络连接问题。br3. 使用的 base_url 或 model 名称不正确。 | 1. 检查 .env 文件路径和内容确保密钥正确。br2. 检查网络如果使用其他服务商确认其 API 状态和可用性。br3. 查阅对应服务商的文档确认端点和模型名。 | | **执行超时或卡死** | 1. 模型生成了死循环代码。br2. 代码执行了非常耗时的操作如下载大文件。 | 1. 在执行器 execute_code 中加入超时机制例如使用 signal 或 multiprocessing 限制执行时间。br2. 在提示词中告诫模型避免生成无限循环或耗时操作。 | ## 6. 最佳实践与工程建议 将“代码优先”代理用于实际项目时请遵循以下建议以确保其鲁棒性、安全性和可维护性。 ### 6.1 安全是第一要务 * **强化沙箱**示例中的 SafeExecutor 是极简版。生产环境务必使用更隔离的方案例如 * **Docker 容器**为每次代码执行启动一个崭新的、无网络、只读文件系统的临时容器。 * **专用沙箱库**评估使用 RestrictedPython、PyPy 沙箱模式等。 * **系统调用拦截**在操作系统层面使用 seccomp、ptrace 等限制系统调用。 * **严格的白名单**仅允许执行任务所必需的最小权限模块和函数。定期审计 ALLOWED_MODULES。 * **资源限制**对代码执行时间、内存使用量、CPU 时间进行严格限制。 * **输入审查**虽然模型生成代码但用户输入也可能包含恶意指令试图“提示注入”模型。对用户输入进行基本的恶意模式过滤。 ### 6.2 优化提示词工程 * **清晰的角色与约束**系统提示词必须明确、无歧义地定义代理的角色、可用工具、输出格式代码块和结果变量final_result。 * **提供高质量示例**在提示词中包含 3-5 个覆盖不同工具和场景的 **高质量示例**Few-Shot Learning能极大提升模型生成代码的准确率和格式符合度。 * **迭代与测试**针对你的特定领域任务收集一批测试用例不断优化提示词直到模型能稳定生成正确代码。 ### 6.3 设计健壮的工具库 * **工具函数应幂等、无副作用**理想情况下工具函数不应修改外部状态数据库、文件除非这是其明确目的。这使调试和回滚更容易。 * **完善的错误处理**工具函数内部应有 try-except返回结构化的错误信息而不是抛出异常导致整个代理崩溃。执行器也应能捕获并报告工具错误。 * **类型注解与文档**如示例所示为每个工具函数编写清晰的文档字符串docstring和类型注解这不仅能帮助开发者也能让 LLM 更好地理解工具用途。 ### 6.4 架构与可扩展性 * **动态工具加载**不要像示例中那样硬编码 TOOL_DESCRIPTIONS。可以设计一个工具注册机制自动扫描特定目录下的 Python 文件提取函数和文档来动态构建提示词。 * **结果验证与后处理**模型生成的代码可能产生非预期格式的结果。可以设计一套后处理规则对 final_result 进行类型检查、格式转换或摘要生成再呈现给用户。 * **会话与状态管理**当前的代理是无状态的。复杂的任务可能需要多轮对话。你需要维护会话历史并在提示词中包含相关上下文让模型能引用之前代码执行的结果。 * **Fallback 机制**如果代码执行失败或者模型多次生成错误代码应有降级策略例如切换到一个更简单的“文本回答”模式或者请求人工干预。 ### 6.5 性能与成本 * **缓存**对于相同或相似的查询可以缓存模型生成的代码片段和执行结果避免重复调用昂贵的 LLM API 和执行相同计算。 * **模型选择**代码生成任务上专门的代码模型如 Claude-3.5-Sonnet、DeepSeek-Coder、GPT-4通常比通用聊天模型表现更好。根据任务复杂度、成本和延迟要求进行选择。 * **本地模型部署**对于数据敏感或高并发场景考虑使用 Ollama、vLLM 等工具在本地部署开源代码模型如 CodeLlama、Qwen2.5-Coder可以彻底控制数据和成本。 “代码优先”的范式为大语言模型的应用打开了新的大门使其从“聊天机器人”真正向“自主代理”迈进。通过本次从零到一的实战希望你不仅理解了其原理也掌握了构建一个基础但功能完整的代码优先 AI 代理的方法。记住核心在于**安全的代码执行**、**清晰的工具描述**和**精准的提示词引导**。接下来你可以尝试为你的代理添加更多强大的工具如数据库查询、发送邮件、调用内部 API或将其集成到你的 Web 应用、自动化流程中解锁更多可能性。如果在实践中遇到问题欢迎在评论区交流探讨。