最近在尝试将大模型应用到实际业务中时很多开发者无论是刚入门的新手还是有一定经验的程序员都卡在了“最后一公里”——如何让大模型不只是聊天而是能真正执行任务、调用工具、处理复杂流程这正是Agent Skills智能体技能要解决的核心问题。网上资料虽多但往往零散要么是理论空谈要么是代码片段不成体系导致从“知道”到“做到”之间鸿沟巨大。本文旨在为你提供一份从零到一的Agent Skills 实战指南。我们将绕过晦涩的理论直接聚焦于如何设计、实现并部署一个具备实用技能的智能体Agent。无论你是想为自己的项目添加AI能力的学生还是需要在企业级应用中集成大模型的工程师都能从本文中找到可复用的代码、清晰的配置和避坑指南。我们将涵盖技能的定义、与工具Tools的关键区别、主流的实现框架并最终通过一个完整的“天气查询新闻摘要”复合技能案例带你走完全流程。1. 背景与核心概念什么是 Agent Skills在深入实战之前我们必须厘清几个容易混淆的核心概念。这有助于我们理解 Agent Skills 在整个智能体生态中的位置。1.1 智能体Agent是什么你可以将智能体理解为一个“会思考的机器人”。它接收用户的指令自然语言通过大模型如 GPT-4、Claude、GLM等进行理解、规划和推理然后决定采取哪些行动来完成任务。这些行动可能包括调用一个函数、查询数据库、发送HTTP请求等。1.2 技能Skills与工具Tools的区别这是最容易混淆的一点也是本文的重点。根据最新的社区讨论和实践两者的区别逐渐清晰工具Tools是原子操作是智能体可以调用的最小功能单元。一个工具通常对应一个具体的函数或API调用职责单一。例如get_current_weather(location: str)获取指定城市的天气。search_web(query: str)执行网络搜索。calculate(expression: str)计算数学表达式。技能Skills是能力的集合或任务的解决方案。一个技能通常由多个工具按照一定的逻辑可能包括条件判断、循环、顺序执行组合而成用于解决一个更复杂的、面向用户的目标。例如“出行规划”技能这可能依次调用search_flights查航班、get_weather查目的地天气、book_hotel订酒店等多个工具并根据天气情况调整酒店推荐。“周报生成”技能这可能调用query_jira_tickets查Jira任务、fetch_git_commits获取Git提交、summarize_text总结文本等工具最后合成一份报告。简单来说工具是“锤子”和“螺丝刀”技能是“组装一台电脑”的完整流程和知识。智能体通过组合不同的技能进而调用其内部的工具来应对复杂的用户请求。1.3 为什么需要专门的 Skills 框架当任务变得复杂时单纯让大模型直接调用一堆零散的工具效率和可靠性会下降。Skills框架提供了以下关键价值抽象与封装将复杂的多步流程封装成一个统一的接口对智能体呈现为一个更高级的“能力”。复用与共享封装好的技能可以像乐高积木一样在不同的智能体间复用甚至可以在社区共享。可控与可靠技能内部可以定义更严格的错误处理、输入验证和业务流程比完全依赖大模型自由发挥更可控。降低提示词复杂度无需在每次请求时都向大模型详细解释整个工作流程只需告诉它“使用XX技能”。1.4 相关概念MCPModel Context ProtocolMCP 是一种新兴的协议旨在标准化大模型与外部工具/数据源之间的连接方式。你可以把它想象成智能体的“USB标准”。一个遵循 MCP 的服务可以将其能力工具或数据源以标准格式暴露给任何兼容 MCP 的客户端如 Claude Desktop、某些 Agent 框架。Skills 可以利用 MCP 来接入标准化的工具但技能本身是更高层次的业务逻辑封装。2. 环境准备与版本说明我们将使用LangChain这一流行的 AI 应用开发框架来构建我们的 Agent Skills。LangChain 提供了丰富的组件来编排工具和构建智能体。2.1 基础环境操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04)。本文示例在 macOS/Linux 环境下编写Windows 用户请注意路径差异。Python 版本 3.8。推荐使用 3.9 或 3.10 以获得最佳兼容性。包管理工具pip。2.2 核心依赖库我们将创建一个新的虚拟环境并安装必要依赖。这是避免版本冲突的最佳实践。# 1. 创建并激活虚拟环境 (可选但推荐) python -m venv agent_skills_env source agent_skills_env/bin/activate # Windows: agent_skills_env\Scripts\activate # 2. 安装核心库 pip install langchain langchain-openai # 3. 安装用于示例的额外工具库 pip install requests # 用于调用天气、新闻API pip install python-dotenv # 用于管理环境变量如API密钥2.3 获取 API 密钥我们的示例需要调用大模型和外部 API。OpenAI API Key访问 OpenAI 平台注册并获取。我们将使用 GPT-3.5-turbo 作为推理模型性价比高。公开 API我们将使用免费的天气和新闻 API无需密钥。2.4 项目结构在开始编码前先规划好项目目录这有助于管理复杂的技能。agent_skills_project/ ├── .env # 存储敏感信息如API KEY ├── skills/ # 技能包目录 │ ├── __init__.py │ ├── weather_skill.py # 天气查询技能 │ └── news_skill.py # 新闻摘要技能 ├── tools/ # 基础工具目录 │ ├── __init__.py │ └── custom_tools.py # 自定义工具定义 ├── agent_builder.py # 智能体组装逻辑 ├── main.py # 主程序入口 └── requirements.txt # 依赖列表创建基础文件mkdir -p agent_skills_project/{skills,tools} cd agent_skills_project touch .env .gitignore skills/__init__.py skills/weather_skill.py skills/news_skill.py tools/__init__.py tools/custom_tools.py agent_builder.py main.py requirements.txt在.gitignore中添加.env __pycache__/ *.pyc agent_skills_env/在.env文件中添加你的 OpenAI API KeyOPENAI_API_KEYsk-your-actual-openai-api-key-here3. 核心原理与框架拆解LangChain 中的 Agent 与 Tools在构建技能之前需要理解 LangChain 如何实现智能体。其核心是AgentExecutor它驱动一个循环理解用户输入 - 选择工具 - 执行工具 - 观察结果 - 继续思考或返回最终答案。3.1 工具Tool的定义在 LangChain 中一个工具本质是一个带有描述和参数的函数。使用tool装饰器可以轻松创建。# tools/custom_tools.py from langchain.tools import tool import requests tool def get_current_weather(location: str) - str: 获取指定城市的当前天气。参数 location 是城市名例如 ‘北京‘ ‘上海‘。 # 这里使用一个模拟的免费API实际项目请替换为可靠的API如OpenWeatherMap try: # 示例API可能不稳定 url fhttps://wttr.in/{location}?format%C%t response requests.get(url, timeout10) if response.status_code 200: return f{location}的天气是{response.text} else: return f无法获取{location}的天气API返回状态码{response.status_code} except Exception as e: return f获取天气时出错{str(e)} tool def search_news(keyword: str, max_results: int 3) - str: 根据关键词搜索最新新闻。参数 keyword 是搜索关键词max_results 是返回的最大新闻条数默认3条。 # 使用一个免费的新闻API示例NewsAPI需要注册此处用模拟 # 实际开发中请替换为真实的 NewsAPI 调用 mock_news_data { AI: [ 【AI突破】研究人员开发出新型节能算法训练成本降低50%。, 【行业动态】多家科技公司宣布成立AI伦理联盟。, 【产品发布】XX公司推出新一代代码辅助编程工具。 ], 科技: [ 【航天】民营公司成功完成可回收火箭第10次发射。, 【芯片】新一代国产CPU性能提升显著已投入商用。, ] } news_list mock_news_data.get(keyword, [f未找到关于‘{keyword}‘的特定新闻。以下是科技快讯...]) return f关于‘{keyword}‘的新闻摘要共{min(max_results, len(news_list))}条\n \n.join(news_list[:max_results])3.2 智能体类型与初始化LangChain 提供了多种预设的智能体类型如ZERO_SHOT_REACT_DESCRIPTION,OPENAI_FUNCTIONS,STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION等。我们使用OPENAI_FUNCTIONS它利用 OpenAI 的函数调用功能更稳定可靠。# agent_builder.py from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI from tools.custom_tools import get_current_weather, search_news import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 def build_basic_agent(): 构建一个具备基础工具天气、新闻的智能体 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定 openai_api_keyos.getenv(OPENAI_API_KEY) ) tools [get_current_weather, search_news] agent initialize_agent( toolstools, llmllm, agentAgentType.OPENAI_FUNCTIONS, # 使用OpenAI函数调用代理 verboseTrue, # 打印详细的思考过程便于调试 handle_parsing_errorsTrue # 优雅处理解析错误 ) return agent3.3 智能体运行循环解析当执行agent.run(“北京天气怎么样”)时背后发生规划LLM 根据用户问题和可用工具描述决定调用get_current_weather并生成符合函数签名的参数{“location”: “北京”}。执行LangChain 执行该工具函数获得结果字符串。观察将工具执行结果返回给 LLM。再规划/回答LLM 判断是否需要继续调用其他工具。本例中结果已足够LLM 将工具结果组织成自然语言回复给用户。verboseTrue会打印出这些中间步骤是调试的利器。4. 实战构建复合型 Agent Skill现在我们将两个基础工具组合成一个更高级的“出行信息简报”技能。这个技能的目标是用户输入一个城市名智能体不仅返回天气还返回该城市相关的热点新闻。4.1 设计技能逻辑技能逻辑输入城市-并行或依次获取天气和新闻-整合信息生成一份简报。 我们将这个流程封装成一个新的函数但它本身不作为直接暴露给智能体的工具而是作为我们应用程序的一个高级功能。4.2 实现技能类我们创建一个技能类它内部使用之前定义的工具并添加了业务逻辑。# skills/travel_brief_skill.py from typing import Dict, Any from tools.custom_tools import get_current_weather, search_news class TravelBriefSkill: 出行信息简报技能为指定城市生成包含天气和新闻的简报。 def __init__(self): self.name travel_brief self.description 为指定的城市生成一份出行简报包含当前天气和当地热点新闻。 def run(self, city: str) - Dict[str, Any]: 执行技能。 参数: city: 城市名称例如“上海”、“New York”。 返回: 包含天气、新闻和综合简报的字典。 print(f[TravelBriefSkill] 正在为城市 ‘{city}‘ 生成简报...) # 1. 并行或顺序执行子任务此处顺序执行 weather_info get_current_weather.invoke({location: city}) news_info search_news.invoke({keyword: city, max_results: 3}) # 2. 整合信息这里可以加入更复杂的逻辑比如根据天气推荐衣物 brief f 【{city}出行简报】 ️ 天气状况{weather_info} 本地要闻 {news_info} --- 祝您出行愉快 # 3. 返回结构化结果 return { “city”: city, “weather”: weather_info, “news”: news_info, “brief”: brief.strip() } # 为了方便使用可以创建一个实例 travel_brief_skill TravelBriefSkill()4.3 将技能封装为智能体可用的工具为了让现有的智能体能直接调用这个技能我们需要将其“包装”成一个 LangChain Tool。# skills/travel_brief_skill.py (续) from langchain.tools import Tool # 将技能的 run 方法适配成 Tool 需要的函数格式 def travel_brief_tool_func(city: str) - str: 为指定城市生成出行简报。输入应为城市名称。 skill TravelBriefSkill() result skill.run(city) # 返回简报字符串智能体会直接把这个字符串作为结果 return result[“brief”] # 创建 LangChain Tool 对象 travel_brief_tool Tool( name“TravelBriefMaker”, functravel_brief_tool_func, description“””为指定的城市生成一份出行简报包含当前天气和当地热点新闻。 输入应该是一个明确的城市名称例如‘北京’、‘上海’、‘纽约’。””” )4.4 构建具备高级技能的智能体现在我们构建一个新的智能体它同时拥有基础工具和这个高级技能工具。# agent_builder.py (新增函数) from skills.travel_brief_skill import travel_brief_tool def build_advanced_agent(): 构建一个具备基础工具和高级出行简报技能的智能体 llm ChatOpenAI(model“gpt-3.5-turbo”, temperature0, openai_api_keyos.getenv(“OPENAI_API_KEY”)) # 工具列表包含基础工具和高级技能工具 tools [get_current_weather, search_news, travel_brief_tool] agent initialize_agent( toolstools, llmllm, agentAgentType.OPENAI_FUNCTIONS, verboseTrue, handle_parsing_errorsTrue ) return agent4.5 运行与验证创建一个主程序来测试我们的智能体。# main.py from agent_builder import build_basic_agent, build_advanced_agent import sys def main(): print(“请选择要测试的智能体类型”) print(“1. 基础智能体 (天气、新闻)”) print(“2. 高级智能体 (增加出行简报技能)”) choice input(“请输入 1 或 2: “).strip() if choice “1”: agent build_basic_agent() print(“\n 基础智能体已就绪请输入您的问题例如北京天气怎么样或 搜索AI新闻”) elif choice “2”: agent build_advanced_agent() print(“\n 高级智能体已就绪您可以问‘为上海生成一份出行简报’或基础问题 ”) else: print(“输入无效退出程序。”) sys.exit(1) while True: try: user_input input(“\n您: “).strip() if user_input.lower() in [“quit”, “exit”, “q”]: print(“再见”) break if not user_input: continue # 运行智能体 response agent.run(user_input) print(f“\nAgent: {response}”) except KeyboardInterrupt: print(“\n程序被中断。”) break except Exception as e: print(f“\n处理请求时出错{e}”) if __name__ “__main__”: main()运行程序cd agent_skills_project python main.py选择2然后输入“为北京生成一份出行简报”。观察verboseTrue模式下智能体的思考过程它会正确选择TravelBriefMaker工具并最终输出整合了天气和新闻的简报。5. 常见问题与排查思路在开发 Agent Skills 过程中你一定会遇到以下典型问题。问题现象可能原因排查与解决思路错误OpenAI API未授权或额度不足1..env文件未正确加载或OPENAI_API_KEY未设置。2. API Key 错误或已失效。3. 账户余额不足。1. 检查load_dotenv()是否调用打印os.getenv(“OPENAI_API_KEY”)前几位确认。2. 在 OpenAI 平台检查 Key 有效性。3. 登录 OpenAI 平台查看使用量和余额。智能体不调用正确的工具1. 工具Tool的description描述不清LLM 无法理解其用途。2. 用户提问方式与工具描述不匹配。3. 工具过多LLM 困惑。1.优化描述确保description清晰、简洁包含关键词和准确的参数说明。2.改进提示在系统消息或用户提问中引导智能体。例如“请使用出行简报技能来回答”。3.精简工具集只提供与当前任务最相关的工具。工具调用参数错误1. 工具函数参数类型与 LLM 推断的不符。2. 复杂参数如嵌套对象解析失败。1.使用STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION代理它更适合处理多参数工具。2.简化工具接口尽量让工具接收字符串参数。3.检查handle_parsing_errors设置为True能让代理在解析失败时尝试修复。技能内部逻辑错误1. 调用的外部 API 失败或超时。2. 技能内部代码存在 bug如变量未定义。3. 网络问题。1.增加异常捕获和日志在技能run方法内部用try…except包裹返回友好错误信息。2.单元测试为技能的每个子功能编写测试。3.超时设置为网络请求设置合理的timeout。verbose模式下看到无限循环或重复调用1. 工具返回的结果不足以让 LLM 得出最终答案。2. 代理类型选择不当。1.优化工具输出确保工具返回的信息是完整、明确的。2.设置max_iterations在initialize_agent中传入max_iterations5等参数防止死循环。3.使用更强大的模型如 GPT-4其规划和推理能力更强。6. 最佳实践与工程建议将 Agent Skills 从 demo 推向生产环境需要关注以下几点6.1 技能设计原则单一职责一个技能应专注于完成一个明确的、高层次的任务。可复用性设计技能时考虑其通用性避免与特定业务场景过度耦合。可以通过参数化来增加灵活性。错误处理与鲁棒性技能内部必须对可能失败的操作如网络调用、数据解析进行妥善处理返回结构化的错误信息而不是抛出异常导致智能体崩溃。可观测性在技能的关键节点添加日志记录便于追踪执行流程和排查问题。6.2 性能与成本优化缓存对于耗时长或调用成本高的操作如某些API调用考虑引入缓存机制如functools.lru_cache或 Redis在输入相同时直接返回缓存结果。异步执行如果技能需要调用多个独立的 I/O 操作如同时查询天气和新闻使用asyncio进行异步调用可以显著降低延迟。模型选择简单的工具调用和路由任务使用gpt-3.5-turbo性价比高。复杂的规划和推理任务再考虑gpt-4。6.3 安全与权限输入验证与清理对所有来自用户输入并传递给技能/工具的参数进行严格的验证和清理防止注入攻击。权限控制不是所有用户都能调用所有技能。在生产系统中需要建立技能-用户权限映射在智能体调用技能前进行鉴权。敏感信息隔离API密钥、数据库密码等敏感信息必须通过环境变量或安全的配置中心管理绝不可硬编码在代码中。6.4 部署与监控容器化使用 Docker 将你的智能体应用及其依赖打包确保环境一致性。API 化使用 FastAPI 或 Flask 将智能体封装成 RESTful API方便与其他系统集成。监控指标记录智能体的调用次数、成功率、平均响应时间、Token 消耗量等关键指标以便进行成本分析和性能优化。7. 扩展方向与学习路线掌握了基础技能构建后你可以向以下方向深入探索探索更强大的框架LangGraphLangChain 官方推出的用于构建复杂、有状态的多智能体工作流的库。非常适合实现需要严格步骤控制、循环、分支的复杂技能。AutoGen微软推出的多智能体对话框架擅长模拟多个专家智能体协作解决任务。Semantic Kernel微软的轻量级 SDK支持将传统编程与 AI 模型提示词、函数深度融合。集成 MCP 服务器学习如何将你的工具或技能封装成 MCP 服务器这样它们就可以被任何支持 MCP 的客户端如 Claude Desktop发现和使用极大提高可移植性。实现记忆与状态管理让智能体记住之前的对话历史短期记忆或关键用户信息长期记忆从而进行连贯的多轮对话。可以集成LangChain Memory组件。连接真实数据源将技能与你的业务数据库、内部 API、知识库连接起来打造真正有用的企业级智能助手。例如构建一个“客户服务技能”能查询订单、检索知识库文章。评估与持续改进建立技能效果的评估体系通过人工反馈或自动化测试不断优化技能的提示词描述、内部逻辑和工具组合。从构建一个简单的天气查询工具到设计一个协调多步骤的出行简报技能你已经走过了 Agent Skills 落地的关键路径。记住核心在于“分解复杂任务为可执行的工具再组合工具为有价值的技能”。接下来选择一个你业务中重复性高、规则明确的场景尝试用智能体技能将其自动化在实践中你会遇到更多具体问题解决它们就是你成长为 AI 应用开发专家的过程。