基于OpenAI Function Calling的LLM工具与智能体开发实践

1. 项目概述用熟悉的语言为LLM打造专属工具与智能体如果你和我一样既对大型语言模型LLM的能力感到兴奋又对如何将其无缝集成到实际工作流中感到头疼那么sigoden/llm-functions这个项目绝对值得你花时间深入了解。简单来说它解决了一个核心痛点如何让我们用最熟悉的编程语言Bash、JavaScript、Python快速为LLM创建可调用的函数工具和更复杂的智能体Agent而无需陷入复杂的框架集成和API封装中。这就像为LLM这个“大脑”配上了一双灵巧的“手”让它不仅能思考还能直接操作你的系统、处理数据、调用外部服务。想象一下你可以用几行Bash脚本就做出一个“执行系统命令”的工具或者用Python写一个“分析日志文件”的函数然后直接让ChatGPT、Claude这类模型在对话中调用它们。llm-functions正是基于OpenAI的Function Calling机制构建的但它将实现门槛降到了最低。目前它主要与AIChat这个命令行工具配合使用提供了一个极其轻量、以开发者为中心的本地化方案。无论你是想自动化日常运维任务、构建一个个人知识管理助手还是探索AI智能体的可能性这个项目都提供了一个清晰、可扩展的起点。接下来我将带你从零开始拆解它的设计思路、手把手完成部署并分享如何定制属于你自己的AI工具。2. 核心设计思路与架构解析2.1 为什么是“Function Calling”要理解llm-functions的价值首先要明白LLM的局限性。纯粹的对话模型是一个“黑盒”它擅长生成文本但无法直接操作你的电脑、查询实时信息或运行特定代码。Function Calling函数调用是一种协议它允许LLM在对话中识别用户的意图并“决定”需要调用哪个预定义的外部函数来完成任务然后将函数的执行结果返回给LLM由LLM整合后回复给用户。llm-functions的核心贡献在于它标准化并简化了“函数”的定义和调用流程。它没有发明新轮子而是巧妙地利用了现有生态语言无界你可以用任何你熟悉的脚本语言Bash/JS/Py编写工具逻辑。声明即生成通过规范的代码注释如JSDoc、Python docstring工具的描述、参数等信息会被自动提取并生成标准的OpenAI Function Calling格式的JSON声明。统一调度通过argc这个Bash命令行框架作为“粘合剂”统一管理和运行这些用不同语言编写的工具。这种设计使得开发者可以专注于工具本身的业务逻辑“做什么”而将复杂的格式转换、参数解析和LLM交互协议交给框架处理。2.2 项目组件与工作流全景图整个项目围绕几个核心文件和目录工作理解它们的关系至关重要./tools/目录存放所有具体的工具脚本.sh,.js,.py。每个工具都是一个独立的可执行单元。./tools.txt文件一个清单列出你当前希望激活并暴露给LLM使用的工具文件名。./agents/目录存放智能体Agent的定义。每个智能体是一个文件夹包含提示词、专属工具列表、知识文档等。./agents.txt文件清单列出你希望激活的智能体名称。argc项目的核心命令行工具负责根据tools.txt和agents.txt构建最终的函数声明文件(functions.json)和可执行入口(bin/)。AIChat一个支持Function Calling的LLM命令行客户端。llm-functions生成的函数声明需要被AIChat加载才能使用。其工作流可以概括为开发者编写工具/定义智能体 - 编辑清单文件 -argc build构建 - 链接到AIChat- 在对话中使用。这个流程将动态的、代码驱动的工具开发与静态的、声明式的LLM调用桥接了起来。2.3 与MCP模型上下文协议的关联项目还提到了MCPModel Context Protocol这是一个由Anthropic等公司推动的、旨在标准化LLM与外部工具和数据源连接的协议。llm-functions对MCP的支持体现在两个方向作为MCP服务器可以将llm-functions创建的工具和智能体通过MCP协议暴露给任何兼容MCP的客户端如Claude Desktop极大地扩展了使用场景。集成MCP工具可以通过内置的MCP桥接器将外部的MCP工具如数据库连接器、日历接口引入作为llm-functions自身的工具来使用。这体现了项目的前瞻性它不仅是一个封闭的工具集更是一个可以融入更广阔AI生态的开放平台。对于普通用户你可以先从基础的AIChat集成用起对于追求集成的开发者MCP路径提供了企业级应用的可能性。3. 从零开始的完整部署与配置指南3.1 环境准备与依赖安装在开始之前确保你的系统Linux/macOSWindows可通过WSL已准备好以下依赖。这是项目运行的基石。安装argc这是项目的命令运行框架。推荐使用包管理器安装最方便。# 对于 macOS (使用 Homebrew) brew install argc # 对于 Linux (使用 cargo需先安装Rust) cargo install argc # 或者直接从GitHub发布页下载预编译的二进制文件放入系统PATH中。安装后在终端输入argc --version验证是否成功。安装jq一个强大的命令行JSON处理器项目内部用于解析和生成JSON。# macOS brew install jq # Ubuntu/Debian sudo apt-get install jq # CentOS/RHEL sudo yum install jq安装AIChat这是当前与llm-functions配合使用的主要客户端。# 使用 cargo 安装推荐 cargo install --git https://github.com/sigoden/aichat # 或者从 GitHub Releases 页面下载对应平台的二进制文件。安装后运行aichat --version检查。关键一步你需要配置AIChat的API密钥以连接后端LLM如OpenAI, Anthropic等。编辑~/.config/aichat/config.yaml文件如果不存在则创建# 示例配置OpenAI model: openai:gpt-4o-mini # 或 gpt-4-turbo openai-api-key: sk-你的OpenAI密钥 # 你也可以配置其他模型如Claude # model: claude:claude-3-5-sonnet-20241022 # anthropic-api-key: sk-ant-你的Anthropic密钥注意AIChat的模型配置和密钥管理是其自身的功能llm-functions只负责提供“函数”能力。请确保你的API密钥有足够的余额并且所选的模型支持Function CallingGPT-3.5-turbo及以上、Claude 3系列通常都支持。3.2 获取与初始化 llm-functions 项目环境就绪后我们拉取项目代码并进行初始化构建。# 1. 克隆仓库 git clone https://github.com/sigoden/llm-functions cd llm-functions # 2. 选择要使用的工具和智能体 # 编辑 tools.txt 文件取消注释或添加你需要的工具。 # 例如一个基础的工具集可能包含 echo -e get_current_weather.sh\nexecute_command.sh\nweb_search_perplexity.sh tools.txt # 3. 编辑 agents.txt 文件选择智能体。 # 例如使用内置的‘coder’和‘todo’智能体 echo -e coder\ntodo agents.txt # 4. 执行构建命令 # 此命令会读取上面的txt文件在 ./bin 目录下生成可执行脚本并合成一个总的 functions.json。 argc build执行argc build后你应该看到bin/目录下生成了许多以工具名命名的脚本同时根目录下会有一个functions.json文件。这个JSON文件就是所有已激活工具和智能体的“功能说明书”稍后需要被AIChat加载。3.3 链接到 AIChat 并验证现在我们需要让AIChat知道去哪里找这些函数定义。# 方法一创建符号链接推荐一劳永逸 # 这条命令会自动找到AIChat的函数目录并将当前llm-functions目录链接过去。 argc link-to-aichat # 方法二设置环境变量更灵活适合多环境 # 将以下行添加到你的shell配置文件如 ~/.bashrc, ~/.zshrc中 export AICHAT_FUNCTIONS_DIR/你的完整路径/llm-functions # 然后执行 source ~/.zshrc (或 ~/.bashrc) 使配置生效链接完成后强烈建议运行检查命令确保所有依赖和配置都正确argc check这个命令会做几件事检查tools.txt和agents.txt中列出的文件是否存在检查某些工具如需要网络搜索的是否配置了必要的API密钥环境变量检查Node.js或Python工具的运行时环境是否就绪。如果看到任何[ERROR]提示请根据提示信息进行修复。实操心得argc check是排查问题的第一利器。我遇到过因为没设置PERPLEXITY_API_KEY而导致web_search_perplexity.sh工具检查失败的情况。根据错误提示去对应的工具脚本里查看它需要哪些环境变量然后去相应服务商如Perplexity, Tavily申请API密钥并导出问题就解决了。3.4 首次运行测试一切就绪让我们进行第一次对话测试。# 测试工具调用询问天气将调用 get_current_weather.sh 工具 # --role %functions% 是关键它告诉AIChat加载并使用我们链接的函数。 aichat --role %functions% What‘s the weather like in Tokyo? # 测试智能体调用使用‘todo’智能体 aichat --agent todo 帮我买牛奶和鸡蛋添加到购物清单 aichat --agent todo 列出我所有的待办事项如果配置正确AIChat会先思考然后识别出需要调用“获取天气”或“管理待办事项”的函数并在后台执行对应的脚本最后将结果整合成自然语言回复给你。你会看到类似[Function] get_current_weather这样的调用日志。4. 深度实操编写自定义工具与智能体4.1 编写一个Bash工具系统信息收集器内置工具很好但真正的威力在于自定义。假设我们想创建一个工具让AI能快速收集并汇报当前系统的关键信息如负载、内存、磁盘。在./tools/目录下创建新文件system_info.sh#!/usr/bin/env bash set -e # describe Get current system information (load, memory, disk usage). # option --type! The type of info to get: load|memory|disk|all. main() { local info_type$argc_type case $info_type in load) uptime | awk -Fload average: {print $2} $LLM_OUTPUT ;; memory) free -h | grep Mem | awk {print Total: $2, Used: $3, Free: $4} $LLM_OUTPUT ;; disk) df -h / | tail -1 | awk {print Size: $2, Used: $3, Avail: $4, Use%: $5} $LLM_OUTPUT ;; all) { echo System Load uptime echo echo Memory Usage free -h echo echo Disk Usage (Root) df -h / } $LLM_OUTPUT ;; *) echo Error: Invalid type. Choose from: load, memory, disk, all 2 exit 1 ;; esac } eval $(argc --argc-eval $0 $)关键代码解析# describe和# option这是argc的注释标签用于自动生成函数声明。!表示该参数是必需的。argc_typeargc会自动将命令行参数解析为对应的变量。 “$LLM_OUTPUT”这是与llm-functions框架的约定。工具执行的所有输出都应追加到这个环境变量指向的文件中框架会读取这个文件的内容作为函数的返回结果。最后的eval语句是argc脚本的标准结尾用于处理参数解析。启用工具# 将新工具添加到 tools.txt echo system_info.sh tools.txt # 重新构建 argc build测试工具aichat --role %functions% 检查一下我服务器的系统负载和内存使用情况类型选all。AI应该会理解你的请求调用system_info工具并返回格式化的系统信息。4.2 编写一个Python工具简易文本分析器对于更复杂的逻辑Python是更好的选择。我们来创建一个分析文本情绪极简版和关键词的工具。在./tools/目录下创建text_analyzer.pyimport re from collections import Counter def run(text: str, analysis_type: str both): Analyze the given text for sentiment and keywords. Args: text: The text to analyze. analysis_type: What to analyze. One of: sentiment|keywords|both. result_parts [] if analysis_type in [sentiment, both]: # 极简情绪分析通过关键词计数 positive_words [good, great, excellent, happy, love] negative_words [bad, terrible, awful, sad, hate] words text.lower().split() pos_count sum(1 for w in words if w in positive_words) neg_count sum(1 for w in words if w in negative_words) if pos_count neg_count: sentiment 总体上偏积极 elif neg_count pos_count: sentiment 总体上偏消极 else: sentiment 中性或情绪不明显 result_parts.append(f情绪分析: {sentiment} (积极词:{pos_count}, 消极词:{neg_count})) if analysis_type in [keywords, both]: # 提取简单的关键词去除常见停用词 stop_words {the, a, an, and, or, but, in, on, at, to, for, of, with, by} words re.findall(r\b[a-zA-Z]{3,}\b, text.lower()) # 匹配3个字母以上的单词 filtered_words [w for w in words if w not in stop_words] word_freq Counter(filtered_words).most_common(5) # 取前5个 if word_freq: keywords_str , .join([f‘{w}‘({c}) for w, c in word_freq]) result_parts.append(f高频关键词: {keywords_str}) else: result_parts.append(未提取到显著关键词。) # 将结果输出到标准输出框架会捕获并传递给LLM。 # 在llm-functions的Python工具中直接print即可。 print(\n.join(result_parts)) # 注意Python工具不需要特殊的main函数包装框架会直接调用 run 函数。关键点说明函数名必须是run。参数的类型提示如text: str和文档字符串 ... 至关重要框架依赖它们来生成准确的JSON Schema。工具的所有输出通过print函数输出即可框架会自动捕获。启用并测试echo text_analyzer.py tools.txt argc build aichat --role %functions% 分析一下这段文本‘The project is making good progress, but the recent bug is terrible. The team is still happy with the overall direction.‘ 请同时分析情绪和关键词。4.3 构建一个专属智能体个人写作助手智能体Agent比单一工具更强大它结合了定制化提示词Instructions、一组专用工具和可选的参考文档RAG。我们来创建一个帮助写作技术博客的智能体。创建智能体目录结构mkdir -p agents/tech_writer cd agents/tech_writer定义智能体核心配置 (index.yaml)name: TechWriterAssistant description: A specialized assistant for writing and refining technical blog posts. version: 1.0.0 instructions: | 你是一位经验丰富的技术博客编辑和作者。你的任务是帮助用户构思、起草、润色技术博客文章。 你的风格应该清晰、专业、易懂避免不必要的行话。专注于提供实用的建议和具体的修改。 你可以执行以下操作 1. 根据用户提供的主题和大纲生成详细的文章段落。 2. 对用户提供的草稿进行语法检查、风格优化和可读性提升。 3. 为用户提供技术概念的解释建议。 4. 使用可用的工具来获取实时信息或执行代码示例。 在回复时请直接提供修改后的文本或写作建议并简要说明修改理由。 conversation_starters: - 帮我为‘如何理解HTTP/3’这个主题写一个引言。 - 润色这段关于Python装饰器的解释。 - 为我的‘Kubernetes入门’博客列一个提纲。 variables: [] # 本例暂不定义变量 documents: [] # 本例暂不挂载知识文档instructions是智能体的“灵魂”决定了它的行为和口吻。写得越具体智能体的表现就越符合预期。为智能体配置专属工具 (tools.txt)# 在 agents/tech_writer/ 目录下创建 tools.txt # 这个文件列出的工具仅对该智能体可用。 echo -e text_analyzer.py\nweb_search_perplexity.sh tools.txt这样这个写作助手就拥有了文本分析能力和联网搜索能力可以在写作时查找资料或分析文本。可选创建智能体专属工具 你还可以在agents/tech_writer/下创建仅该智能体可用的工具例如一个专门用于格式化Markdown代码块的脚本format_code.sh。创建方式与全局工具完全相同。启用智能体并测试# 回到项目根目录 cd ../.. # 将智能体名称添加到全局 agents.txt echo tech_writer agents.txt # 重新构建 argc build # 测试智能体 aichat --agent tech_writer “帮我润色下面这段话让它更流畅专业‘Docker is good for making your app run the same everywhere. It packages things up.‘”观察AI的回复它应该会运用你定义的“技术编辑”角色并可能调用text_analyzer工具来分析原文然后给出修改后的版本和理由。5. 高级配置、问题排查与性能优化5.1 工具配置与环境变量管理许多工具需要API密钥或特定配置例如各种web_search_*.sh工具。最佳实践是通过环境变量管理这些敏感信息。查看工具所需配置# 查看某个工具脚本的开头部分通常会有注释说明需要的环境变量。 head -20 ./tools/web_search_perplexity.sh你可能会看到类似# env PERPLEXITY_API_KEY! Your Perplexity API key的注释。设置环境变量# 临时设置仅当前终端会话有效 export PERPLEXITY_API_KEYyour_api_key_here export TAVILY_API_KEYyour_tavily_key # 永久设置将上述 export 行添加到你的 ~/.bashrc 或 ~/.zshrc 文件末尾。 echo ‘export PERPLEXITY_API_KEY“your_key”‘ ~/.zshrc source ~/.zshrc使用.env文件推荐用于项目 在llm-functions项目根目录创建.env文件PERPLEXITY_API_KEYyour_key_here TAVILY_API_KEYyour_key_here OPENWEATHER_API_KEYyour_key_here然后在运行aichat前使用source .env加载变量。你甚至可以创建一个启动脚本# start_aichat.sh #!/bin/bash cd /path/to/llm-functions source .env aichat --role %functions% “$”赋予执行权限chmod x start_aichat.sh之后用./start_aichat.sh “你的问题”来运行。5.2 常见问题与解决方案速查表以下是我在长期使用中遇到的一些典型问题及解决方法问题现象可能原因解决方案运行argc build失败提示“command not found: argc”argc未安装或不在PATH中1. 确认已按3.1节安装。2. 尝试which argc查看路径或将安装目录如~/.cargo/bin添加到PATH。argc check报告工具“Missing dependencies”工具依赖的运行时如Node.js、Python或第三方库未安装1. 根据错误提示安装对应运行时node -v,python3 --version。2. 对于Python工具可能需要pip install特定库。检查工具脚本的import语句。aichat提示“No function call found”或直接回答而不调用工具1. 函数未成功链接到AIChat。2. AIChat模型不支持或不擅长Function Calling。3. 用户提问方式不够明确。1. 运行 aichat --info工具被调用但返回错误或空结果1. 工具脚本本身有bug。2. 缺少必要的环境变量如API密钥。3. 参数传递错误。1. 直接在终端手动测试工具./bin/your_tool --arg1 value。2. 运行argc check检查环境变量警告。3. 查看AIChat的详细日志aichat --log-level debug …观察LLM生成的调用参数是否正确。智能体Agent行为不符合预期instructions提示词写得不够清晰或具体。迭代修改agents/your_agent/index.yaml中的instructions字段。使其更详细、更具约束性并明确说明可用的工具和禁止的行为。5.3 性能优化与使用技巧精简工具集tools.txt里列出的工具越多生成的functions.json就越庞大这会增加LLM理解工具列表的负担也可能增加不必要的Token消耗。只激活你当前真正需要的工具并定期清理。编写高质量的工具描述在工具脚本的describe注释和参数描述中使用清晰、无歧义的自然语言。好的描述能极大提升LLM选择正确工具的准确率。例如“获取当前天气”比“天气查询”更好。利用AIChat的会话记忆AIChat支持多轮对话。在一个会话中LLM会记住之前调用过的工具和结果。这对于需要多步骤协作的任务如先搜索再分析再总结非常有用。只需连续对话即可。为复杂任务创建专用智能体如果一个工作流涉及固定的工具组合和特定的提示词不要每次都手动在对话中引导LLM。为其创建一个专用的智能体将提示词和工具固化在index.yaml中使用起来效率更高、效果更稳定。调试工具如果工具执行出错框架通常会将错误信息返回给LLM。但更直接的调试方法是脱离AIChat直接在终端运行工具。所有工具的可执行文件都在./bin/目录下你可以像运行普通命令行程序一样测试它们例如./bin/get_current_weather.sh --location “北京”。这是定位脚本逻辑错误的最快方式。6. 生态扩展与未来展望llm-functions目前深度集成于AIChat但其设计理念是开放的。通过MCP桥接它具备了融入更广泛生态的潜力。你可以探索以下方向连接更多数据源利用MCP可以连接数据库、Notion、Google Drive等将这些数据源作为“工具”提供给LLM构建强大的个人数据助手。开发图形界面虽然现在是CLI工具但其生成的标准化functions.json可以被任何支持OpenAI Function Calling的前端应用调用。理论上你可以基于此开发一个图形化的AI助手桌面应用。工具共享社区项目结构鼓励分享工具脚本。你可以将写好的、解决通用问题的工具如“发送邮件”、“管理日历事件”提交到社区或者从他人的分享中获取灵感。这个项目的魅力在于它的简洁和直接。它没有试图构建一个庞大复杂的AI Agent框架而是专注于做好“让LLM调用本地代码”这一件事并且做得足够优雅和易扩展。对于开发者而言它降低了为AI赋予“行动力”的门槛对于普通用户它提供了一条清晰路径将AI能力定制化地融入自己的数字生活。从我个人的使用体验来看从构思一个工具到实际让AI调用它往往只需要一杯咖啡的时间这种快速的反馈循环正是持续探索AI应用的最佳动力。