1. 项目概述一个面向开发者的智能体技能库最近在折腾AI智能体Agent开发发现一个挺有意思的开源项目叫agentskill-sh/ags。简单来说它是一个专门为AI智能体设计的“技能库”或“工具箱”。如果你正在用类似LangChain、AutoGen或者直接调用大模型API来构建能执行复杂任务的智能体那么这个项目很可能就是你一直在找的“瑞士军刀”。想象一下你构建了一个智能体它能理解你的指令但让它去执行一个具体操作时比如“帮我查一下明天的天气”、“把这份文档总结成要点发到我的邮箱”或者“分析这个GitHub仓库最近一周的提交记录”你会发现核心的LLM大语言模型本身并不具备这些能力。它需要调用外部的工具Tools或技能Skills。ags项目的目标就是预先封装好一大批高质量、开箱即用的技能让开发者能像搭积木一样快速赋予智能体各种实际能力而无需从零开始写每一个API的调用和数据处理逻辑。这个项目托管在GitHub上由agentskill-sh组织维护。从名字就能看出它的定位ag代表 Agent智能体s代表 Skill技能组合起来就是“智能体技能”。它不是一个完整的智能体框架而是一个专注于“技能”层面的基础设施。这种设计哲学我很欣赏——做好一件事并把它做到极致。在智能体生态中框架负责流程编排和推理决策而ags则负责提供丰富、可靠的动作执行单元。2. 核心设计思路标准化、模块化与可组合性2.1 为什么需要专门的技能库在深入代码之前我们先聊聊为什么“技能”值得被单独抽离成一个项目。早期做智能体项目时我习惯为每个任务写一个特定的工具函数。比如一个查天气的函数一个发邮件的函数。很快问题就来了函数签名五花八门错误处理各自为政文档也散落在各处。当我想复用某个功能到新项目时拷贝代码后还得适配半天。更麻烦的是不同框架如LangChain和AutoGen对工具的定义格式还不一样导致代码无法直接迁移。ags的核心理念就是解决这些痛点。它试图定义一套标准化的技能接口。无论这个技能是调用一个Web API、操作一个本地文件还是执行一段计算对外都呈现出一致的模样。这带来的好处是巨大的可复用性一次封装处处使用。今天在LangChain项目里用的“网页搜索”技能明天可以无缝用到另一个基于原始OpenAI API调用的项目中。可发现性一个集中、分类清晰的技能仓库让开发者能快速找到所需功能而不是重复造轮子。可维护性技能的迭代升级、Bug修复在一个地方进行所有使用它的项目都能受益。生态建设标准接口鼓励社区贡献形成丰富的技能生态加速智能体应用开发。2.2 技能Skill的抽象与构成在ags的设计中一个技能Skill通常包含以下几个核心部分技能描述Description用自然语言清晰说明这个技能是做什么的。这部分描述至关重要因为它是大语言模型决定是否以及如何调用该技能的主要依据。描述需要准确、无歧义并包含关键参数信息。输入参数Input Parameters定义技能执行所需的信息。每个参数都有名称、类型字符串、数字、布尔值等、描述以及是否为必填项。良好的参数设计能引导大模型正确提供所需信息。执行函数Execution Function技能的具体实现逻辑。这里封装了所有的业务代码包括API调用、数据处理、错误处理等。这是技能的“肌肉”。输出格式Output Schema定义技能执行后返回数据的结构。明确的输出格式有助于下游智能体或应用解析和处理结果。ags通过一套装饰器decorator或基类base class体系让开发者能够以声明式的方式定义技能将上述元素有机地组合在一起。开发者只需关注“执行函数”的具体实现框架会自动处理描述生成、参数校验、与大模型框架的适配等工作。2.3 与主流智能体框架的集成一个优秀的技能库不能是孤岛。ags在设计之初就考虑了与主流智能体开发框架的兼容性。根据其文档和代码结构我能看到它提供了到以下框架的适配器或转换工具LangChain可以将ags技能轻松转换为 LangChain 的Tool对象直接用于AgentExecutor。AutoGen支持将技能包装成 AutoGen 代理Agent可用的函数。原始 OpenAI Function Calling / Tools API能生成符合 OpenAI 工具调用格式的 JSON Schema方便在直接使用 OpenAI API 时集成。这种“一次定义多端运行”的能力极大地扩展了ags的适用场景。无论你的技术栈是什么都可以从中获益。3. 技能分类与典型技能解析ags项目按照功能领域对技能进行了分类这有助于开发者快速定位。我们挑几个典型类别和技能深入看看。3.1 网络与搜索类技能这是智能体感知外部世界的“眼睛和耳朵”。网页搜索Web Search封装了对接搜索引擎如DuckDuckGo、Serper等的复杂逻辑。它不仅仅是发送一个搜索请求还涉及处理反爬机制、解析搜索结果摘要、提取关键信息等。在实现上它可能会使用requests或httpx库并配合BeautifulSoup或lxml进行HTML解析。注意直接爬取搜索引擎结果页面风险很高容易被封IP。因此更稳健的实现是使用搜索引擎提供的官方API如果有的话或者使用无头浏览器如Playwright进行更仿真的操作但这会引入更高的复杂性和性能开销。ags的实现通常会给出明确警告并建议用户配置自己的API密钥。网页内容提取Web Content Fetch给定一个URL智能地提取网页中的核心正文内容过滤掉导航栏、广告、侧边栏等噪音。这通常需要用到专门的库如readability或trafilatura。一个高质量的提取技能能显著提升后续总结、分析等任务的效果。RSS订阅读取RSS Feed Reader定期抓取指定博客或新闻源的更新。实现相对直接使用feedparser库即可。关键在于错误处理如网络超时、XML格式错误和增量更新逻辑避免重复处理已读条目。3.2 文件与数据处理类技能智能体操作本地或云端数据的“手”。文件读写File Read/Write支持读取.txt,.md,.pdf,.docx,.csv,.json等多种格式。以读取PDF为例它内部可能集成了PyPDF2或pdfplumber库来处理文本提取对于扫描版PDF则可能调用OCR服务如Tesseract。写入文件时则要处理好目录创建、文件编码、并发写入冲突等问题。数据查询Data Query对结构化数据如CSV、JSON文件或小型SQLite数据库执行简单的查询操作。例如“找出销售额大于10000的所有记录”。这需要技能内部集成一个轻量级的SQL引擎如duckdb内存数据库或Pandas DataFrame操作。格式转换Format Conversion在JSON、YAML、CSV等格式间进行转换。这类技能看似简单但边界情况很多比如CSV中的逗号转义、JSON中的日期时间序列化等需要健壮的异常处理。3.3 通信与协作类技能智能体与其他系统或人交互的“嘴巴”。电子邮件发送Email Sending配置SMTP服务器信息主机、端口、加密方式构建邮件头发件人、收件人、主题支持纯文本和HTML正文并能处理附件。安全是重中之重必须避免将密码等敏感信息硬编码在代码中而是通过环境变量或配置文件传入。日历事件管理Calendar Event Management与Google Calendar、Outlook等日历服务集成实现创建、查询、更新、删除事件。这涉及到OAuth 2.0授权流程是技能中复杂度较高的一类。ags的实现通常会依赖像google-api-python-client这样的官方SDK并提供一个清晰的授权引导流程。即时消息通知Instant Messaging Notification发送消息到Slack、钉钉、企业微信等平台。这类技能的核心是封装各平台不同的Webhook或API调用格式。3.4 计算与工具类技能智能体进行逻辑运算和调用的“大脑延伸”。代码执行Code Execution这是一个需要极度谨慎对待的技能。它允许智能体在沙箱环境中执行一段Python或其他语言的代码。ags的实现必须包含严格的沙箱隔离如使用docker容器或seccomp沙箱限制资源使用CPU、内存、运行时间并禁用危险模块如os,subprocess的某些功能。即使如此在生产环境中开放此技能仍需经过严格的安全评审。数学计算Calculator执行安全的数学表达式求值。应使用ast模块解析表达式确保只包含合法的数学运算符和函数杜绝任何形式的代码注入。可以集成math和numpy如果可用中的函数来增强能力。单位换算Unit Conversion长度、重量、温度、货币等单位的换算。货币换算需要集成实时汇率API并处理好数据更新和缓存。4. 实战集成ags技能到你的智能体项目理论说了这么多我们来点实际的。假设我们要构建一个“个人助理智能体”它能根据我们的指令搜索信息并保存结果。我们将使用ags中的网页搜索和文件写入技能。4.1 环境准备与安装首先创建一个新的Python虚拟环境并安装依赖。ags项目本身可能还在快速迭代建议通过Git直接安装最新开发版或者查看其PyPI页面安装稳定版。# 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows # 从GitHub安装ags (假设方式) pip install githttps://github.com/agentskill-sh/ags.git # 安装可能需要的额外依赖例如用于网页搜索的库 pip install duckduckgo-search beautifulsoup4 httpx4.2 定义与加载技能在ags中技能通常以Python模块的形式组织。我们假设已经有两个现成的技能web_search和write_to_file。# my_assistant.py import asyncio from ags.skills import load_skill, get_skill_registry # 假设ags提供了这样的接口 async def main(): # 1. 加载技能 search_skill await load_skill(ags.contrib.web.search) # 加载网页搜索技能 write_skill await load_skill(ags.contrib.files.write_text) # 加载文件写入技能 # 2. 将技能注册到本地技能库方便管理 registry get_skill_registry() registry.register(search, search_skill) registry.register(save_note, write_skill) # 3. 现在我们有了两个可用的技能对象search_skill 和 write_skill # 它们通常有一个 .description 属性和一个 .execute(**kwargs) 方法。 # 4. 为了给大模型使用我们需要获取技能的“模式”Schema # 这通常是一个符合OpenAI Tools格式的字典列表。 tools_for_llm registry.get_tools_schema() print(可用工具描述) for tool in tools_for_llm: print(f- {tool[function][name]}: {tool[function][description]}) return registry if __name__ __main__: registry asyncio.run(main())4.3 与大语言模型LLM协同工作接下来我们需要将技能描述“喂”给大语言模型并教会模型在需要时调用它们。这里以使用OpenAI API为例。import openai from my_assistant import registry # 导入上一步创建的技能注册表 client openai.OpenAI(api_keyyour-api-key) def run_conversation(user_query: str): # 第一步将技能描述作为“工具”提供给模型 available_tools registry.get_tools_schema() # 初始化对话 messages [ {role: user, content: user_query} ] # 首次调用模型可能会决定调用工具 response client.chat.completions.create( modelgpt-4-turbo-preview, # 或 gpt-3.5-turbo messagesmessages, toolsavailable_tools, tool_choiceauto, # 让模型自行决定是否调用工具 ) response_message response.choices[0].message messages.append(response_message) # 将模型的回复加入对话历史 # 第二步检查模型是否想要调用工具 tool_calls response_message.tool_calls if tool_calls: # 模型要求调用一个或多个工具 for tool_call in tool_calls: function_name tool_call.function.name function_args json.loads(tool_call.function.arguments) print(f模型要求调用工具: {function_name} 参数: {function_args}) # 第三步在我们的环境中执行对应的技能 skill_to_call registry.get_skill(function_name) if skill_to_call: # 执行技能 function_response skill_to_call.execute(**function_args) print(f工具执行结果: {function_response}) # 第四步将工具执行结果返回给模型让它继续推理 messages.append({ role: tool, tool_call_id: tool_call.id, content: str(function_response), # 结果需要是字符串 }) else: print(f警告未找到技能 {function_name}) # 获得工具结果后再次调用模型让它基于结果生成最终回复 second_response client.chat.completions.create( modelgpt-4-turbo-preview, messagesmessages, ) final_message second_response.choices[0].message.content print(f助理的最终回复: {final_message}) return final_message else: # 模型没有调用工具直接回复 print(f助理直接回复: {response_message.content}) return response_message.content # 测试一个需要调用技能的复杂查询 result run_conversation(请搜索一下‘开源大语言模型的最新进展’并将前三项主要发现总结后保存到文件‘llm_news.txt’里。)在这个流程中智能体大模型扮演了“大脑”的角色负责理解指令、规划步骤先搜索再总结最后保存。而ags提供的技能则是“四肢”负责执行具体的、模型自身无法完成的任务。两者通过标准的工具调用接口进行协作。4.4 封装成可复用的智能体我们可以将上述流程封装成一个更通用的智能体类。class ToolUsingAssistant: def __init__(self, llm_client, skill_registry): self.llm llm_client self.registry skill_registry self.conversation_history [] def chat(self, user_input: str): self.conversation_history.append({role: user, content: user_input}) # 获取当前所有可用的工具描述 available_tools self.registry.get_tools_schema() while True: # 调用LLM传入历史对话和工具描述 response self.llm.chat.completions.create( modelgpt-4-turbo-preview, messagesself.conversation_history, toolsavailable_tools, tool_choiceauto, ) msg response.choices[0].message self.conversation_history.append(msg) # 如果模型想调用工具 if msg.tool_calls: for tool_call in msg.tool_calls: # 执行工具调用流程同上 skill_name tool_call.function.name skill_args json.loads(tool_call.function.arguments) skill self.registry.get_skill(skill_name) if skill: tool_result skill.execute(**skill_args) self.conversation_history.append({ role: tool, tool_call_id: tool_call.id, content: str(tool_result), }) else: # 处理技能未找到的情况 self.conversation_history.append({ role: tool, tool_call_id: tool_call.id, content: fError: Skill {skill_name} not found., }) # 工具调用结束后继续循环让LLM基于结果生成回复 continue else: # 模型给出了最终文本回复结束本次交互 final_reply msg.content self.conversation_history.append({role: assistant, content: final_reply}) return final_reply # 使用示例 assistant ToolUsingAssistant(client, registry) answer assistant.chat(明天的北京天气怎么样) print(answer)5. 开发自己的自定义技能ags的强大之处在于它易于扩展。当内置技能无法满足需求时我们可以轻松创建自定义技能。5.1 技能定义模板ags通常提供一个基础类或装饰器来定义技能。下面是一个假设的基于装饰器的定义方式from ags.decorators import skill, parameter from typing import Annotated import requests skill( nameget_weather, description根据城市名称查询实时天气情况。, version1.0.0 ) parameter( namecity, description要查询天气的城市名称例如北京、Shanghai。, typestr, requiredTrue ) parameter( nameunit, description温度单位c 表示摄氏度f 表示华氏度。默认为 c。, typestr, requiredFalse, defaultc ) async def get_weather_skill(city: str, unit: str c) - str: 技能的执行函数。 这里封装了具体的业务逻辑调用一个天气API。 # 1. 参数验证与预处理装饰器可能已处理基础类型这里可做业务验证 if unit not in [c, f]: return 错误单位参数必须是 c 或 f。 # 2. 调用外部API示例需要替换为真实的API和密钥 api_key os.getenv(WEATHER_API_KEY) if not api_key: return 错误未配置天气API密钥。 url fhttps://api.weatherapi.com/v1/current.json?key{api_key}q{city} try: response requests.get(url, timeout10) response.raise_for_status() # 检查HTTP错误 data response.json() # 3. 解析和格式化结果 location data[location][name] temp_c data[current][temp_c] temp_f data[current][temp_f] condition data[current][condition][text] if unit c: temp temp_c unit_str 摄氏度 else: temp temp_f unit_str 华氏度 result f{location}的当前天气{condition}。温度{temp} {unit_str}。 return result except requests.exceptions.Timeout: return 错误请求天气API超时。 except requests.exceptions.RequestException as e: return f错误获取天气数据失败 - {str(e)} except KeyError as e: return f错误解析天气API响应失败缺少字段 {e}。 # 使用这个技能 weather_skill get_weather_skill # 装饰器会将函数包装成一个技能对象 # 或者通过 registry 加载5.2 技能开发最佳实践与避坑指南根据我开发和使用类似工具的经验在创建自定义技能时以下几点至关重要清晰的描述是第一生产力技能的description和每个参数的description必须精准、无歧义。大模型完全依赖这些描述来决定是否以及如何调用技能。避免使用“获取数据”这种模糊描述而要用“根据ISBN号查询图书的详细信息包括书名、作者、出版社和出版日期”。严格的输入验证即使装饰器进行了基础类型检查在技能执行函数内部也要对参数进行业务逻辑层面的验证。例如城市名是否为空、日期格式是否合法、ID是否在有效范围内等。验证失败时应返回明确的错误信息帮助智能体进行后续决策。健壮的错误处理网络请求、文件I/O、第三方API调用都可能失败。技能必须能妥善处理超时、连接错误、权限不足、数据格式异常等情况并返回对人和对AI友好的错误信息而不是抛出未处理的异常导致整个智能体崩溃。敏感信息管理绝对不要将API密钥、密码等硬编码在技能代码中。必须通过环境变量、配置文件或安全的密钥管理服务传入。在技能描述中也要提醒用户需要预先配置这些信息。控制输出长度与格式大模型对上下文长度有限制。技能的输出应尽可能简洁、信息密集。对于可能很长的输出如一篇抓取的文章考虑提供摘要或截断选项。输出格式最好结构化如JSON便于智能体解析和提取关键信息。考虑异步支持许多I/O操作网络、数据库是阻塞的。如果技能库框架支持如ags可能设计为异步优先尽量使用async/await编写技能以提高智能体在并发调用多个技能时的整体效率。编写单元测试为你的技能编写测试模拟各种正常和异常的输入确保其行为符合预期。这对于保证由多个技能组合而成的智能体的稳定性至关重要。6. 项目架构与源码导读要深入理解ags最好能浏览其核心源码。虽然具体文件结构可能变化但一个典型的核心模块划分可能如下ags/ ├── core/ │ ├── skill.py # 技能基类BaseSkill和抽象定义 │ ├── registry.py # 技能注册表负责技能的加载、管理和发现 │ └── decorators.py # 用于定义技能的装饰器如 skill, parameter ├── skills/ # 内置技能包 │ ├── web/ # 网络相关技能 │ │ ├── search.py │ │ └── fetch.py │ ├── files/ # 文件操作技能 │ ├── communication/ # 通信技能 │ └── compute/ # 计算技能 ├── integrations/ # 与外部框架的集成适配器 │ ├── langchain.py # 转换为LangChain Tool │ ├── autogen.py # 转换为AutoGen Function │ └── openai.py # 生成OpenAI Tools Schema ├── utils/ # 通用工具函数 └── config.py # 全局配置阅读core/skill.py和core/decorators.py可以理解技能是如何被抽象和定义的。core/registry.py展示了技能是如何被组织和管理可能支持从本地目录、Python包或远程URL加载技能。integrations/目录下的代码则展示了如何将内部的技能对象“翻译”成不同框架能理解的格式这是ags实现兼容性的关键。7. 常见问题与排查技巧在实际集成和使用ags的过程中你可能会遇到以下典型问题问题现象可能原因排查步骤与解决方案导入ags模块失败提示模块不存在1.ags未正确安装。2. Python路径问题。3. 项目仍处于早期开发安装方式有变。1. 使用 pip list技能执行时报错如API连接失败1. 技能依赖的第三方服务不可用或网络不通。2. 未正确配置API密钥等环境变量。3. 技能代码有Bug。1. 单独写一个脚本测试技能的核心API调用是否正常。2. 检查环境变量是否在当前Shell中已设置并生效 (print(os.getenv(“XXX”)))。3. 查看技能的源码看是否有明显的逻辑错误或版本不兼容。大模型不调用我期望的技能1. 技能描述不够清晰模型无法理解其用途。2. 用户指令模糊模型无法确定是否需要调用工具。3. 提供的工具列表太长模型“看花了眼”。1.优化技能描述确保描述精准概括功能并包含关键参数示例。例如“查询天气”改为“根据城市名称查询该城市当前的温度、天气状况和湿度”。2.优化用户指令在系统提示词System Prompt中明确告知智能体“你可以使用以下工具来帮助你完成任务”并鼓励它在需要时主动调用。3.精简工具集只提供与当前任务最相关的技能给模型。动态管理技能注册表。技能被调用了但参数不对1. 模型误解了用户意图输出了错误的参数。2. 参数描述不清导致模型填充了错误的值。3. 模型幻觉Hallucination。1. 在技能执行函数入口处增加严格的参数校验和格式化逻辑对于错误参数返回明确提示让模型有机会纠正。2. 细化参数描述规定格式。例如date参数描述写为“日期格式必须为YYYY-MM-DD例如2023-10-27”。3. 使用更强大的模型如GPT-4通常能减少幻觉。在系统提示词中强调“如果你不确定请向我询问澄清”。多个技能组合时智能体陷入循环或逻辑混乱1. 任务规划过于复杂模型“迷失”了。2. 上一个技能的输出格式不利于下一个技能解析。1.分步引导对于复杂任务不要一次性给出所有指令。可以设计成多轮对话由用户或一个顶层协调器分步骤下达子任务。2.标准化输出尽量让技能输出结构化的数据如JSON并在描述中说明输出格式便于后续技能或模型提取信息。可以在系统提示词中要求模型“请以清晰的步骤思考并逐步调用工具”。我个人在实际操作中的体会是ags这类技能库的价值在智能体开发的中后期会爆发式体现。初期做原型验证时可能随手写几个工具函数更快。但当智能体功能越来越复杂技能数量超过10个并且需要在不同项目间复用时一个标准化、中心化的技能管理方案就变得不可或缺。它强迫你思考接口设计、错误处理和文档这些看似额外的工作最终会换来整个系统可维护性和可靠性的巨大提升。开始可能会觉得有点束缚但习惯之后你会发现开发效率和质量都上了一个台阶。