最近在AI圈子里吴恩达教授关于“Agent Skills”的课程讨论度很高很多开发者都在问这到底是又一个被过度包装的概念还是真的能改变我们构建AI应用的方式我的判断是“Agent Skills”的核心价值在于它提供了一套标准化的、可复用的“技能”构建范式将AI Agent的开发从“手工作坊”模式推进到了“组件化”工程阶段。它解决的不是“能不能”让AI执行任务的问题而是“如何高效、稳定、规模化”地让AI执行复杂任务的问题。如果你还在用“提示词工程”的老办法让一个AI模型去处理从数据查询、代码生成到结果验证的全流程很快就会遇到瓶颈提示词臃肿、逻辑混乱、错误难以定位、功能无法复用。而“Agent Skills”的思路是把一个复杂的Agent拆解成多个专注、可测试、可组合的“技能”Skills。这就像从写一个几千行的“上帝类”函数转向设计一个由多个单一职责的类组成的清晰架构。本文将基于这一核心判断为你拆解“Agent Skills”的核心思想、与Anthropic Claude模型的结合实践以及一套从零搭建可运行技能链的保姆级教程。你将不仅理解概念更能亲手搭建一个具备“思考-行动-观察”循环的实用Agent。1. Agent Skills 要解决的真正问题从“提示词魔术”到“软件工程”在深入代码之前我们必须先厘清一个根本问题为什么需要“Skills”想象一个场景你需要一个Agent帮你分析GitHub仓库的活跃度。传统“单体提示词”方式可能是“你是一个代码分析专家请访问仓库https://github.com/xxx/yyy获取最近一个月的提交数、贡献者列表和主要Issue然后生成一份报告。”这个提示词至少隐含了四个独立子任务解析指令理解用户要分析哪个仓库。获取数据调用GitHub API或爬虫获取原始数据。处理与分析对获取的提交、贡献者等数据进行统计和解读。组织与报告将分析结果格式化成一份易读的报告。当任何一个环节出错如API限流、数据格式变化、分析逻辑有误整个流程都会失败并且很难定位问题所在。更糟糕的是如果你想做一个“分析GitLab仓库”的Agent大部分逻辑要重写。Agent Skills 范式带来的转变是解耦将上述四个子任务定义为四个独立的Skill。复用数据获取Skill稍作修改就能同时服务于GitHub和GitLab分析。测试每个Skill可以单独进行单元测试。组合你可以像搭积木一样将解析Skill、GitHub数据Skill、分析Skill、报告Skill组合成一个工作流。维护当GitHub API升级时你只需要修改GitHub数据Skill而不会影响分析和报告的逻辑。这就是从“提示词魔术”靠一个复杂的、难以调试的提示词驱动一切转向“软件工程”关注模块化、接口、测试和复用。理解了这一点后续的所有配置和代码才有了灵魂。2. 核心概念辨析Skill, Tool, Agent 与 MCP网络热词中出现了agent skills和mcp、skills和agent tools区别的讨论这里必须澄清几个关键概念避免混淆。概念定义与角色类比Agent (智能体)一个能够感知环境、做出决策并执行行动以实现目标的自治系统。它是“大脑”和“调度中心”。公司的CEO负责制定总体目标并协调各部门工作。Skill (技能)Agent所具备的、用于完成特定任务的一种能力或知识模块。它更偏向于“知道如何做某事”的逻辑封装。公司的部门如“市场部”知道如何做营销、“研发部”知道如何开发产品。一个Skill内部可能包含复杂的决策链。Tool (工具)Agent在执行任务时可以调用的一个具体操作或外部API。它是最小的可执行单元。部门员工手中的具体工具如市场部的“社交媒体发布平台”、研发部的“代码编辑器”。一个Skill可以通过调用多个Tools来实现其功能。MCP (Model Context Protocol)一个协议标准由Anthropic提出用于规范Tools如何以一种模型可理解的方式被暴露给AI模型如Claude。它定义了Tools的描述格式、调用方式和结果返回。公司内部的标准化工作流程和汇报格式。它规定了所有“工具”Tools必须以什么样的“说明书”呈现给“CEO”Agent以及如何接收指令和反馈结果。核心关系Agent 使用 Skills 来规划任务。Skill 内部可以封装复杂的逻辑并可能调用一个或多个 Tools 来完成具体操作。 |Tool 通过 MCP 协议被暴露给 Agent/Model使其能够被理解和调用。为什么强调Skills因为单纯的Tool调用是“原子性”的执行一个API而Skill是“分子性”的它代表了一个有意义的、可重复的任务单元例如“获取天气”是一个Tool“规划出差行程”就是一个需要调用天气、航班、酒店等多个Tools的Skill。3. 环境准备构建你的第一个Skill所需的一切我们的目标是构建一个具备真实技能的Agent。我们将以“网络信息研究员”Agent为例它拥有网络搜索和内容总结两个核心Skill。前置条件操作系统macOS / Linux / Windows (WSL2推荐)。Python版本3.10 或以上。这是大多数AI框架的稳定要求。包管理工具pip(Python自带) 或poetry(推荐用于项目管理)。Anthropic API密钥这是驱动Claude模型的核心。前往 Anthropic Console 注册并获取。搜索引擎API密钥可选为了演示Tool调用我们使用Serper Dev一个免费的Google搜索API。前往 Serper Dev 注册获取。项目初始化打开终端创建一个干净的项目目录并初始化虚拟环境这是管理Python依赖的最佳实践。# 1. 创建项目目录并进入 mkdir agent-skills-tutorial cd agent-skills-tutorial # 2. 创建虚拟环境以venv为例 python -m venv venv # 3. 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 创建关键项目文件 touch main.py skills.py tools.py config.py README.md requirements.txt安装核心依赖编辑requirements.txt文件加入以下内容anthropic0.25.0 langchain0.1.0 langchain-anthropic0.0.2 langchain-community0.0.10 requests2.31.0 python-dotenv1.0.0然后安装它们pip install -r requirements.txt配置环境变量创建.env文件来安全地存储你的API密钥永远不要将它们硬编码在代码中。# .env 文件内容 ANTHROPIC_API_KEYyour_anthropic_api_key_here SERPER_API_KEYyour_serper_api_key_here # 可选对应的config.py文件用于加载这些配置# config.py import os from dotenv import load_dotenv load_dotenv() # 从 .env 文件加载环境变量 ANTHROPIC_API_KEY os.getenv(ANTHROPIC_API_KEY) SERPER_API_KEY os.getenv(SERPER_API_KEY) if not ANTHROPIC_API_KEY: raise ValueError(请在 .env 文件中设置 ANTHROPIC_API_KEY) # SERPER_API_KEY 非必需仅当使用搜索Skill时需要4. 核心流程拆解构建Skill的四步法构建一个可用的Skill可以遵循以下四个清晰步骤我们以网络搜索Skill为例。4.1 第一步定义Tool具体的操作Tool是Skill的基石。我们先实现一个调用Serper API进行搜索的Tool。# tools.py import requests import json from typing import Dict, Any class SerperSearchTool: 一个调用Serper API进行谷歌搜索的Tool name serper_web_search description 使用Serper API在互联网上进行实时搜索。当用户需要获取最新的、不在模型知识库内的信息时使用此工具。 def __init__(self, api_key: str): self.api_key api_key self.url https://google.serper.dev/search self.headers { X-API-KEY: api_key, Content-Type: application/json } def _run(self, query: str) - Dict[str, Any]: 执行搜索的内部方法 payload json.dumps({q: query}) response requests.post(self.url, headersself.headers, datapayload) response.raise_for_status() # 如果请求失败则抛出异常 return response.json() def run(self, query: str) - str: 对外暴露的run方法。 参数: query (str): 搜索查询词 返回: str: 格式化的搜索结果摘要 try: results self._run(query) # 从结果中提取关键信息并格式化 organic_results results.get(organic, []) if not organic_results: return 未找到相关结果。 summary_parts [f关于 {query} 的搜索结果摘要] for i, item in enumerate(organic_results[:3]): # 取前3条 title item.get(title, 无标题) link item.get(link, #) snippet item.get(snippet, 无摘要) summary_parts.append(f{i1}. [{title}]({link})\n {snippet[:150]}...) return \n\n.join(summary_parts) except requests.exceptions.RequestException as e: return f搜索请求失败: {str(e)} except Exception as e: return f处理搜索结果时发生错误: {str(e)}关键点name和description至关重要AI模型Claude会读取它们来决定何时调用此Tool。description要清晰说明工具的用途和调用时机。run方法是Tool的入口其参数和返回值类型应尽可能简单通常是str。4.2 第二步封装Skill能力的逻辑单元Skill将Tool和必要的逻辑包装起来提供一个更高级的、目标明确的接口。# skills.py from tools import SerperSearchTool from config import SERPER_API_KEY from typing import Optional class WebSearchSkill: 网络搜索技能。 职责理解用户的信息需求将其转化为有效的搜索查询获取并初步整理网络信息。 def __init__(self): # 初始化所需的Tool if not SERPER_API_KEY: raise ValueError(SERPER_API_KEY未设置无法初始化WebSearchSkill。) self.search_tool SerperSearchTool(SERPER_API_KEY) property def name(self) - str: return web_search property def description(self) - str: return 当问题涉及实时信息、最新事件、特定数据或需要验证的事实时使用此技能进行网络搜索。 def execute(self, user_query: str, context: Optional[dict] None) - str: 执行搜索技能。 参数: user_query: 用户的原始问题 context: 可选的上下文信息如之前的对话历史 返回: str: 搜索得到的信息摘要 # 技能内部可以包含更复杂的逻辑比如优化查询词 # 这里我们做一个简单的查询优化示例 optimized_query self._optimize_query(user_query, context) print(f[WebSearchSkill] 正在搜索: {optimized_query}) # 调用Tool执行具体操作 search_result self.search_tool.run(optimized_query) # 可以对结果进行进一步的技能内部处理 processed_result self._post_process(search_result, user_query) return processed_result def _optimize_query(self, raw_query: str, context: Optional[dict]) - str: 一个简单的查询优化逻辑可扩展 # 例如如果上下文表明用户之前问过Python可以添加相关词 if context and python in context.get(last_topic, ).lower(): return f{raw_query} Python 编程 return raw_query def _post_process(self, raw_result: str, original_query: str) - str: 对Tool返回的原始结果进行后处理 # 这里可以添加过滤、重排序、去重等逻辑 # 目前只是简单包装 return f## 针对“{original_query}”的搜索结果\n{raw_result}\n\n---\n*注以上信息来自网络实时搜索请谨慎核实。*关键点Skill有明确的name和description用于在Agent层面进行技能路由。execute方法是Skill的主入口它接收任务和上下文。Skill内部可以包含业务逻辑如_optimize_query而不仅仅是简单转发Tool调用。4.3 第三步集成Agent大脑与调度Agent负责管理所有Skills理解用户意图并决定调用哪个或哪些Skill。# main.py (部分代码) from anthropic import Anthropic from skills import WebSearchSkill from config import ANTHROPIC_API_KEY import json class ResearchAgent: 一个具备网络搜索和总结技能的研究型Agent def __init__(self): self.client Anthropic(api_keyANTHROPIC_API_KEY) # 注册技能 self.skills { web_search: WebSearchSkill(), # 未来可以在这里添加更多技能如SummarySkill, CodeAnalysisSkill等 } self.conversation_history [] def _build_system_prompt(self) - str: 构建系统提示词定义Agent的角色、可用技能和行为规范 skills_desc \n.join([f- {skill.name}: {skill.description} for skill in self.skills.values()]) prompt f你是一个专业的研究助手擅长利用各种技能获取和整合信息。 你拥有以下技能 {skills_desc} 你的工作流程 1. 仔细分析用户的问题。 2. 判断是否需要以及需要调用哪个技能来回答问题。一次可以调用一个或多个技能。 3. 如果需要调用技能请在回复中明确指出你将使用哪个技能并生成调用该技能所需的参数例如搜索查询词。 4. 调用技能后你会收到技能返回的结果。你需要基于这些结果结合你自己的知识生成最终友好、全面、准确的回答。 注意对于事实性问题尤其是涉及最新事件、数据、具体技术细节时优先使用web_search技能进行核实。 return prompt def process_query(self, user_input: str) - str: 处理用户输入的主循环 self.conversation_history.append({role: user, content: user_input}) # 1. 让Claude分析意图并决定是否调用技能 system_prompt self._build_system_prompt() response self.client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用合适的Claude模型 max_tokens1000, systemsystem_prompt, messagesself.conversation_history ) assistant_reply response.content[0].text self.conversation_history.append({role: assistant, content: assistant_reply}) # 2. 一个简单的技能调用检测在实际项目中这里应该用更严谨的解析如Function Calling # 这里仅为演示假设Claude在回复中明确提到了“使用web_search技能搜索XXX” if 使用web_search技能搜索 in assistant_reply: # 提取搜索查询词这里用简单字符串分割生产环境应用正则或结构化输出 query_start assistant_reply.find(搜索) 3 search_query assistant_reply[query_start:].split(\n)[0].strip() print(f[Agent] 检测到技能调用指令查询词: {search_query}) # 3. 调用对应的Skill skill_result self.skills[web_search].execute(search_query, context{last_topic: user_input}) # 4. 将技能结果作为新的上下文让Claude生成最终回答 follow_up_prompt f用户最初的问题是{user_input}\n\n你刚才决定使用web_search技能并获得了以下结果\n\n{skill_result}\n\n请基于以上搜索结果为用户生成一个完整、准确的最终回答。 final_response self.client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1500, systemsystem_prompt, messagesself.conversation_history [{role: user, content: follow_up_prompt}] ) final_answer final_response.content[0].text self.conversation_history.append({role: assistant, content: final_answer}) return final_answer # 如果不需要调用技能直接返回Claude的回复 return assistant_reply4.4 第四步运行与迭代完成闭环创建一个简单的脚本来启动Agent并与它交互。# run_agent.py from main import ResearchAgent def main(): print(初始化研究型Agent...) agent ResearchAgent() print(Agent 就绪。输入您的问题输入 quit 退出) while True: try: user_input input(\n您: ) if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input.strip(): continue print(\nAgent 正在思考...) answer agent.process_query(user_input) print(f\n助手: {answer}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f\n处理请求时出错: {e}) if __name__ __main__: main()5. 完整示例构建一个多技能内容分析Agent让我们扩展上面的例子构建一个更实用的“内容分析Agent”。它除了能搜索还能对获取的文本内容进行总结和要点提取。第一步添加一个文本总结Skill# skills.py (新增内容) class SummarizationSkill: 文本总结技能。 职责对长文本进行摘要提取核心要点。 def __init__(self, llm_client): # 依赖一个LLM客户端来执行总结任务 self.llm_client llm_client property def name(self) - str: return text_summarize property def description(self) - str: return 当需要处理长文档、文章或报告并提取其核心内容、关键论点或摘要时使用此技能。 def execute(self, text: str, instruction: Optional[str] None) - str: 执行总结。 参数: text: 需要总结的长文本 instruction: 可选的总结指令如“用三点总结”、“专注于技术细节” 返回: str: 总结后的文本 if not text or len(text) 50: return 文本过短无需总结。原文 text[:100] prompt f请对以下文本进行摘要总结。要求总结准确、简洁抓住核心信息。 {f额外要求{instruction} if instruction else } 待总结文本 {text[:3000]} # 防止文本过长可截断 请直接输出总结内容 try: response self.llm_client.messages.create( modelclaude-3-haiku-20240307, # 使用更轻量、快速的模型进行总结 max_tokens500, messages[{role: user, content: prompt}] ) summary response.content[0].text return f## 文本总结\n{summary} except Exception as e: return f总结过程出错{str(e)}第二步更新Agent以支持多技能路由我们需要增强Agent的“大脑”使其能更好地理解和规划多技能任务。# main.py (更新部分) from skills import WebSearchSkill, SummarizationSkill from anthropic import Anthropic class ContentAnalysisAgent(ResearchAgent): 增强版Agent具备搜索和总结技能 def __init__(self): super().__init__() # 初始化基类包括Claude客户端 # 覆盖并扩展技能列表 self.skills { web_search: WebSearchSkill(), text_summarize: SummarizationSkill(self.client), # 传入LLM客户端 } # 更复杂的任务规划提示词 self.system_prompt self._build_enhanced_system_prompt() def _build_enhanced_system_prompt(self) - str: skills_desc \n.join([f- **{name}**: {skill.description} for name, skill in self.skills.items()]) return f你是一个强大的内容分析助手。你的核心能力是协调使用以下技能来解决问题 {skills_desc} **任务规划与执行流程** 1. **理解**彻底理解用户请求的最终目标。 2. **规划**将复杂目标分解为需要按顺序执行的技能步骤。 3. **执行**一次执行一个技能步骤并将上一步的结果作为下一步的输入或上下文。 4. **整合**将所有技能步骤的结果整合形成最终答案。 **技能组合示例** - 用户“帮我了解一下最近大语言模型在代码生成方面的最新进展并总结成一份简报。” - 步骤1: 使用web_search技能搜索“大语言模型 代码生成 最新进展 2024”。 - 步骤2: 使用text_summarize技能对搜索得到的关键文章或报告进行摘要。 - 步骤3: 将摘要整合生成一份结构化的简报。 请在回复中清晰说明你的**分步计划**然后按计划执行。 def process_complex_query(self, user_input: str) - str: 处理可能需要多步技能调用的复杂查询 print(f[用户] {user_input}) # 步骤1: 让Agent生成初始计划 plan_response self.client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens800, systemself.system_prompt, messages[{role: user, content: user_input}] ) plan plan_response.content[0].text print(f[Agent计划]\n{plan}) # 步骤2: 一个简化的执行器解析计划并调用技能 # 注意这是一个高度简化的演示。生产环境需要更强大的计划解析和执行引擎如LangGraph。 result_accumulator f**原始问题**: {user_input}\n\n**执行计划**:\n{plan}\n\n**执行结果**:\n # 演示如果计划中提到“搜索”则调用搜索技能 if 搜索 in plan and web_search in plan: # 这里需要从plan中提取查询词演示中我们简单使用用户输入 search_query user_input print(f[执行] 调用 web_search: {search_query}) search_result self.skills[web_search].execute(search_query) result_accumulator f\n### 步骤1: 网络搜索\n{search_result}\n # 假设搜索后需要总结 if 总结 in plan or 摘要 in plan: print(f[执行] 调用 text_summarize 处理搜索结果) # 这里我们总结搜索结果的摘要部分前1000字符 summary_input search_result[:1000] summary_result self.skills[text_summarize].execute(summary_input, 提取3-5个最关键的技术进展) result_accumulator f\n### 步骤2: 关键信息总结\n{summary_result}\n # 步骤3: 将收集到的所有结果交给Agent生成最终回答 final_prompt f{result_accumulator}\n\n基于以上执行过程中收集到的所有信息请生成对用户问题{user_input}的最终、完整的回答。 final_response self.client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1500, messages[{role: user, content: final_prompt}] ) final_answer final_response.content[0].text return final_answer第三步运行多技能Agent# run_complex_agent.py from main import ContentAnalysisAgent if __name__ __main__: agent ContentAnalysisAgent() question LangChain框架最近有什么重要的版本更新它的主要改进是什么 print(处理复杂查询示例...) answer agent.process_complex_query(question) print(\n *50) print(最终回答) print(*50) print(answer)6. 运行结果与效果验证运行run_complex_agent.py你会看到类似以下的输出流程具体内容因搜索实时结果而异处理复杂查询示例... [用户] LangChain框架最近有什么重要的版本更新它的主要改进是什么 [Agent计划] 我将通过以下步骤来回答这个问题 1. 首先使用web_search技能搜索“LangChain 框架 最新版本 更新 2024 主要改进”。 2. 然后使用text_summarize技能对搜索到的相关文章或发布说明进行摘要提取核心更新内容。 ... [执行] 调用 web_search: LangChain框架最近有什么重要的版本更新它的主要改进是什么 [WebSearchSkill] 正在搜索: LangChain框架最近有什么重要的版本更新它的主要改进是什么 [执行] 调用 text_summarize 处理搜索结果 最终回答 根据最新的网络信息LangChain 框架在近期2024年初发布了多个重要更新... **主要版本更新与改进包括** 1. **LangChain 0.1.0 版本发布**这是一个里程碑版本标志着API的稳定... 2. **LCELLangChain Expression Language的增强**提供了更声明式、更简洁的方式来构建链... 3. **对 Anthropic Claude 3 系列模型的深度集成**... 4. **改进的流式输出和调试工具**... ...如何验证你的Agent是否工作正常技能调用日志检查控制台是否打印了[WebSearchSkill] 正在搜索: ...和[执行] 调用 ...等日志。这证明Agent成功解析了计划并触发了技能。结果相关性最终回答是否直接引用了网络搜索得到的具体信息如版本号0.1.0、特性名LCEL而不是泛泛而谈。结构完整性回答是否遵循了“计划-执行-整合”的结构体现了多步骤协作的过程。错误处理尝试断开网络或输入无效的API密钥观察Agent是否给出了清晰的错误提示而不是崩溃。7. 常见问题与排查思路在构建和运行Agent Skills过程中你几乎一定会遇到以下问题。这里提供清晰的排查路径。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named anthropic依赖未安装或虚拟环境未激活。1. 运行pip list | grep anthropic。2. 检查终端提示符前是否有(venv)。1. 激活虚拟环境source venv/bin/activate。2. 安装依赖pip install -r requirements.txt。ValueError: 请在 .env 文件中设置 ANTHROPIC_API_KEY环境变量文件.env不存在或格式错误或API_KEY未设置。1. 检查项目根目录下是否存在.env文件。2. 检查.env文件内容是否为KEYvalue格式无空格和引号。1. 创建.env文件。2. 确保内容为ANTHROPIC_API_KEYsk-xxx。3. 重启终端或IDE。anthropic.APIConnectionError: ... failed to connect to api.anthropic.c...网络连接问题或API端点不可用。1. 运行ping api.anthropic.com。2. 检查系统代理设置。1. 确认网络通畅。2. 如果使用代理确保Python请求能通过代理设置HTTP_PROXY/HTTPS_PROXY环境变量。3. 等待片刻重试可能是Anthropic服务临时故障。Agent不调用Skill总是用自身知识回答系统提示词system_prompt未清晰定义技能调用规范或模型未理解。1. 打印并检查_build_system_prompt()的输出。2. 查看Claude的初始回复是否包含调用意图。1. 强化提示词明确要求“必须先调用技能”并给出具体格式示例。2. 使用Anthropic的工具使用Tool Use或结构化输出功能这是更可靠的调用方式见最佳实践部分。Skill被调用但结果未被用于最终回答Agent的“规划-执行-整合”循环逻辑有缺陷技能结果未正确传递回上下文。1. 在process_complex_query方法中打印result_accumulator变量。2. 检查传递给最终Claude调用的消息历史。1. 确保技能执行结果被添加到对话历史或最终提示词中。2. 使用更成熟的工作流引擎如LangGraph来管理状态和流程。搜索Skill返回“未找到相关结果”或错误Serper API密钥无效、额度用尽或查询词太模糊。1. 检查.env中的SERPER_API_KEY。2. 登录Serper Dev控制台查看额度。3. 直接在代码中调用search_tool.run(“test”)测试。1. 更换或充值API密钥。2. 在Skill的_optimize_query方法中优化查询词使其更具体。程序运行缓慢网络请求API调用是主要耗时操作尤其是顺序执行时。使用time模块记录每个技能和API调用的耗时。1. 对于无依赖的Skill考虑使用asyncio进行并发调用。2. 为Claude模型调用设置合理的max_tokens和timeout。8. 最佳实践与工程建议将Agent Skills从演示推进到生产环境需要遵循以下工程原则8.1 技能设计原则单一职责每个Skill只做好一件事。WebSearchSkill只负责搜索SummarizationSkill只负责总结。避免创建“瑞士军刀”式的巨型Skill。明确接口Skill的execute方法应有清晰、稳定的输入输出定义。使用类型注解如str,Dict,Optional提高可读性和可维护性。无状态与幂等尽可能设计无状态的Skill。相同的输入应产生相同的输出幂等这便于测试、缓存和重试。8.2 使用正式的Tool Calling/Function Calling我们之前的示例使用了“文本检测”这种不稳定的方式来触发技能。在生产中必须使用模型原生的工具调用能力。以Anthropic Claude的Tool Use为例# 1. 按照Anthropic格式定义Tools tools_for_claude [ { name: web_search, description: 在互联网上搜索最新信息。, input_schema: { type: object, properties: { query: {type: string, description: 搜索查询词} }, required: [query] } }, # ... 其他tool定义 ] # 2. 在调用Claude时传入tools参数 response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1000, toolstools_for_claude, # 关键在这里传入工具定义 messages[{role: user, content: LangChain的最新版本是什么}] ) # 3. 检查响应中是否有tool_use内容 if response.content and hasattr(response.content[0], tool_use): tool_call response.content[0].tool_use if tool_call.name web_search: # 4. 执行对应的Tool/Skill search_result search_skill.execute(tool_call.input[query]) # 5. 将结果以tool_result形式发送回Claude让其继续生成 next_response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1000, toolstools_for_claude, messages[ {role: user, content: LangChain的最新版本是什么}, response.content[0], # 包含tool_use的assistant消息 { role: user, content: [ { type: tool_result, tool_use_id: tool_call.id, content: search_result } ] } ] ) final_answer next_response.content[0].text这种方式由模型主动、结构化地发起工具调用远比字符串匹配可靠。8.3 技能编排与工作流管理对于复杂的多步骤任务手动管理状态和流程会变得非常混乱。建议引入工作流引擎LangGraphLangChain官方的工作流库非常适合构建有状态、可循环的Agent。自定义状态机对于简单流程可以自己设计一个状态机来跟踪任务进度。8.4 测试与监控单元测试Skill为每个Skill的execute方法编写测试模拟各种输入验证输出是否符合预期。集成测试Agent测试完整的“用户输入-技能调用-最终输出”流程。日志与追踪为每个技能调用、工具调用和模型调用记录详细的日志包括输入、输出、耗时和错误信息。这对于调试和优化至关重要。8.5 安全与成本控制输入验证与清理对所有来自外部的输入用户输入、API返回进行验证和清理防止注入攻击。权限控制不同的Skill可能对应不同权限级别的操作如读数据库、写文件、发邮件。在Agent层面实现权限检查。API成本监控为Anthropic、搜索API等设置用量告警和预算。在Skill中可以考虑对结果进行缓存避免重复查询。Agent Skills不是魔法而是一种工程范式。它的价值在于将AI应用的构建从“提示词艺术”转变为“软件工程”通过模块化、可测试、可复用的技能让我们能够构建更复杂、更可靠、更易维护的智能系统。本文带你从概念辨析到环境搭建从单一技能实现到多技能协作并提供了生产级的最佳实践。下一步你可以尝试实现更多实用技能如CodeInterpreterSkill代码执行、DatabaseQuerySkill数据库查询、FileOperationSkill文件读写。集成更强大的工作流引擎使用LangGraph重构你的多技能Agent实现更复杂的循环、分支和并行逻辑。构建技能市场/仓库将你的技能标准化、打包使其可以被团队或其他项目轻松导入和使用。深入探索MCPModel Context Protocol这是Anthropic推动的Tool标准化协议能让你的Skills更容易被不同的模型和平台使用。真正的天花板不在于理解概念而在于将这些工程化的思想应用到实际项目中解决真实世界的问题。建议收藏本文在构建你的第一个生产级Agent时反复对照检查和实践。 AI Agent技能化开发：从提示词工程到组件化架构的实践指南
最近在AI圈子里吴恩达教授关于“Agent Skills”的课程讨论度很高很多开发者都在问这到底是又一个被过度包装的概念还是真的能改变我们构建AI应用的方式我的判断是“Agent Skills”的核心价值在于它提供了一套标准化的、可复用的“技能”构建范式将AI Agent的开发从“手工作坊”模式推进到了“组件化”工程阶段。它解决的不是“能不能”让AI执行任务的问题而是“如何高效、稳定、规模化”地让AI执行复杂任务的问题。如果你还在用“提示词工程”的老办法让一个AI模型去处理从数据查询、代码生成到结果验证的全流程很快就会遇到瓶颈提示词臃肿、逻辑混乱、错误难以定位、功能无法复用。而“Agent Skills”的思路是把一个复杂的Agent拆解成多个专注、可测试、可组合的“技能”Skills。这就像从写一个几千行的“上帝类”函数转向设计一个由多个单一职责的类组成的清晰架构。本文将基于这一核心判断为你拆解“Agent Skills”的核心思想、与Anthropic Claude模型的结合实践以及一套从零搭建可运行技能链的保姆级教程。你将不仅理解概念更能亲手搭建一个具备“思考-行动-观察”循环的实用Agent。1. Agent Skills 要解决的真正问题从“提示词魔术”到“软件工程”在深入代码之前我们必须先厘清一个根本问题为什么需要“Skills”想象一个场景你需要一个Agent帮你分析GitHub仓库的活跃度。传统“单体提示词”方式可能是“你是一个代码分析专家请访问仓库https://github.com/xxx/yyy获取最近一个月的提交数、贡献者列表和主要Issue然后生成一份报告。”这个提示词至少隐含了四个独立子任务解析指令理解用户要分析哪个仓库。获取数据调用GitHub API或爬虫获取原始数据。处理与分析对获取的提交、贡献者等数据进行统计和解读。组织与报告将分析结果格式化成一份易读的报告。当任何一个环节出错如API限流、数据格式变化、分析逻辑有误整个流程都会失败并且很难定位问题所在。更糟糕的是如果你想做一个“分析GitLab仓库”的Agent大部分逻辑要重写。Agent Skills 范式带来的转变是解耦将上述四个子任务定义为四个独立的Skill。复用数据获取Skill稍作修改就能同时服务于GitHub和GitLab分析。测试每个Skill可以单独进行单元测试。组合你可以像搭积木一样将解析Skill、GitHub数据Skill、分析Skill、报告Skill组合成一个工作流。维护当GitHub API升级时你只需要修改GitHub数据Skill而不会影响分析和报告的逻辑。这就是从“提示词魔术”靠一个复杂的、难以调试的提示词驱动一切转向“软件工程”关注模块化、接口、测试和复用。理解了这一点后续的所有配置和代码才有了灵魂。2. 核心概念辨析Skill, Tool, Agent 与 MCP网络热词中出现了agent skills和mcp、skills和agent tools区别的讨论这里必须澄清几个关键概念避免混淆。概念定义与角色类比Agent (智能体)一个能够感知环境、做出决策并执行行动以实现目标的自治系统。它是“大脑”和“调度中心”。公司的CEO负责制定总体目标并协调各部门工作。Skill (技能)Agent所具备的、用于完成特定任务的一种能力或知识模块。它更偏向于“知道如何做某事”的逻辑封装。公司的部门如“市场部”知道如何做营销、“研发部”知道如何开发产品。一个Skill内部可能包含复杂的决策链。Tool (工具)Agent在执行任务时可以调用的一个具体操作或外部API。它是最小的可执行单元。部门员工手中的具体工具如市场部的“社交媒体发布平台”、研发部的“代码编辑器”。一个Skill可以通过调用多个Tools来实现其功能。MCP (Model Context Protocol)一个协议标准由Anthropic提出用于规范Tools如何以一种模型可理解的方式被暴露给AI模型如Claude。它定义了Tools的描述格式、调用方式和结果返回。公司内部的标准化工作流程和汇报格式。它规定了所有“工具”Tools必须以什么样的“说明书”呈现给“CEO”Agent以及如何接收指令和反馈结果。核心关系Agent 使用 Skills 来规划任务。Skill 内部可以封装复杂的逻辑并可能调用一个或多个 Tools 来完成具体操作。 |Tool 通过 MCP 协议被暴露给 Agent/Model使其能够被理解和调用。为什么强调Skills因为单纯的Tool调用是“原子性”的执行一个API而Skill是“分子性”的它代表了一个有意义的、可重复的任务单元例如“获取天气”是一个Tool“规划出差行程”就是一个需要调用天气、航班、酒店等多个Tools的Skill。3. 环境准备构建你的第一个Skill所需的一切我们的目标是构建一个具备真实技能的Agent。我们将以“网络信息研究员”Agent为例它拥有网络搜索和内容总结两个核心Skill。前置条件操作系统macOS / Linux / Windows (WSL2推荐)。Python版本3.10 或以上。这是大多数AI框架的稳定要求。包管理工具pip(Python自带) 或poetry(推荐用于项目管理)。Anthropic API密钥这是驱动Claude模型的核心。前往 Anthropic Console 注册并获取。搜索引擎API密钥可选为了演示Tool调用我们使用Serper Dev一个免费的Google搜索API。前往 Serper Dev 注册获取。项目初始化打开终端创建一个干净的项目目录并初始化虚拟环境这是管理Python依赖的最佳实践。# 1. 创建项目目录并进入 mkdir agent-skills-tutorial cd agent-skills-tutorial # 2. 创建虚拟环境以venv为例 python -m venv venv # 3. 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 创建关键项目文件 touch main.py skills.py tools.py config.py README.md requirements.txt安装核心依赖编辑requirements.txt文件加入以下内容anthropic0.25.0 langchain0.1.0 langchain-anthropic0.0.2 langchain-community0.0.10 requests2.31.0 python-dotenv1.0.0然后安装它们pip install -r requirements.txt配置环境变量创建.env文件来安全地存储你的API密钥永远不要将它们硬编码在代码中。# .env 文件内容 ANTHROPIC_API_KEYyour_anthropic_api_key_here SERPER_API_KEYyour_serper_api_key_here # 可选对应的config.py文件用于加载这些配置# config.py import os from dotenv import load_dotenv load_dotenv() # 从 .env 文件加载环境变量 ANTHROPIC_API_KEY os.getenv(ANTHROPIC_API_KEY) SERPER_API_KEY os.getenv(SERPER_API_KEY) if not ANTHROPIC_API_KEY: raise ValueError(请在 .env 文件中设置 ANTHROPIC_API_KEY) # SERPER_API_KEY 非必需仅当使用搜索Skill时需要4. 核心流程拆解构建Skill的四步法构建一个可用的Skill可以遵循以下四个清晰步骤我们以网络搜索Skill为例。4.1 第一步定义Tool具体的操作Tool是Skill的基石。我们先实现一个调用Serper API进行搜索的Tool。# tools.py import requests import json from typing import Dict, Any class SerperSearchTool: 一个调用Serper API进行谷歌搜索的Tool name serper_web_search description 使用Serper API在互联网上进行实时搜索。当用户需要获取最新的、不在模型知识库内的信息时使用此工具。 def __init__(self, api_key: str): self.api_key api_key self.url https://google.serper.dev/search self.headers { X-API-KEY: api_key, Content-Type: application/json } def _run(self, query: str) - Dict[str, Any]: 执行搜索的内部方法 payload json.dumps({q: query}) response requests.post(self.url, headersself.headers, datapayload) response.raise_for_status() # 如果请求失败则抛出异常 return response.json() def run(self, query: str) - str: 对外暴露的run方法。 参数: query (str): 搜索查询词 返回: str: 格式化的搜索结果摘要 try: results self._run(query) # 从结果中提取关键信息并格式化 organic_results results.get(organic, []) if not organic_results: return 未找到相关结果。 summary_parts [f关于 {query} 的搜索结果摘要] for i, item in enumerate(organic_results[:3]): # 取前3条 title item.get(title, 无标题) link item.get(link, #) snippet item.get(snippet, 无摘要) summary_parts.append(f{i1}. [{title}]({link})\n {snippet[:150]}...) return \n\n.join(summary_parts) except requests.exceptions.RequestException as e: return f搜索请求失败: {str(e)} except Exception as e: return f处理搜索结果时发生错误: {str(e)}关键点name和description至关重要AI模型Claude会读取它们来决定何时调用此Tool。description要清晰说明工具的用途和调用时机。run方法是Tool的入口其参数和返回值类型应尽可能简单通常是str。4.2 第二步封装Skill能力的逻辑单元Skill将Tool和必要的逻辑包装起来提供一个更高级的、目标明确的接口。# skills.py from tools import SerperSearchTool from config import SERPER_API_KEY from typing import Optional class WebSearchSkill: 网络搜索技能。 职责理解用户的信息需求将其转化为有效的搜索查询获取并初步整理网络信息。 def __init__(self): # 初始化所需的Tool if not SERPER_API_KEY: raise ValueError(SERPER_API_KEY未设置无法初始化WebSearchSkill。) self.search_tool SerperSearchTool(SERPER_API_KEY) property def name(self) - str: return web_search property def description(self) - str: return 当问题涉及实时信息、最新事件、特定数据或需要验证的事实时使用此技能进行网络搜索。 def execute(self, user_query: str, context: Optional[dict] None) - str: 执行搜索技能。 参数: user_query: 用户的原始问题 context: 可选的上下文信息如之前的对话历史 返回: str: 搜索得到的信息摘要 # 技能内部可以包含更复杂的逻辑比如优化查询词 # 这里我们做一个简单的查询优化示例 optimized_query self._optimize_query(user_query, context) print(f[WebSearchSkill] 正在搜索: {optimized_query}) # 调用Tool执行具体操作 search_result self.search_tool.run(optimized_query) # 可以对结果进行进一步的技能内部处理 processed_result self._post_process(search_result, user_query) return processed_result def _optimize_query(self, raw_query: str, context: Optional[dict]) - str: 一个简单的查询优化逻辑可扩展 # 例如如果上下文表明用户之前问过Python可以添加相关词 if context and python in context.get(last_topic, ).lower(): return f{raw_query} Python 编程 return raw_query def _post_process(self, raw_result: str, original_query: str) - str: 对Tool返回的原始结果进行后处理 # 这里可以添加过滤、重排序、去重等逻辑 # 目前只是简单包装 return f## 针对“{original_query}”的搜索结果\n{raw_result}\n\n---\n*注以上信息来自网络实时搜索请谨慎核实。*关键点Skill有明确的name和description用于在Agent层面进行技能路由。execute方法是Skill的主入口它接收任务和上下文。Skill内部可以包含业务逻辑如_optimize_query而不仅仅是简单转发Tool调用。4.3 第三步集成Agent大脑与调度Agent负责管理所有Skills理解用户意图并决定调用哪个或哪些Skill。# main.py (部分代码) from anthropic import Anthropic from skills import WebSearchSkill from config import ANTHROPIC_API_KEY import json class ResearchAgent: 一个具备网络搜索和总结技能的研究型Agent def __init__(self): self.client Anthropic(api_keyANTHROPIC_API_KEY) # 注册技能 self.skills { web_search: WebSearchSkill(), # 未来可以在这里添加更多技能如SummarySkill, CodeAnalysisSkill等 } self.conversation_history [] def _build_system_prompt(self) - str: 构建系统提示词定义Agent的角色、可用技能和行为规范 skills_desc \n.join([f- {skill.name}: {skill.description} for skill in self.skills.values()]) prompt f你是一个专业的研究助手擅长利用各种技能获取和整合信息。 你拥有以下技能 {skills_desc} 你的工作流程 1. 仔细分析用户的问题。 2. 判断是否需要以及需要调用哪个技能来回答问题。一次可以调用一个或多个技能。 3. 如果需要调用技能请在回复中明确指出你将使用哪个技能并生成调用该技能所需的参数例如搜索查询词。 4. 调用技能后你会收到技能返回的结果。你需要基于这些结果结合你自己的知识生成最终友好、全面、准确的回答。 注意对于事实性问题尤其是涉及最新事件、数据、具体技术细节时优先使用web_search技能进行核实。 return prompt def process_query(self, user_input: str) - str: 处理用户输入的主循环 self.conversation_history.append({role: user, content: user_input}) # 1. 让Claude分析意图并决定是否调用技能 system_prompt self._build_system_prompt() response self.client.messages.create( modelclaude-3-5-sonnet-20241022, # 使用合适的Claude模型 max_tokens1000, systemsystem_prompt, messagesself.conversation_history ) assistant_reply response.content[0].text self.conversation_history.append({role: assistant, content: assistant_reply}) # 2. 一个简单的技能调用检测在实际项目中这里应该用更严谨的解析如Function Calling # 这里仅为演示假设Claude在回复中明确提到了“使用web_search技能搜索XXX” if 使用web_search技能搜索 in assistant_reply: # 提取搜索查询词这里用简单字符串分割生产环境应用正则或结构化输出 query_start assistant_reply.find(搜索) 3 search_query assistant_reply[query_start:].split(\n)[0].strip() print(f[Agent] 检测到技能调用指令查询词: {search_query}) # 3. 调用对应的Skill skill_result self.skills[web_search].execute(search_query, context{last_topic: user_input}) # 4. 将技能结果作为新的上下文让Claude生成最终回答 follow_up_prompt f用户最初的问题是{user_input}\n\n你刚才决定使用web_search技能并获得了以下结果\n\n{skill_result}\n\n请基于以上搜索结果为用户生成一个完整、准确的最终回答。 final_response self.client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1500, systemsystem_prompt, messagesself.conversation_history [{role: user, content: follow_up_prompt}] ) final_answer final_response.content[0].text self.conversation_history.append({role: assistant, content: final_answer}) return final_answer # 如果不需要调用技能直接返回Claude的回复 return assistant_reply4.4 第四步运行与迭代完成闭环创建一个简单的脚本来启动Agent并与它交互。# run_agent.py from main import ResearchAgent def main(): print(初始化研究型Agent...) agent ResearchAgent() print(Agent 就绪。输入您的问题输入 quit 退出) while True: try: user_input input(\n您: ) if user_input.lower() in [quit, exit, q]: print(再见) break if not user_input.strip(): continue print(\nAgent 正在思考...) answer agent.process_query(user_input) print(f\n助手: {answer}) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f\n处理请求时出错: {e}) if __name__ __main__: main()5. 完整示例构建一个多技能内容分析Agent让我们扩展上面的例子构建一个更实用的“内容分析Agent”。它除了能搜索还能对获取的文本内容进行总结和要点提取。第一步添加一个文本总结Skill# skills.py (新增内容) class SummarizationSkill: 文本总结技能。 职责对长文本进行摘要提取核心要点。 def __init__(self, llm_client): # 依赖一个LLM客户端来执行总结任务 self.llm_client llm_client property def name(self) - str: return text_summarize property def description(self) - str: return 当需要处理长文档、文章或报告并提取其核心内容、关键论点或摘要时使用此技能。 def execute(self, text: str, instruction: Optional[str] None) - str: 执行总结。 参数: text: 需要总结的长文本 instruction: 可选的总结指令如“用三点总结”、“专注于技术细节” 返回: str: 总结后的文本 if not text or len(text) 50: return 文本过短无需总结。原文 text[:100] prompt f请对以下文本进行摘要总结。要求总结准确、简洁抓住核心信息。 {f额外要求{instruction} if instruction else } 待总结文本 {text[:3000]} # 防止文本过长可截断 请直接输出总结内容 try: response self.llm_client.messages.create( modelclaude-3-haiku-20240307, # 使用更轻量、快速的模型进行总结 max_tokens500, messages[{role: user, content: prompt}] ) summary response.content[0].text return f## 文本总结\n{summary} except Exception as e: return f总结过程出错{str(e)}第二步更新Agent以支持多技能路由我们需要增强Agent的“大脑”使其能更好地理解和规划多技能任务。# main.py (更新部分) from skills import WebSearchSkill, SummarizationSkill from anthropic import Anthropic class ContentAnalysisAgent(ResearchAgent): 增强版Agent具备搜索和总结技能 def __init__(self): super().__init__() # 初始化基类包括Claude客户端 # 覆盖并扩展技能列表 self.skills { web_search: WebSearchSkill(), text_summarize: SummarizationSkill(self.client), # 传入LLM客户端 } # 更复杂的任务规划提示词 self.system_prompt self._build_enhanced_system_prompt() def _build_enhanced_system_prompt(self) - str: skills_desc \n.join([f- **{name}**: {skill.description} for name, skill in self.skills.items()]) return f你是一个强大的内容分析助手。你的核心能力是协调使用以下技能来解决问题 {skills_desc} **任务规划与执行流程** 1. **理解**彻底理解用户请求的最终目标。 2. **规划**将复杂目标分解为需要按顺序执行的技能步骤。 3. **执行**一次执行一个技能步骤并将上一步的结果作为下一步的输入或上下文。 4. **整合**将所有技能步骤的结果整合形成最终答案。 **技能组合示例** - 用户“帮我了解一下最近大语言模型在代码生成方面的最新进展并总结成一份简报。” - 步骤1: 使用web_search技能搜索“大语言模型 代码生成 最新进展 2024”。 - 步骤2: 使用text_summarize技能对搜索得到的关键文章或报告进行摘要。 - 步骤3: 将摘要整合生成一份结构化的简报。 请在回复中清晰说明你的**分步计划**然后按计划执行。 def process_complex_query(self, user_input: str) - str: 处理可能需要多步技能调用的复杂查询 print(f[用户] {user_input}) # 步骤1: 让Agent生成初始计划 plan_response self.client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens800, systemself.system_prompt, messages[{role: user, content: user_input}] ) plan plan_response.content[0].text print(f[Agent计划]\n{plan}) # 步骤2: 一个简化的执行器解析计划并调用技能 # 注意这是一个高度简化的演示。生产环境需要更强大的计划解析和执行引擎如LangGraph。 result_accumulator f**原始问题**: {user_input}\n\n**执行计划**:\n{plan}\n\n**执行结果**:\n # 演示如果计划中提到“搜索”则调用搜索技能 if 搜索 in plan and web_search in plan: # 这里需要从plan中提取查询词演示中我们简单使用用户输入 search_query user_input print(f[执行] 调用 web_search: {search_query}) search_result self.skills[web_search].execute(search_query) result_accumulator f\n### 步骤1: 网络搜索\n{search_result}\n # 假设搜索后需要总结 if 总结 in plan or 摘要 in plan: print(f[执行] 调用 text_summarize 处理搜索结果) # 这里我们总结搜索结果的摘要部分前1000字符 summary_input search_result[:1000] summary_result self.skills[text_summarize].execute(summary_input, 提取3-5个最关键的技术进展) result_accumulator f\n### 步骤2: 关键信息总结\n{summary_result}\n # 步骤3: 将收集到的所有结果交给Agent生成最终回答 final_prompt f{result_accumulator}\n\n基于以上执行过程中收集到的所有信息请生成对用户问题{user_input}的最终、完整的回答。 final_response self.client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1500, messages[{role: user, content: final_prompt}] ) final_answer final_response.content[0].text return final_answer第三步运行多技能Agent# run_complex_agent.py from main import ContentAnalysisAgent if __name__ __main__: agent ContentAnalysisAgent() question LangChain框架最近有什么重要的版本更新它的主要改进是什么 print(处理复杂查询示例...) answer agent.process_complex_query(question) print(\n *50) print(最终回答) print(*50) print(answer)6. 运行结果与效果验证运行run_complex_agent.py你会看到类似以下的输出流程具体内容因搜索实时结果而异处理复杂查询示例... [用户] LangChain框架最近有什么重要的版本更新它的主要改进是什么 [Agent计划] 我将通过以下步骤来回答这个问题 1. 首先使用web_search技能搜索“LangChain 框架 最新版本 更新 2024 主要改进”。 2. 然后使用text_summarize技能对搜索到的相关文章或发布说明进行摘要提取核心更新内容。 ... [执行] 调用 web_search: LangChain框架最近有什么重要的版本更新它的主要改进是什么 [WebSearchSkill] 正在搜索: LangChain框架最近有什么重要的版本更新它的主要改进是什么 [执行] 调用 text_summarize 处理搜索结果 最终回答 根据最新的网络信息LangChain 框架在近期2024年初发布了多个重要更新... **主要版本更新与改进包括** 1. **LangChain 0.1.0 版本发布**这是一个里程碑版本标志着API的稳定... 2. **LCELLangChain Expression Language的增强**提供了更声明式、更简洁的方式来构建链... 3. **对 Anthropic Claude 3 系列模型的深度集成**... 4. **改进的流式输出和调试工具**... ...如何验证你的Agent是否工作正常技能调用日志检查控制台是否打印了[WebSearchSkill] 正在搜索: ...和[执行] 调用 ...等日志。这证明Agent成功解析了计划并触发了技能。结果相关性最终回答是否直接引用了网络搜索得到的具体信息如版本号0.1.0、特性名LCEL而不是泛泛而谈。结构完整性回答是否遵循了“计划-执行-整合”的结构体现了多步骤协作的过程。错误处理尝试断开网络或输入无效的API密钥观察Agent是否给出了清晰的错误提示而不是崩溃。7. 常见问题与排查思路在构建和运行Agent Skills过程中你几乎一定会遇到以下问题。这里提供清晰的排查路径。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named anthropic依赖未安装或虚拟环境未激活。1. 运行pip list | grep anthropic。2. 检查终端提示符前是否有(venv)。1. 激活虚拟环境source venv/bin/activate。2. 安装依赖pip install -r requirements.txt。ValueError: 请在 .env 文件中设置 ANTHROPIC_API_KEY环境变量文件.env不存在或格式错误或API_KEY未设置。1. 检查项目根目录下是否存在.env文件。2. 检查.env文件内容是否为KEYvalue格式无空格和引号。1. 创建.env文件。2. 确保内容为ANTHROPIC_API_KEYsk-xxx。3. 重启终端或IDE。anthropic.APIConnectionError: ... failed to connect to api.anthropic.c...网络连接问题或API端点不可用。1. 运行ping api.anthropic.com。2. 检查系统代理设置。1. 确认网络通畅。2. 如果使用代理确保Python请求能通过代理设置HTTP_PROXY/HTTPS_PROXY环境变量。3. 等待片刻重试可能是Anthropic服务临时故障。Agent不调用Skill总是用自身知识回答系统提示词system_prompt未清晰定义技能调用规范或模型未理解。1. 打印并检查_build_system_prompt()的输出。2. 查看Claude的初始回复是否包含调用意图。1. 强化提示词明确要求“必须先调用技能”并给出具体格式示例。2. 使用Anthropic的工具使用Tool Use或结构化输出功能这是更可靠的调用方式见最佳实践部分。Skill被调用但结果未被用于最终回答Agent的“规划-执行-整合”循环逻辑有缺陷技能结果未正确传递回上下文。1. 在process_complex_query方法中打印result_accumulator变量。2. 检查传递给最终Claude调用的消息历史。1. 确保技能执行结果被添加到对话历史或最终提示词中。2. 使用更成熟的工作流引擎如LangGraph来管理状态和流程。搜索Skill返回“未找到相关结果”或错误Serper API密钥无效、额度用尽或查询词太模糊。1. 检查.env中的SERPER_API_KEY。2. 登录Serper Dev控制台查看额度。3. 直接在代码中调用search_tool.run(“test”)测试。1. 更换或充值API密钥。2. 在Skill的_optimize_query方法中优化查询词使其更具体。程序运行缓慢网络请求API调用是主要耗时操作尤其是顺序执行时。使用time模块记录每个技能和API调用的耗时。1. 对于无依赖的Skill考虑使用asyncio进行并发调用。2. 为Claude模型调用设置合理的max_tokens和timeout。8. 最佳实践与工程建议将Agent Skills从演示推进到生产环境需要遵循以下工程原则8.1 技能设计原则单一职责每个Skill只做好一件事。WebSearchSkill只负责搜索SummarizationSkill只负责总结。避免创建“瑞士军刀”式的巨型Skill。明确接口Skill的execute方法应有清晰、稳定的输入输出定义。使用类型注解如str,Dict,Optional提高可读性和可维护性。无状态与幂等尽可能设计无状态的Skill。相同的输入应产生相同的输出幂等这便于测试、缓存和重试。8.2 使用正式的Tool Calling/Function Calling我们之前的示例使用了“文本检测”这种不稳定的方式来触发技能。在生产中必须使用模型原生的工具调用能力。以Anthropic Claude的Tool Use为例# 1. 按照Anthropic格式定义Tools tools_for_claude [ { name: web_search, description: 在互联网上搜索最新信息。, input_schema: { type: object, properties: { query: {type: string, description: 搜索查询词} }, required: [query] } }, # ... 其他tool定义 ] # 2. 在调用Claude时传入tools参数 response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1000, toolstools_for_claude, # 关键在这里传入工具定义 messages[{role: user, content: LangChain的最新版本是什么}] ) # 3. 检查响应中是否有tool_use内容 if response.content and hasattr(response.content[0], tool_use): tool_call response.content[0].tool_use if tool_call.name web_search: # 4. 执行对应的Tool/Skill search_result search_skill.execute(tool_call.input[query]) # 5. 将结果以tool_result形式发送回Claude让其继续生成 next_response client.messages.create( modelclaude-3-5-sonnet-20241022, max_tokens1000, toolstools_for_claude, messages[ {role: user, content: LangChain的最新版本是什么}, response.content[0], # 包含tool_use的assistant消息 { role: user, content: [ { type: tool_result, tool_use_id: tool_call.id, content: search_result } ] } ] ) final_answer next_response.content[0].text这种方式由模型主动、结构化地发起工具调用远比字符串匹配可靠。8.3 技能编排与工作流管理对于复杂的多步骤任务手动管理状态和流程会变得非常混乱。建议引入工作流引擎LangGraphLangChain官方的工作流库非常适合构建有状态、可循环的Agent。自定义状态机对于简单流程可以自己设计一个状态机来跟踪任务进度。8.4 测试与监控单元测试Skill为每个Skill的execute方法编写测试模拟各种输入验证输出是否符合预期。集成测试Agent测试完整的“用户输入-技能调用-最终输出”流程。日志与追踪为每个技能调用、工具调用和模型调用记录详细的日志包括输入、输出、耗时和错误信息。这对于调试和优化至关重要。8.5 安全与成本控制输入验证与清理对所有来自外部的输入用户输入、API返回进行验证和清理防止注入攻击。权限控制不同的Skill可能对应不同权限级别的操作如读数据库、写文件、发邮件。在Agent层面实现权限检查。API成本监控为Anthropic、搜索API等设置用量告警和预算。在Skill中可以考虑对结果进行缓存避免重复查询。Agent Skills不是魔法而是一种工程范式。它的价值在于将AI应用的构建从“提示词艺术”转变为“软件工程”通过模块化、可测试、可复用的技能让我们能够构建更复杂、更可靠、更易维护的智能系统。本文带你从概念辨析到环境搭建从单一技能实现到多技能协作并提供了生产级的最佳实践。下一步你可以尝试实现更多实用技能如CodeInterpreterSkill代码执行、DatabaseQuerySkill数据库查询、FileOperationSkill文件读写。集成更强大的工作流引擎使用LangGraph重构你的多技能Agent实现更复杂的循环、分支和并行逻辑。构建技能市场/仓库将你的技能标准化、打包使其可以被团队或其他项目轻松导入和使用。深入探索MCPModel Context Protocol这是Anthropic推动的Tool标准化协议能让你的Skills更容易被不同的模型和平台使用。真正的天花板不在于理解概念而在于将这些工程化的思想应用到实际项目中解决真实世界的问题。建议收藏本文在构建你的第一个生产级Agent时反复对照检查和实践。