1. 项目概述当AI学会“使用工具”最近在折腾AI应用开发的朋友估计都绕不开一个核心问题如何让大语言模型LLM从“能说会道”的聊天伙伴变成“能动手干活”的智能体这中间的鸿沟就是“工具调用”。你告诉AI“帮我查一下明天的天气”它需要知道去哪里查天气API、怎么查发送请求、以及如何理解返回的数据解析JSON。这个过程就是让AI具备了使用外部工具的能力。ComposioHQ/awesome-codex-skills这个项目正是在这个背景下诞生的一个宝藏资源库。它不是一个可以直接运行的软件而是一个精心整理的、关于如何为AI特别是OpenAI的Codex模型及其后继者构建和使用“技能”的精选列表。你可以把它理解为一个“AI工具使用指南”的导航站或者一个“技能配方”大全。它的核心价值在于将散落在各处的、关于如何让AI连接数据库、调用API、操作软件、处理文件等具体能力的实现方案、开源代码和最佳实践进行了系统的归类与梳理。对于开发者而言这个项目直接切中了当前AI工程化的痛点。我们不再满足于让GPT生成一段文本而是希望它能作为一个智能工作流的核心自动完成一系列任务。比如一个客服AI不仅能回答问题还能根据对话内容在CRM系统里创建工单、在日历中预约会议、并发送确认邮件。awesome-codex-skills提供的正是构建这些复杂能力所需的技术组件和思路。2. 核心思路技能即插即用的模块化设计为什么我们需要一个专门的“技能”列表这背后反映的是一种工程思维的转变。早期我们与AI交互是“问答式”的输入问题获取文本回答。而现在我们进入“代理式”交互我们赋予AI一个目标它自己决定需要调用哪些工具、按什么顺序调用并最终达成目标。这里的“工具”或“技能”就是AI可以调用的、具有明确输入输出规范的函数。2.1 技能的定义与标准化一个合格的“技能”远不止是一个API封装。在awesome-codex-skills所倡导的范式里它通常包含以下几个层次自然语言描述用人类能理解的话说明这个技能是干什么的。例如“这个技能可以获取指定城市的当前天气情况。” 这是给AI看的用于让AI理解在什么场景下应该选择这个技能。结构化模式严格定义技能的输入参数和输出格式。通常采用JSON Schema来描述。例如输入参数city是字符串类型、必填输出是一个包含temperature、condition等字段的对象。这是AI和代码之间沟通的“合同”。执行代码具体的实现函数。当AI决定调用该技能时这段代码会被执行。它可能是一个简单的HTTP请求也可能是一段复杂的本地计算逻辑。认证与安全如何处理API密钥、用户令牌等敏感信息。是硬编码、环境变量还是通过更安全的动态鉴权流程这是技能能否投入实际使用的关键。awesome-codex-skills项目收集的许多优秀实践都体现了对这种标准化模式的追求。例如一个项目可能提供了一种将任意OpenAPI规范Swagger文档自动转换为上述格式技能套件的方法这极大地降低了接入新工具的成本。2.2 技能编排与AI的“思考”过程有了一个个独立的技能如何让AI使用它们这就涉及到“编排”。当前主流的方式是基于LLM的“规划-执行”循环任务规划用户提出一个复杂请求如“总结我上周GitHub仓库中最活跃的三个issue并给提交者发封感谢邮件”。AI首先需要拆解任务它需要调用“获取仓库issue列表”技能然后需要“分析issue活跃度”的逻辑可能涉及另一个技能或内部处理最后需要“发送邮件”技能。技能选择AI根据当前任务上下文和可用技能的自然语言描述选择最合适的一个或一组技能。awesome-codex-skills中列举的许多框架如LangChain Tools、Microsoft AutoGen的AssistantAgent都内置了这种匹配和选择机制。参数填充AI根据对话历史和信息自动填充所选技能所需的参数。例如从上下文中提取出“上周”、“我的GitHub仓库”等具体信息转化为start_date、repo_name等参数。执行与验证调用技能代码获取结果。AI需要解析结果判断任务是否完成或是否需要进一步调用其他技能例如获取issue列表后发现需要再调用用户API来获取提交者邮箱。这个列表里推荐的很多工具和库其核心价值就是简化了从“定义技能”到“被AI调用”的整个流水线。3. 技能生态盘点从基础工具到复杂集成awesome-codex-skills作为一个精选列表其内容覆盖了技能生态的各个方面。我们可以将其分为几个大类来理解这也是开发者入手时可以遵循的路径。3.1 核心框架与SDK这是构建AI智能体的“基础设施”。它们提供了定义、注册、调用技能的标准方法并通常与主流LLM API如OpenAI Anthropic深度集成。LangChain / LangGraph目前最流行的生态系统之一。其Tool抽象是技能概念的典型实现。通过装饰器tool可以轻松将Python函数转化为AI可调用的工具并自动生成描述和模式。LangGraph更进一步允许你以图的形式定义多个工具/智能体之间复杂的调用流程。实操心得LangChain的Tool接口非常灵活但初期学习曲线稍陡。建议从定义一个最简单的工具开始比如一个计算器函数感受AI如何调用它。关键点在于函数文档字符串docstring的质量AI很大程度上依赖它来理解工具用途。LlamaIndex最初专注于数据索引与检索现在也具备了强大的工具调用能力。其QueryEngineTool可以将一个完整的检索查询引擎包装成一个工具非常适合构建基于私有知识的问答智能体。Microsoft AutoGen微软推出的多智能体框架其AssistantAgent可以配置工具列表。特色在于支持多智能体协作不同的智能体可以专精于不同的工具集通过对话共同完成复杂任务。OpenAI Assistants API Function Calling这是官方的方案。通过functions参数在聊天补全调用中定义工具模型会返回一个包含需要调用函数名称和参数的响应。这是最“原生”的支持但需要开发者自己处理函数调用和结果回传的循环逻辑。注意框架选择上没有绝对的好坏。LangChain生态丰富但庞大OpenAI Function Calling 直接但需自行编排AutoGen强于多智能体场景。建议根据项目复杂度和个人偏好选择。对于新手从OpenAI Function Calling入手最能理解底层机制对于快速构建复杂应用LangChain更高效。3.2 预构建技能集与工具集成这是“轮子”层。很多开源项目将常见的API和服务封装成了即插即用的技能直接节省了开发时间。composio、toolkit这类库的目标是成为“工具的App Store”。它们集成了数百种常见SaaS工具如GitHub, Slack, Notion, Salesforce, Google Workspace等的API并提供统一的接口供AI调用。awesome-codex-skills列表中很可能就收录了此类项目。浏览器自动化工具对于没有开放API的网站可以通过浏览器自动化来模拟人类操作。例如将playwright或selenium脚本封装成技能让AI可以“操作浏览器”进行数据抓取或表单填写。这类技能通常更脆弱网站结构一变就可能失效但能力边界极广。代码执行与计算工具给AI一个安全的沙箱环境来执行代码如Python使其能够进行复杂的数学计算、数据分析或生成可运行的程序片段。安全是这里的首要考虑必须严格限制网络、文件系统访问权限。硬件与本地操作一些实验性项目将技能拓展到了物理世界例如控制智能家居、操作机器人臂等。这通常需要与MQTT、ROS等物联网或机器人中间件结合。3.3 开发、调试与评估工具工欲善其事必先利其器。这类资源帮助开发者更好地创建和管理技能。技能描述生成器自动分析函数代码和注释生成高质量的自然语言描述和JSON Schema。这对于维护大型技能库至关重要。交互式调试平台有些工具提供可视化界面你可以模拟用户提问逐步观察AI的思考过程ReAct模式、工具选择、参数生成和结果解析极大提升调试效率。技能评估基准如何判断你的智能体是否正确地使用了工具需要一套测试用例。例如给定任务“查询北京天气”评估AI是否选择了正确的天气工具参数city是否填为“Beijing”。这类基准测试集对于迭代优化智能体性能非常有帮助。4. 动手实践从零构建一个天气查询智能体理论说得再多不如亲手实现一个。下面我们以最经典的“天气查询”为例使用OpenAI Function Calling和Python构建一个完整的、具备工具调用能力的AI智能体。我们将遵循awesome-codex-skills中推崇的清晰、模块化的风格。4.1 环境准备与依赖安装首先确保你的Python环境在3.8以上。我们主要需要openai库。通过pip安装pip install openai你需要一个OpenAI的API密钥。如果你还没有请前往OpenAI平台创建。出于安全考虑永远不要将API密钥硬编码在代码中。推荐使用环境变量管理# 在终端中设置临时 export OPENAI_API_KEYyour-api-key-here或者在代码中使用python-dotenv加载.env文件。4.2 定义天气查询技能技能的本质是一个函数以及对其的描述。我们先实现一个真实的天气查询函数。这里我们使用一个免费的天气API例如wttr.in作为示例它简单且无需注册。import requests import json def get_current_weather(location: str, unit: str celsius) - str: 获取指定城市的当前天气情况。 Args: location (str): 城市名称例如“北京”或“London,UK”。 unit (str): 温度单位可选“celsius”或“fahrenheit”。默认为“celsius”。 Returns: str: 格式化的天气信息字符串。 try: # 使用 wttr.in API它返回格式化的文本我们这里简单处理 # 实际项目中建议使用返回JSON的API如OpenWeatherMap url fhttps://wttr.in/{location}?formatj1 response requests.get(url) response.raise_for_status() # 检查请求是否成功 data response.json() # 解析返回的JSON数据 current_condition data[current_condition][0] temp_c current_condition[temp_C] temp_f current_condition[temp_F] weather_desc current_condition[weatherDesc][0][value] humidity current_condition[humidity] # 根据单位选择温度 temp temp_c if unit celsius else temp_f unit_symbol °C if unit celsius else °F result f{location}的当前天气{weather_desc}。温度{temp}{unit_symbol}湿度{humidity}%。 return result except requests.exceptions.RequestException as e: return f无法获取{location}的天气信息{e} except (KeyError, json.JSONDecodeError) as e: return f解析天气数据时出错{e} # 测试函数 print(get_current_weather(Beijing))接下来我们需要按照OpenAI Function Calling的格式为这个函数创建一个“工具定义”。这个定义是一个JSON对象告诉AI这个工具叫什么、干什么、需要什么参数。# 定义工具技能的元数据 weather_tool { type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气情况。, parameters: { type: object, properties: { location: { type: string, description: 城市或地区名称例如‘上海’或‘San Francisco, CA’。, }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位华氏度或摄氏度。, } }, required: [location], }, } }关键点解析name必须与实际的函数名严格一致。description至关重要AI主要靠它来判断是否调用此工具。描述应清晰、简洁。parameters使用JSON Schema定义。enum可以限制参数的可选值提高准确性。required数组指明哪些参数是必填的。4.3 实现智能体对话循环现在我们将函数定义交给AI并处理它的响应。核心逻辑是一个循环用户输入 - AI判断是否需要调用工具 - 若需要则执行对应函数 - 将结果返回给AI - AI生成最终回复。import os from openai import OpenAI # 初始化OpenAI客户端它会自动从环境变量 OPENAI_API_KEY 读取密钥 client OpenAI() # 可用工具列表 tools [weather_tool] # 工具名到实际函数的映射 available_functions { get_current_weather: get_current_weather, } def run_conversation(user_input: str, messages_history: list None): 运行一轮对话处理可能的工具调用。 if messages_history is None: messages_history [] # 1. 将用户输入加入历史 messages_history.append({role: user, content: user_input}) # 2. 发送请求给AI并告知它可用的工具 response client.chat.completions.create( modelgpt-3.5-turbo-1106, # 或 gpt-4-turbo-preview它们都支持function calling messagesmessages_history, toolstools, tool_choiceauto, # 让模型自行决定是否调用工具 ) response_message response.choices[0].message messages_history.append(response_message) # 将AI的回复也加入历史 # 3. 检查AI是否想要调用工具 tool_calls response_message.tool_calls if tool_calls: # 4. 并行执行所有AI想要调用的工具 for tool_call in tool_calls: function_name tool_call.function.name function_to_call available_functions[function_name] function_args json.loads(tool_call.function.arguments) # 解析AI生成的参数 # 执行函数 print(f[系统] 正在调用函数: {function_name} 参数: {function_args}) function_response function_to_call(**function_args) # 5. 将工具执行结果作为一条新消息追加给AI messages_history.append({ tool_call_id: tool_call.id, role: tool, name: function_name, content: function_response, # 将结果字符串传回 }) # 6. 再次请求AI让它结合工具结果生成最终回复 second_response client.chat.completions.create( modelgpt-3.5-turbo-1106, messagesmessages_history, ) return second_response.choices[0].message.content else: # AI没有调用工具直接返回其回复 return response_message.content # 示例对话 if __name__ __main__: history [] while True: user_input input(\n你: ) if user_input.lower() in [退出, exit, quit]: break ai_response run_conversation(user_input, history) print(fAI: {ai_response})运行流程示例你: 今天北京天气怎么样 [系统] 正在调用函数: get_current_weather 参数: {location: 北京, unit: celsius} AI: 北京的当前天气晴朗。温度22°C湿度35%。你: 那纽约呢用华氏度告诉我。 [系统] 正在调用函数: get_current_weather 参数: {location: New York, unit: fahrenheit} AI: 纽约的当前天气局部多云。温度68°F湿度60%。4.4 关键技巧与避坑指南在实际开发中你会遇到比示例更复杂的情况。以下是一些从经验中总结的要点工具描述的“咒语”工程description和参数description的质量直接决定AI调用的准确性。要像给一个实习生写工作说明书一样清晰。例如如果参数location可能接受“城市名”或“城市名,国家代码”就在描述里写清楚。多用例子。错误处理与鲁棒性工具函数内部必须有完善的错误处理如try-catch。网络请求可能超时API可能返回意外格式。工具函数应返回一个字符串格式的错误信息AI通常能理解并告知用户“暂时无法获取信息”而不是让整个智能体崩溃。上下文管理我们的示例使用了简单的列表来存储对话历史。在复杂应用中你需要管理更长的上下文可能涉及向量数据库并决定哪些历史消息需要保留给AI作为参考。工具调用的请求和响应也会占用token需注意成本。处理多个工具调用AI有时会计划同时调用多个工具如tool_calls数组。我们的代码展示了如何并行处理它们。确保你的函数是线程安全的或者按顺序执行。强制与引导工具使用tool_choice参数可以设置为none禁止调用、auto默认由AI决定或一个具体的工具定义强制调用。在特定工作流中你可以引导AI必须使用某个工具。5. 进阶挑战与模式探索当你掌握了单个工具调用后awesome-codex-skills列表里更吸引人的是那些解决复杂问题的模式。5.1 技能链与工作流很多任务需要按顺序调用多个技能。例如“查天气如果下雨就提醒我带伞”。这需要AI具备初步的推理和规划能力。实现方式有两种AI自主规划提供所有相关工具在对话循环中依靠AI自己的逻辑来依次调用。这更灵活但对AI的推理能力要求高可能不稳定。预定义工作流开发者使用像LangGraph这样的框架显式地定义工具A和工具B的调用顺序和条件分支。这更稳定、可控适合业务流程固定的场景。5.2 动态技能发现与加载在大型应用中技能可能有上百个不可能每次都全部发送给AItoken有限。需要实现“技能路由”机制先根据用户问题用一个轻量级模型或规则筛选出最相关的几个技能再交给主AI模型使用。这类似于插件系统的按需加载。5.3 技能的可解释性与评估如何知道AI调用工具的决定是正确的除了看最终结果还需要中间过程的透明度。一些框架提供了“思维链”输出让你看到AI选择工具时的理由。建立评估体系也至关重要准备一批测试问题验证智能体是否选择了正确的工具、填充了正确的参数。5.4 安全与权限控制这是企业级应用无法回避的问题。一个面向内部员工的智能体不同部门的员工能调用的技能应该不同如HR能访问人事系统财务不能。需要在技能调用层添加权限校验。此外工具函数如果执行写操作如发送邮件、创建订单必须加入二次确认机制例如让AI生成操作摘要经用户明确确认后再执行。6. 从项目列表到个人知识体系ComposioHQ/awesome-codex-skills的价值不仅仅在于它列出了什么更在于它揭示了一个正在快速演进的技术领域全景图。作为开发者我的建议是从模仿开始不要试图一口气吃透整个列表。选中一个最贴近你需求的小工具或框架比如就用上面天气查询的例子把它跑通理解数据流的每一个环节。深入一个框架在LangChain、LlamaIndex、AutoGen等主流框架中选一个深入学习其工具调用的设计哲学和API。每个框架背后都代表了一种构建智能体的思路。动手封装自己的技能将你工作中最常重复的、有明确API的操作封装成一个技能。例如“查询数据库销售数据”、“生成周报图表”、“向Slack频道发送通知”。这是最能产生直接价值的一步。关注设计模式 beyond具体的代码去观察列表里不同项目是如何解决编排、错误处理、状态管理这些共性问题的。这些模式比任何单一工具都更有生命力。这个领域的变化日新月异新的工具和框架不断涌现。保持实践保持好奇最重要的不是记住所有工具的名字而是建立起一套让AI安全、可靠、高效地为你工作的思维模型和工程方法。awesome-codex-skills这样的资源就是你探索过程中的一张优质地图但真正的旅程还需要你用自己的代码一步步走出来。