这次我们来看一个关于 AI Agent 与 Skills 开发的系统性教程。对于想要从零开始构建智能体应用尤其是希望掌握如何为 Agent 赋予各种“技能”Skills的开发者来说一套结构清晰、从理论到实战的教程至关重要。本文旨在为你梳理出一条高效的学习路径涵盖从核心概念理解、环境搭建、到代码实战开发的完整流程让你能够快速上手并构建自己的智能体应用。AI Agent 的核心在于其“智能”与“行动”能力而 Skills 则是实现具体行动的工具集。无论是处理文件、调用 API、分析数据还是与外部系统交互都需要通过 Skills 来完成。因此掌握 Skills 的开发是 Agent 开发中最具实践价值的一环。本文将重点关注如何从入门到精通手把手带你完成环境配置、基础 Skill 开发、复杂 Skill 集成以及项目实战。1. 核心能力速览Agent Skills 开发全景在深入代码之前我们先快速了解学习 Agent Skills 开发所能获得的核心能力与所需的技术栈这有助于你判断是否要继续投入时间。能力项说明与目标核心掌握理解 Agent 架构中 Skills 的作用、生命周期与调用机制。开发技能能够使用 Python主流或其他语言开发自定义的 Skills包括工具调用、API 封装、数据处理等。集成能力将开发的 Skills 集成到主流 Agent 框架如 LangChain, AutoGen, CrewAI 等中使 Agent 具备相应能力。调试与测试掌握对 Skills 进行单元测试、集成测试以及通过 Agent 进行端到端测试的方法。环境门槛中等。需要基础的 Python 编程能力、熟悉 REST API 概念本地或云服务器均可。无特殊 GPU 要求。典型工具链Python 3.8, Pip/Conda, 代码编辑器VSCode/PyCharm, Git, 可选 Docker。学习产出能够独立开发并部署至少 3-5 个具有实用价值的 Skills并集成到一个可运行的 Agent 原型中。2. 适用场景与学习边界学习 Agent Skills 开发主要适用于以下几类人群和场景适合谁AI 应用开发者希望为 LLM 增加具体执行能力构建功能更完善的 AI 应用。后端/全栈工程师希望将现有服务或 API 封装成智能体可调用的 Skills提升系统智能化水平。技术爱好者/学生对 AI Agent 实现原理感兴趣希望通过动手实践深入理解。产品经理/技术负责人需要评估 Agent 技术落地可行性了解 Skills 开发的成本与边界。能解决什么问题能力扩展让大语言模型突破“仅能对话”的局限可以执行查询天气、发送邮件、分析数据库、操作文件等具体任务。流程自动化通过组合多个 Skills实现多步骤工作流的自动化例如爬取数据 - 分析总结 - 生成报告 - 邮件发送。系统集成作为中间层将企业内部系统CRM、ERP、OA的能力安全、可控地暴露给 AI Agent 使用。学习边界与注意事项不是银弹Skills 开发是工程实现它不能解决 Agent 在规划、推理、记忆等核心智能层面的根本问题而是为其提供“手脚”。安全与权限开发 Skills 时必须高度重视安全性。特别是涉及数据访问、文件操作、网络请求的 Skill需设计严格的输入验证、权限控制和审计日志。依赖管理每个 Skill 可能引入新的第三方库需要妥善管理依赖避免版本冲突。错误处理Skill 执行可能失败网络超时、API 变更、资源不足必须有健壮的错误处理机制并向 Agent 返回清晰的错误信息。3. 环境准备与前置条件开始实战前请确保你的开发环境满足以下基础要求。这是后续所有步骤的基石。3.1 基础软件环境操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04 推荐)。本文示例以 macOS/Linux 命令为主Windows 用户可使用 WSL2 或对应 PowerShell 命令。Python版本 3.8 或 3.9。这是大多数 Agent 框架的稳定支持版本。避免使用 Python 3.10 可能遇到的某些库兼容性问题。# 检查Python版本 python --version # 或 python3 --version包管理工具pip必须为最新版。强烈建议使用venv或conda创建独立的虚拟环境。# 创建虚拟环境 python -m venv agent_skills_env # 激活环境 (Linux/macOS) source agent_skills_env/bin/activate # 激活环境 (Windows) agent_skills_env\Scripts\activate代码编辑器Visual Studio Code (VSCode) 或 PyCharm。VSCode 轻量且插件丰富推荐安装 Python、Pylance、GitLens 等插件。Git用于版本管理和克隆示例项目。git --version3.2 可选但推荐的工具Docker Docker Compose用于环境隔离和依赖封装尤其在部署阶段非常有用。Postman 或 Insomnia用于测试 Skill 暴露的 HTTP API如果有。Jupyter Notebook用于快速原型验证和交互式测试。4. 项目初始化与第一个 Skill 开发我们从一个最简单的“回声”EchoSkill 开始理解 Skill 的基本结构。4.1 创建项目目录结构一个清晰的项目结构有助于管理多个 Skills。agent-skills-tutorial/ ├── skills/ # 存放所有自定义Skills │ ├── __init__.py │ ├── echo_skill.py # 第一个Skill │ └── weather_skill.py # 后续增加的Skill ├── agents/ # 存放Agent配置和主程序 │ └── main_agent.py ├── tests/ # 单元测试 │ └── test_skills.py ├── requirements.txt # 项目依赖 └── README.md4.2 安装基础依赖在激活的虚拟环境中创建requirements.txt并安装。我们以 LangChain 为例因为它提供了清晰且广泛使用的 Tools即 Skills抽象。langchain0.1.0 langchain-openai0.0.5 openai1.0.0 python-dotenv1.0.0 pytest7.0.0 # 用于测试安装命令pip install -r requirements.txt4.3 编写 Echo Skill在skills/echo_skill.py中我们定义一个最简单的工具它接收一段文本并原样返回。from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type class EchoInput(BaseModel): Echo工具的输入模型。 message: str Field(description需要被回声输出的消息) class EchoSkill(BaseTool): name echo_tool description 一个简单的回声工具输入什么就返回什么。用于测试和演示。 args_schema: Type[BaseModel] EchoInput def _run(self, message: str) - str: 执行工具的主逻辑。 # 这里可以加入更复杂的逻辑例如日志记录 print(f[EchoSkill] 收到消息: {message}) return f回声: {message} async def _arun(self, message: str) - str: 异步执行版本。 return self._run(message) # 为了方便导入可以在skills/__init__.py中暴露它 # from .echo_skill import EchoSkill关键点解析继承BaseTool这是 LangChain 中所有工具的基类。name和description至关重要。AgentLLM通过 description 来判断在什么场景下调用这个工具。args_schema使用 Pydantic 模型严格定义输入参数这能帮助 LLM 生成正确的调用参数。_run方法同步执行逻辑。_arun是异步版本。4.4 测试 Echo Skill在项目根目录创建一个测试脚本test_echo.pyimport sys sys.path.append(.) from skills.echo_skill import EchoSkill def test_echo_skill(): tool EchoSkill() # 测试同步调用 result tool.run(你好世界) print(result) # 输出: 回声: 你好世界 if __name__ __main__: test_echo_skill()运行它确保 Skill 能正常工作。这是开发任何 Skill 后的第一步。5. 开发实用型 Skills以天气查询为例现在我们来开发一个更有实用价值的 Skill天气查询。它将调用一个公开的天气 API。5.1 分析设计与依赖功能根据城市名查询实时天气。输入城市名字符串。输出结构化的天气信息字符串。外部依赖requests库用于调用 API。API 选择使用免费开放的天气 API如 Open-Meteo 或和风天气需注册免费密钥。首先安装额外依赖pip install requests5.2 编写 Weather Skill在skills/weather_skill.py中import requests from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type import os from dotenv import load_dotenv load_dotenv() # 加载环境变量 class WeatherInput(BaseModel): 天气查询工具的输入模型。 city_name: str Field(description需要查询天气的城市名称例如北京、Shanghai) class WeatherSkill(BaseTool): name get_weather description 根据城市名称查询当前的天气情况包括温度、天气状况和湿度。 args_schema: Type[BaseModel] WeatherInput def _run(self, city_name: str) - str: 调用天气API查询天气。 # 注意这里使用示例API实际需要替换为有效的API端点并处理密钥 # 示例使用 Open-Meteo 免费API (无需密钥但功能有限) try: # 第一步通过城市名获取经纬度这里简化实际应使用地理编码API # 仅为演示我们假设一个映射或使用固定坐标 city_coords { beijing: (39.9042, 116.4074), shanghai: (31.2304, 121.4737), new york: (40.7128, -74.0060), } coords city_coords.get(city_name.lower()) if not coords: return f抱歉暂不支持查询城市 {city_name} 的天气。请尝试北京、上海、New York等。 lat, lon coords url fhttps://api.open-meteo.com/v1/forecast?latitude{lat}longitude{lon}current_weathertrue response requests.get(url, timeout10) response.raise_for_status() data response.json() current data.get(current_weather, {}) temperature current.get(temperature) weather_code current.get(weathercode) # 简化天气代码转换 weather_map { 0: 晴, 1: 晴间多云, 2: 多云, 3: 阴天, 45: 雾, 61: 小雨, } condition weather_map.get(weather_code, 未知) return f{city_name}的当前天气温度 {temperature}°C, 天气状况 {condition}。 except requests.exceptions.RequestException as e: return f查询天气时网络出错{e} except Exception as e: return f查询天气时发生未知错误{e} async def _arun(self, city_name: str) - str: 异步版本。 return self._run(city_name)5.3 关键改进点错误处理网络请求必须包含try...except块确保 Skill 失败时能返回友好信息而不是导致整个 Agent 崩溃。输入处理对用户输入城市名进行了小写转换和映射提高了容错性。在生产环境中应集成更完善的地理编码服务。环境变量使用python-dotenv管理 API 密钥等敏感信息避免硬编码。描述清晰description字段明确说明了工具的功能和输入格式这是 Agent 能否正确调用的关键。5.4 测试 Weather Skill创建test_weather.pyimport sys sys.path.append(.) from skills.weather_skill import WeatherSkill def test_weather_skill(): tool WeatherSkill() # 测试已知城市 result tool.run(beijing) print(result) # 测试未知城市 result2 tool.run(unknowncity) print(result2) if __name__ __main__: test_weather_skill()6. 将 Skills 集成到 Agent 并运行测试单个 Skill 是零件现在我们需要把它组装到“智能体”这台机器上。6.1 创建基础 Agent在agents/main_agent.py中我们创建一个使用 OpenAI GPT 模型并集成了上述两个 Skills 的简单 Agent。import os from dotenv import load_dotenv from langchain.agents import initialize_agent, AgentType from langchain_openai import ChatOpenAI from langchain.memory import ConversationBufferMemory # 导入我们自定义的Skills import sys sys.path.append(..) # 根据你的目录结构调整 from skills.echo_skill import EchoSkill from skills.weather_skill import WeatherSkill load_dotenv() def create_agent(): # 1. 初始化LLM需要设置你的OPENAI_API_KEY环境变量 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, openai_api_keyos.getenv(OPENAI_API_KEY) ) # 2. 初始化我们自定义的工具列表 tools [EchoSkill(), WeatherSkill()] # 3. 可选添加记忆让Agent能记住对话上下文 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 4. 创建Agent agent initialize_agent( tools, llm, agentAgentType.CHAT_CONVERSATIONAL_REACT_DESCRIPTION, # 适合对话式能利用记忆 verboseTrue, # 打印详细的思考过程便于调试 memorymemory, handle_parsing_errorsTrue # 当LLM输出格式错误时尝试自动修复 ) return agent if __name__ __main__: # 在.env文件中设置 OPENAI_API_KEYsk-... agent create_agent() # 开始与Agent对话 while True: try: user_input input(\n你: ) if user_input.lower() in [quit, exit, q]: break response agent.run(user_input) print(fAgent: {response}) except Exception as e: print(f发生错误: {e})6.2 运行与调试在项目根目录创建.env文件填入你的 OpenAI API KeyOPENAI_API_KEYyour_openai_api_key_here运行 Agentcd agents python main_agent.py在对话中测试输入“你能做什么” Agent 会列出可用的工具。输入“用回声工具说‘你好’。” 观察 Agent 是否正确调用EchoSkill。输入“北京天气怎么样” 观察 Agent 是否调用WeatherSkill并返回结果。输入“先查询上海天气然后对结果说声‘谢谢’。” 测试多轮交互和记忆能力。6.3 观察与理解 Agent 的思考过程由于设置了verboseTrue控制台会输出类似以下的日志这是理解 Agent 如何工作的关键 Entering new AgentExecutor chain... Thought: 用户想知道北京的天气。我有一个工具叫 get_weather描述是查询天气。我应该使用它。 Action:{ action: get_weather, action_input: {city_name: beijing} }Observation: 北京的当前天气温度 22°C天气状况 晴。 Thought: 我已经得到了天气信息可以回答用户了。 Action:{ action: Final Answer, action_input: 北京的当前天气是晴天温度大约22摄氏度。 }通过这个过程你可以清晰地看到 Agent 的“思考-行动-观察”循环这对于调试复杂的 Skill 调用链至关重要。7. 开发高级 Skill文件操作与批量任务一个强大的 Agent 需要能处理更复杂的任务例如文件操作。我们开发一个FileReadSkill并探讨如何设计支持批量任务的 Skill。7.1 FileReadSkill 开发在skills/file_skill.py中import os from pathlib import Path from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Type class FileReadInput(BaseModel): 文件读取工具的输入模型。 file_path: str Field(description需要读取的文件的绝对路径或相对于当前工作目录的路径) class FileReadSkill(BaseTool): name read_file description 读取指定文本文件的内容。输入应为文件的路径。 args_schema: Type[BaseModel] FileReadInput def _run(self, file_path: str) - str: 读取文件内容。 try: path Path(file_path) if not path.exists(): return f错误文件 {file_path} 不存在。 if not path.is_file(): return f错误{file_path} 不是一个文件。 # 安全考虑可以在这里检查文件大小避免读取过大文件 if path.stat().st_size 1_000_000: # 例如限制1MB return f错误文件过大超过1MB出于安全考虑拒绝读取。 # 读取文本内容 content path.read_text(encodingutf-8, errorsignore) # 返回前可以截断过长的内容 if len(content) 2000: content content[:2000] \n... (内容已截断) return f文件 {file_path} 的内容如下\n\n{content}\n except PermissionError: return f错误没有权限读取文件 {file_path}。 except Exception as e: return f读取文件时发生未知错误{e} async def _arun(self, file_path: str) - str: return self._run(file_path)安全与边界设计路径检查验证文件是否存在、是否为普通文件。大小限制防止 Agent 意外读取超大文件导致内存问题。权限处理捕获权限错误并返回友好提示。内容截断对于超长文本进行截断避免淹没 Agent 的上下文窗口。7.2 批量任务的设计模式真正的“批量任务”往往不是单个 Skill 能完成的而是通过 Agent 的规划和迭代来实现。例如Agent 可以结合list_files(一个列出目录的 Skill) 和read_file来批量处理多个文件。我们可以创建一个BatchProcessorSkill的概念模型它本身可能不直接处理批量而是指导 Agent 如何操作# 概念性代码展示思路 class BatchProcessInput(BaseModel): directory_path: str Field(description需要处理的目录路径) file_pattern: str Field(description文件匹配模式例如 *.txt) class BatchProcessorSkill(BaseTool): name batch_process_hint description 指导Agent如何批量处理一个目录下的文件。例如先列出文件再对每个文件进行特定操作。 args_schema: Type[BaseModel] BatchProcessInput def _run(self, directory_path: str, file_pattern: str *.txt) - str: # 这个Skill不直接执行批量操作而是返回一个计划或提示。 return ( f要批量处理目录 {directory_path} 下匹配 {file_pattern} 的文件你可以\n f1. 使用 list_files 工具获取文件列表。\n f2. 对于列表中的每个文件使用 read_file 或 analyze_file 等工具进行处理。\n f3. 最后使用 summarize_results 工具汇总结果。\n f这是一个多步骤任务请逐步执行。 )实际上更常见的做法是让 Agent 利用其规划能力结合多个基础 Skillslist_files,read_file,write_file,call_analysis_api自动完成批量任务。这考验的是 Agent 框架的规划和工具调用能力。8. 接口 API 与外部服务集成对于更复杂的 Skill尤其是需要调用内部或第三方服务的我们通常将其封装为一个独立的微服务并通过 HTTP API 暴露给 Agent。8.1 设计一个 API 封装的 Skill假设我们有一个内部用户查询服务端点为http://internal-api.example.com/user/{id}。我们为其创建一个 Skill。在skills/user_api_skill.py中import requests from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Type import os from dotenv import load_dotenv load_dotenv() class UserQueryInput(BaseModel): user_id: str Field(description需要查询的用户ID) class UserQuerySkill(BaseTool): name query_user_info description 根据用户ID查询用户的基本信息姓名、部门等。 args_schema: Type[BaseModel] UserQueryInput def _run(self, user_id: str) - str: api_base os.getenv(INTERNAL_API_BASE, http://internal-api.example.com) # 从环境变量获取认证信息例如API Key api_key os.getenv(INTERNAL_API_KEY) headers {Authorization: fBearer {api_key}} if api_key else {} try: url f{api_base}/user/{user_id} response requests.get(url, headersheaders, timeout15) response.raise_for_status() user_data response.json() # 格式化返回信息 return ( f用户ID: {user_data.get(id)}\n f姓名: {user_data.get(name)}\n f部门: {user_data.get(department)}\n f邮箱: {user_data.get(email)} ) except requests.exceptions.HTTPError as e: if response.status_code 404: return f错误未找到用户ID为 {user_id} 的用户。 else: return f查询用户API返回错误 (状态码 {response.status_code}): {e} except requests.exceptions.RequestException as e: return f网络请求失败{e} except Exception as e: return f处理用户信息时发生错误{e} async def _arun(self, user_id: str) - str: return self._run(user_id)8.2 关键实践配置化API 地址、认证密钥等必须从环境变量读取保证安全性和可移植性。健壮的错误处理区分不同的 HTTP 状态码如 404、500返回对 Agent 和最终用户都有意义的错误信息。超时设置为网络请求设置合理的超时避免 Skill 调用阻塞整个 Agent 过长时间。结构化输出将 JSON 响应转换为清晰、易读的自然语言字符串方便 LLM 理解和后续处理。9. 测试、调试与性能观察开发 Skills 后系统的测试和性能观察是保证其可靠性的关键。9.1 单元测试为每个 Skill 编写单元测试。在tests/test_skills.py中import sys import os sys.path.append(os.path.join(os.path.dirname(__file__), ..)) from skills.echo_skill import EchoSkill from skills.weather_skill import WeatherSkill from skills.file_skill import FileReadSkill def test_echo_skill(): tool EchoSkill() result tool.run(test message) assert 回声: test message in result print(✓ EchoSkill test passed.) def test_weather_skill_basic(): tool WeatherSkill() # 测试已知城市模拟或使用固定坐标 result tool.run(beijing) assert 北京 in result or beijing in result.lower() # 测试未知城市 result2 tool.run(unknowncity123) assert 不支持 in result2 or 抱歉 in result2 print(✓ WeatherSkill test passed.) def test_file_read_skill(): tool FileReadSkill() # 创建一个临时测试文件 test_file test_temp.txt with open(test_file, w, encodingutf-8) as f: f.write(Hello, this is a test file.) try: result tool.run(test_file) assert Hello, this is a test file. in result print(✓ FileReadSkill test passed.) finally: # 清理 if os.path.exists(test_file): os.remove(test_file) if __name__ __main__: test_echo_skill() test_weather_skill_basic() test_file_read_skill() print(All tests passed!)使用pytest运行测试pytest tests/test_skills.py -v9.2 集成测试与 Agent 端到端测试在agents/目录下创建集成测试脚本模拟真实用户对话验证多个 Skills 协同工作是否正常。9.3 性能观察与资源占用对于 Agent 系统性能瓶颈通常不在自定义的 Skills 上而在 LLM 的 API 调用延迟和费用以及复杂 Skills 的 I/O 操作网络、文件。监控点LLM 调用延迟记录每个agent.run的耗时。工具执行时间在每个 Skill 的_run方法开始和结束记录时间。上下文长度注意 Agent 的对话历史是否过长导致 Token 消耗剧增。需要适时使用ConversationSummaryMemory或清空记忆。优化建议对于耗时的 Skills如调用慢速 API考虑实现异步版本 (_arun) 并在异步 Agent 中调用。缓存频繁查询且变化不大的数据如天气、用户基本信息。设置合理的超时和重试机制。10. 常见问题与排查方法在开发和使用 Agent Skills 过程中你会遇到一些典型问题。问题现象可能原因排查方式解决方案Agent 无法识别或调用自定义 Skill1. Skill 未正确添加到tools列表。2. Skill 的name或description描述不清LLM 无法理解其用途。3. Agent 类型选择不当。1. 检查initialize_agent的tools参数。2. 设置verboseTrue观察 Agent 的思考链看它是否列出了你的工具。3. 尝试更详细的description。1. 确保 Skill 实例被传入。2. 优化description用自然语言清晰说明功能、输入和输出。3. 尝试AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION或AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION。Skill 被调用但参数错误1.args_schema定义不清晰或与_run方法参数不匹配。2. LLM 未能正确解析用户意图。1. 检查verbose日志中 Agent 发出的action_inputJSON 是否规范。2. 在 Skill 的_run方法开头打印输入参数。1. 确保args_schema中的字段名和类型准确description对每个字段都有说明。2. 在 Agent 初始化时设置handle_parsing_errorsTrue。Skill 执行时报错如网络、文件错误Skill 内部代码异常未捕获。查看控制台输出的完整错误堆栈。在 Skill 的_run方法中用try...except包裹核心逻辑并返回友好的错误信息字符串而不是抛出异常。Agent 陷入循环或执行无关动作1.description过于宽泛导致 LLM 在不该调用时调用。2. 任务过于复杂Agent 规划失败。观察verbose日志看 Agent 的思考链是否在重复或偏离主题。1. 缩小和精确化 Skill 的description。2. 将复杂任务拆分成更小的子任务或开发一个更高级的“规划型”Skill 来指导 Agent。3. 尝试使用AgentExecutor的max_iterations参数限制最大步数。依赖库版本冲突不同的 Skills 或框架依赖不同版本的同一库。使用pip list检查版本或运行代码看ImportError。1. 使用虚拟环境隔离项目。2. 在requirements.txt中固定主要依赖的版本。3. 使用poetry或pipenv进行更严格的依赖管理。11. 最佳实践与进阶方向最佳实践单一职责每个 Skill 应只做一件事并做好。避免创建功能臃肿的“超级工具”。描述即契约name和description是与 LLM 沟通的桥梁务必准确、清晰、无歧义。防御性编程假设所有输入都不可信进行验证、清理和转义。对网络、文件 I/O 操作必须有超时和错误处理。日志与可观测性在 Skill 的关键步骤添加日志便于追踪执行过程和调试。配置外置API 密钥、服务地址、文件路径等配置信息一律通过环境变量或配置文件管理。测试驱动为每个 Skill 编写单元测试特别是对于核心逻辑和边界条件。进阶方向异步 Skills对于 I/O 密集型操作实现_arun方法并使用支持异步的 Agent 执行器提升并发性能。结构化输出让 Skill 返回 Pydantic 模型对象而不仅仅是字符串以便后续 Skills 或 Agent 进行结构化处理。技能组合与工作流研究 LangChain 的Toolkits、Agents或 CrewAI、AutoGen 等框架学习如何将多个 Skills 编排成复杂的工作流。技能注册与发现构建一个技能注册中心让 Agent 能够动态发现和加载新的 Skills实现热插拔。Human-in-the-loop在 Skill 执行关键操作如删除文件、发送邮件前设计审批或确认机制。从开发一个简单的回声工具到集成外部 API、处理文件再到思考批量任务和架构设计这条学习路径的核心在于理解“将复杂能力封装成标准化接口供 LLM 调用”这一模式。掌握了这个模式你就能让 AI Agent 突破文本生成的限制真正成为能够操作数字世界的智能助手。建议从本文的示例代码开始亲手运行和修改每一个 Skill理解其与 Agent 交互的每一个细节这是通往精通最扎实的一步。