基于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的核心贡献在于，它标准化并简化了“函数”的定义和调用流程。它没有发明新轮子，而是巧妙地利用了现有生态：

1. 语言无界：你可以用任何你熟悉的脚本语言（Bash/JS/Py）编写工具逻辑。
2. 声明即生成：通过规范的代码注释（如JSDoc、Python docstring），工具的描述、参数等信息会被自动提取并生成标准的OpenAI Function Calling格式的JSON声明。
3. 统一调度：通过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（模型上下文协议）的关联

项目还提到了MCP（Model 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/macOS，Windows可通过WSL）已准备好以下依赖。这是项目运行的基石。

1. 安装argc：这是项目的命令运行框架。推荐使用包管理器安装，最方便。

   # 对于 macOS (使用 Homebrew) brew install argc # 对于 Linux (使用 cargo，需先安装Rust) cargo install argc # 或者，直接从GitHub发布页下载预编译的二进制文件，放入系统PATH中。

   安装后，在终端输入argc --version验证是否成功。

2. 安装jq：一个强大的命令行JSON处理器，项目内部用于解析和生成JSON。

   # macOS brew install jq # Ubuntu/Debian sudo apt-get install jq # CentOS/RHEL sudo yum install jq

3. 安装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 Calling（GPT-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能快速收集并汇报当前系统的关键信息（如负载、内存、磁盘）。

1. 在./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 -F'load 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" "$@")"

2. 关键代码解析：

   • # @describe和# @option：这是argc的注释标签，用于自动生成函数声明。!表示该参数是必需的。
   • argc_type：argc会自动将命令行参数解析为对应的变量。
   • >> “$LLM_OUTPUT”：这是与llm-functions框架的约定。工具执行的所有输出都应追加到这个环境变量指向的文件中，框架会读取这个文件的内容作为函数的返回结果。
   • 最后的eval语句是argc脚本的标准结尾，用于处理参数解析。

3. 启用工具：

   # 将新工具添加到 tools.txt echo "system_info.sh" >> tools.txt # 重新构建 argc build

4. 测试工具：

   aichat --role %functions% "检查一下我服务器的系统负载和内存使用情况，类型选all。"

   AI应该会理解你的请求，调用system_info工具并返回格式化的系统信息。

4.2 编写一个Python工具：简易文本分析器

对于更复杂的逻辑，Python是更好的选择。我们来创建一个分析文本情绪（极简版）和关键词的工具。

1. 在./tools/目录下创建text_analyzer.py：

   import 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` 函数。

2. 关键点说明：

   • 函数名必须是run。
   • 参数的类型提示（如text: str）和文档字符串（""" ... """）至关重要，框架依赖它们来生成准确的JSON Schema。
   • 工具的所有输出通过print函数输出即可，框架会自动捕获。

3. 启用并测试：

   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）。我们来创建一个帮助写作技术博客的智能体。

1. 创建智能体目录结构：

   mkdir -p agents/tech_writer cd agents/tech_writer

2. 定义智能体核心配置 (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是智能体的“灵魂”，决定了它的行为和口吻。写得越具体，智能体的表现就越符合预期。

3. 为智能体配置专属工具 (tools.txt)：

   # 在 agents/tech_writer/ 目录下创建 tools.txt # 这个文件列出的工具，仅对该智能体可用。 echo -e "text_analyzer.py\nweb_search_perplexity.sh" > tools.txt

   这样，这个写作助手就拥有了文本分析能力和联网搜索能力，可以在写作时查找资料或分析文本。

4. （可选）创建智能体专属工具： 你还可以在agents/tech_writer/下创建仅该智能体可用的工具，例如一个专门用于格式化Markdown代码块的脚本format_code.sh。创建方式与全局工具完全相同。

5. 启用智能体并测试：

   # 回到项目根目录 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工具。最佳实践是通过环境变量管理这些敏感信息。

1. 查看工具所需配置：

   # 查看某个工具脚本的开头部分，通常会有注释说明需要的环境变量。 head -20 ./tools/web_search_perplexity.sh

   你可能会看到类似# @env PERPLEXITY_API_KEY! Your Perplexity API key的注释。

2. 设置环境变量：

   # 临时设置（仅当前终端会话有效） export PERPLEXITY_API_KEY="your_api_key_here" export TAVILY_API_KEY="your_tavily_key" # 永久设置：将上述 export 行添加到你的 ~/.bashrc 或 ~/.zshrc 文件末尾。 echo ‘export PERPLEXITY_API_KEY=“your_key”‘ >> ~/.zshrc source ~/.zshrc

3. 使用.env文件（推荐用于项目）： 在llm-functions项目根目录创建.env文件：

   PERPLEXITY_API_KEY=your_key_here TAVILY_API_KEY=your_key_here OPENWEATHER_API_KEY=your_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 常见问题与解决方案速查表

以下是我在长期使用中遇到的一些典型问题及解决方法：

5.3 性能优化与使用技巧

1. 精简工具集：tools.txt里列出的工具越多，生成的functions.json就越庞大，这会增加LLM理解工具列表的负担，也可能增加不必要的Token消耗。只激活你当前真正需要的工具，并定期清理。

2. 编写高质量的工具描述：在工具脚本的@describe注释和参数描述中，使用清晰、无歧义的自然语言。好的描述能极大提升LLM选择正确工具的准确率。例如，“获取当前天气”比“天气查询”更好。

3. 利用AIChat的会话记忆：AIChat支持多轮对话。在一个会话中，LLM会记住之前调用过的工具和结果。这对于需要多步骤协作的任务（如先搜索，再分析，再总结）非常有用。只需连续对话即可。

4. 为复杂任务创建专用智能体：如果一个工作流涉及固定的工具组合和特定的提示词，不要每次都手动在对话中引导LLM。为其创建一个专用的智能体，将提示词和工具固化在index.yaml中，使用起来效率更高、效果更稳定。

5. 调试工具：如果工具执行出错，框架通常会将错误信息返回给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应用的最佳动力。