這次我們來看一個關于Agent Skills的技術主題。Agent Skills智能體技能是當前AI Agent智能體開發(fā)中的核心概念它直接決定了智能體能做什么、做得好不好。網上教程很多但要么太理論要么太零散很難直接上手應用到實際項目中。這篇文章不講虛的直接聚焦于Agent Skills 的實戰(zhàn)落地。我們會拆解清楚 Agent Skills 到底是什么它和 MCPModel Context Protocol、Agent Tools 等熱門概念的區(qū)別以及如何從零開始一步步構建、測試并集成一個可用的技能。無論你是想快速入門還是需要為企業(yè)級應用設計技能體系這里都有可以直接復用的思路和代碼。本文會重點解決幾個核心問題Agent Skills 的準確定義與邊界是什么如何設計一個高可用的技能如何通過代碼實現技能的注冊、調用與管理如何將技能集成到現有的 Agent 框架中以及在實戰(zhàn)中如何避免常見的性能與設計陷阱。1. 核心能力速覽在深入細節(jié)之前我們先通過一個表格快速了解 Agent Skills 的核心特性和本文的覆蓋范圍。能力項說明核心定位定義 AI Agent 可執(zhí)行的具體原子操作或復雜流程是 Agent 能力的具象化單元。與 MCP 區(qū)別MCP 是模型與工具/數據源之間的通信協(xié)議用于安全、標準化地擴展模型上下文。Agent Skills 是建立在協(xié)議或直接調用之上的功能實現。一個 MCP 服務器可以提供多個 Skills 所需的數據或接口。與 Agent Tools 區(qū)別在多數框架中Tools和Skills概念?；煊谩５毜膮^(qū)分是Tools偏向于單一、基礎的函數如搜索、計算而Skills可能是由多個Tools和邏輯組成的、具有明確業(yè)務目標的復合能力如“生成季度報告”、“排查系統(tǒng)故障”。開發(fā)門檻主要依賴 Python。對基礎編程和 API 調用有要求但無需深入的機器學習知識。運行環(huán)境可在本地開發(fā)環(huán)境Python、云服務器或容器化Docker環(huán)境中運行。通常作為后端服務集成到 Agent 框架。核心產出可被 Agent 理解、規(guī)劃和調用的技能函數通常包含清晰的名稱、描述、參數 schema 和執(zhí)行邏輯。適合場景1. 為 AutoGPT、LangChain、CrewAI 等框架擴展自定義能力。2. 構建企業(yè)內部的自動化業(yè)務流程如數據分析、報告生成、系統(tǒng)巡檢。3. 開發(fā)面向垂直領域的專業(yè)智能助手。2. Agent Skills 究竟是什么與 MCP、Tools 的深度辨析理解一個概念最好的方式是劃清它的邊界。當前社區(qū)對 Agent Skills、MCP、Agent Tools 的討論很多容易混淆。Agent Skills智能體技能的本質是“能力包”。它描述了一個智能體可以完成的一項具體任務。這個任務可以很簡單比如“獲取當前天氣”也可以很復雜比如“分析 GitHub 倉庫活躍度并生成報告”后者可能內部調用了多個數據查詢、處理和格式化的步驟。技能的核心在于提供一個標準化的接口讓 Agent 的“大腦”通常是 LLM能夠理解、規(guī)劃并調用它。MCPModel Context Protocol的本質是“安全通道”。它是由 Anthropic 提出的一種協(xié)議旨在解決大模型如何安全、可控地訪問外部工具、數據和計算資源的問題。你可以把它想象成一套標準的“插頭和插座”規(guī)范。一個 MCP 服務器如連接數據庫、JIRA、內部知識庫的服務器通過實現這套協(xié)議就能讓兼容 MCP 的客戶端如 Claude Desktop、某些 Agent 框架安全地調用其能力。Skills 可以利用 MCP 協(xié)議來獲取數據或執(zhí)行操作但 Skills 本身不等于 MCP。MCP 更側重于連接和協(xié)議而 Skills 更側重于功能邏輯。Agent Tools智能體工具在 LangChain、AutoGPT 等早期框架中廣泛使用其概念與 Skills 高度重疊。在許多上下文中它們可以互換。但如果細究可以這樣區(qū)分Tool工具更像一個“螺絲刀”或“扳手”是單一、通用的功能。例如search_web,calculate,read_file。它的輸入輸出通常很簡單。Skill技能更像“組裝一臺電腦”或“更換汽車輪胎”是一個有明確目標的復合流程可能涉及按順序或條件調用多個 Tools并包含更多的業(yè)務邏輯和錯誤處理。例如generate_weekly_report這個技能內部可能調用了query_database、analyze_data、format_to_ppt等多個工具。對于開發(fā)者而言不必過于糾結名詞。關鍵是理解你需要為你 Agent 定義一系列可調用的函數這些函數有清晰的描述和參數這就是你給 Agent 裝備的“技能”或“工具”。本文后續(xù)將統(tǒng)一使用“Skill”來指代。3. 環(huán)境準備與前置條件開始構建 Skill 之前需要準備好開發(fā)和運行環(huán)境。以下是一個通用且推薦的環(huán)境配置。1. 基礎軟件操作系統(tǒng)Windows 10/11 macOS 或 Linux如 Ubuntu 20.04。本文示例以 Linux/macOS 命令為主Windows 用戶可使用 WSL2 或相應調整。Python版本 3.8 - 3.11。推薦使用 3.10 以保證廣泛的庫兼容性。使用python --version檢查。包管理工具pip最新版。建議使用虛擬環(huán)境venv或conda隔離項目。2. 關鍵 Python 庫我們將使用langchain社區(qū)的一個流行框架langchain-core來演示如何定義和調用 Tools/Skills因為它設計清晰且被廣泛采用。# 創(chuàng)建并進入項目目錄 mkdir agent-skills-demo cd agent-skills-demo # 創(chuàng)建虛擬環(huán)境可選但推薦 python -m venv venv # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate # 安裝核心依賴 pip install langchain-core langchain-openai # langchain-openai 用于接入 OpenAI 模型如果你用其他模型請安裝對應包如 langchain-anthropic, langchain-community3. 大模型訪問權限你需要一個可訪問的大語言模型 API。本文示例使用 OpenAI GPT 系列但你也可以替換為 Claude、DeepSeek 或本地部署的模型。OpenAI在 OpenAI Platform 獲取 API Key。將 API Key 設置為環(huán)境變量這是最安全的方式# Linux/macOS export OPENAI_API_KEYyour-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEYyour-api-key-here4. 從零構建你的第一個 Agent Skill我們從一個最簡單的技能開始一個查詢指定城市天氣的技能。雖然它內部只是返回模擬數據但完整展示了 Skill 的定義、封裝和調用流程。4.1 定義技能函數首先創(chuàng)建一個 Python 文件my_skills.py。# my_skills.py import json from typing import Type from pydantic import BaseModel, Field from langchain_core.tools import BaseTool, StructuredTool # 1. 定義技能的輸入參數模型Schema # 這幫助 LLM 理解調用這個技能需要提供什么信息 class WeatherQueryInput(BaseModel): 輸入參數查詢天氣需要城市名。 city_name: str Field(description要查詢天氣的城市名稱例如北京、上海、New York) # 2. 實現技能的核心邏輯函數 def get_current_weather(city_name: str) - str: 獲取指定城市的當前天氣情況。 這是一個模擬函數真實場景應調用如 OpenWeatherMap 的 API。 # 模擬一些天氣數據 weather_data { 北京: {city: 北京, condition: 晴朗, temperature: 22°C, humidity: 40%}, 上海: {city: 上海, condition: 多云, temperature: 25°C, humidity: 65%}, New York: {city: New York, condition: 小雨, temperature: 18°C, humidity: 80%}, } city weather_data.get(city_name) if city: return json.dumps(city, ensure_asciiFalse) else: return json.dumps({error: f未找到城市 {city_name} 的天氣信息}, ensure_asciiFalse) # 3. 使用 LangChain 的 StructuredTool 將函數包裝成一個標準的 Tool/Skill # 這是關鍵一步將普通函數轉化為 Agent 可理解和調用的對象。 weather_tool StructuredTool.from_function( funcget_current_weather, # 關聯(lián)的函數 nameget_current_weather, # 技能名稱LLM 通過這個名稱來調用 description查詢指定城市的當前天氣。, # 技能描述LLM 據此判斷何時使用此技能 args_schemaWeatherQueryInput, # 輸入參數 schema return_directFalse, # 是否直接返回結果給用戶。通常為 False讓 Agent 決定如何呈現。 )4.2 測試技能是否可用創(chuàng)建另一個文件test_skill.py直接測試我們剛定義的技能。# test_skill.py from my_skills import weather_tool # 直接調用工具就像調用普通函數一樣但需要通過 invoke 方法并傳入參數字典 result weather_tool.invoke({city_name: 上海}) print(直接調用技能結果) print(result) print(\n---\n) # 查看技能的 Schema 信息這是 LLM 所看到的內容 print(技能 Schema (供LLM使用)) print(f名稱: {weather_tool.name}) print(f描述: {weather_tool.description}) print(f參數: {weather_tool.args})運行python test_skill.py你應該能看到上海的模擬天氣信息被打印出來同時也能看到技能的元數據。這證明你的技能函數工作正常并且已經被正確封裝。5. 將技能賦予 Agent 并實現自動調用單個技能自己運行意義不大關鍵是讓 AgentLLM能夠根據用戶需求自動決定是否使用、如何使用這個技能。下面我們創(chuàng)建一個簡單的 Agent并觀察它如何運用get_current_weather技能。5.1 創(chuàng)建帶有技能的 Agent創(chuàng)建文件run_agent.py。# run_agent.py import os from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate from my_skills import weather_tool # 導入我們定義的技能 # 0. 確保已設置 OPENAI_API_KEY 環(huán)境變量 # 或者在代碼中設置不推薦用于生產 # os.environ[OPENAI_API_KEY] your-key # 1. 初始化大語言模型 llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 使用 gpt-4o-mini成本低且性能足夠 # 2. 準備技能列表。一個 Agent 可以擁有多個技能。 tools [weather_tool] # 3. 設計提示詞模板告訴 Agent 它的角色和可用技能。 # 這是引導 Agent 行為的關鍵。 prompt ChatPromptTemplate.from_messages([ (system, 你是一個樂于助人的助手可以調用工具來幫助用戶解決問題。 如果你需要查詢實時信息如天氣請務必調用相應的工具。 你的回答應當清晰、準確。 以下是你可以使用的工具 {tools} 調用工具時請嚴格按照工具要求的參數格式提供信息。 如果用戶的問題無法通過現有工具解決請誠實地告知用戶你的能力限制。), (placeholder, {chat_history}), # 預留多輪對話歷史的位置 (human, {input}), # 用戶當前輸入 (placeholder, {agent_scratchpad}), # 預留 Agent 思考過程的位置 ]) # 4. 創(chuàng)建 Agent agent create_tool_calling_agent(llmllm, toolstools, promptprompt) # 5. 創(chuàng)建 Agent 執(zhí)行器它負責運行 Agent 的循環(huán)思考-調用工具-再思考-輸出 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # verboseTrue 打印詳細過程 # 6. 運行測試 if __name__ __main__: # 測試用例 1需要調用技能的問題 query1 今天上海的天氣怎么樣 print(f用戶: {query1}) result1 agent_executor.invoke({input: query1, chat_history: []}) print(f助手: {result1[output]}\n) # 測試用例 2無需調用技能的問題 query2 你好請介紹一下你自己。 print(f用戶: {query2}) result2 agent_executor.invoke({input: query2, chat_history: []}) print(f助手: {result2[output]}\n) # 測試用例 3技能無法解決的問題 query3 你能幫我預訂明天的機票嗎 print(f用戶: {query3}) result3 agent_executor.invoke({input: query3, chat_history: []}) print(f助手: {result3[output]})5.2 運行與觀察運行python run_agent.py。由于設置了verboseTrue你會在控制臺看到詳細的執(zhí)行過程類似于用戶: 今天上海的天氣怎么樣 Entering new AgentExecutor chain... 思考用戶詢問上海的天氣我需要使用 get_current_weather 工具來獲取信息。 Action: get_current_weather Action Input: {city_name: 上海} Observation: {city: 上海, condition: 多云, temperature: 25°C, humidity: 65%} 思考我已經獲取到了上海的天氣信息現在可以回答用戶了。 助手: 上海當前的天氣是多云氣溫25°C濕度65%。這個過程清晰地展示了 Agent 的推理鏈Chain of Thought理解問題識別出用戶需要天氣信息。規(guī)劃決定調用get_current_weather工具。執(zhí)行以正確的參數{city_name: 上海}調用工具。觀察結果接收工具返回的 JSON 數據。合成回答將工具返回的結構化數據轉化為自然語言回復給用戶。對于不需要工具的問題如“介紹自己”Agent 會直接利用 LLM 的內部知識回答。對于工具無法解決的問題如“訂機票”Agent 會根據提示詞要求誠實地告知能力限制。6. 構建企業(yè)級實戰(zhàn)技能復合技能與外部 API 集成單一技能只是開始。企業(yè)級應用需要更復雜、更可靠的技能這些技能往往需要組合多個步驟、調用外部 API 并處理異常。6.1 設計一個復合技能GitHub 倉庫分析報告假設我們需要一個技能能分析指定 GitHub 倉庫的近期活躍度如最近10個 Issue 主要貢獻者并生成一份簡短的文本報告。這個技能會涉及調用 GitHub REST API 獲取數據。對數據進行處理和分析。格式化生成報告。步驟一安裝額外依賴pip install requests python-dateutil步驟二實現復合技能創(chuàng)建文件advanced_skills.py。# advanced_skills.py import requests import json from datetime import datetime, timedelta from dateutil import parser from typing import List, Dict, Any from pydantic import BaseModel, Field from langchain_core.tools import StructuredTool # --- 技能1獲取倉庫基礎信息 --- class RepoInfoInput(BaseModel): owner: str Field(descriptionGitHub 倉庫的所有者用戶名或組織名例如microsoft) repo: str Field(descriptionGitHub 倉庫的名稱例如vscode) def get_github_repo_info(owner: str, repo: str) - str: 獲取 GitHub 倉庫的基礎信息如星標數、fork 數等。 url fhttps://api.github.com/repos/{owner}/{repo} headers {Accept: application/vnd.github.v3json} try: response requests.get(url, headersheaders, timeout10) response.raise_for_status() data response.json() # 提取關鍵信息 result { full_name: data.get(full_name), description: data.get(description), stars: data.get(stargazers_count), forks: data.get(forks_count), open_issues: data.get(open_issues_count), language: data.get(language), updated_at: data.get(updated_at), } return json.dumps(result, ensure_asciiFalse) except requests.exceptions.RequestException as e: return json.dumps({error: f請求 GitHub API 失敗: {str(e)}}, ensure_asciiFalse) except json.JSONDecodeError: return json.dumps({error: 解析 GitHub 響應失敗}, ensure_asciiFalse) repo_info_tool StructuredTool.from_function( funcget_github_repo_info, nameget_github_repo_info, description獲取指定 GitHub 倉庫的基礎信息和統(tǒng)計指標。, args_schemaRepoInfoInput, ) # --- 技能2分析近期 Issues --- class AnalyzeIssuesInput(BaseModel): owner: str Field(descriptionGitHub 倉庫的所有者) repo: str Field(descriptionGitHub 倉庫的名稱) days: int Field(default30, description分析最近多少天內的 Issue默認30天) def analyze_recent_issues(owner: str, repo: str, days: int 30) - str: 分析 GitHub 倉庫最近一段時間內創(chuàng)建的 Issue。 since_date (datetime.now() - timedelta(daysdays)).isoformat() url fhttps://api.github.com/repos/{owner}/{repo}/issues params {state: all, since: since_date, sort: created, direction: desc, per_page: 10} headers {Accept: application/vnd.github.v3json} try: response requests.get(url, headersheaders, paramsparams, timeout15) response.raise_for_status() issues response.json() analysis { total_recent_issues: len(issues), issues: [] } for issue in issues[:5]: # 只分析前5個作為示例 issue_info { number: issue.get(number), title: issue.get(title), state: issue.get(state), created_at: issue.get(created_at), user: issue.get(user, {}).get(login), } analysis[issues].append(issue_info) # 簡單統(tǒng)計 open_count sum(1 for i in issues if i.get(state) open) analysis[open_issues] open_count analysis[closed_issues] len(issues) - open_count return json.dumps(analysis, ensure_asciiFalse) except requests.exceptions.RequestException as e: return json.dumps({error: f請求 Issues API 失敗: {str(e)}}, ensure_asciiFalse) issues_analysis_tool StructuredTool.from_function( funcanalyze_recent_issues, nameanalyze_recent_issues, description分析指定 GitHub 倉庫最近一段時間內的 Issue 活躍情況。, args_schemaAnalyzeIssuesInput, ) # --- 復合技能生成倉庫分析報告 --- # 這個技能本身不直接調用API而是協(xié)調調用上述兩個基礎技能并整合結果。 class GenerateRepoReportInput(BaseModel): owner: str Field(descriptionGitHub 倉庫的所有者) repo: str Field(descriptionGitHub 倉庫的名稱) def generate_github_repo_report(owner: str, repo: str) - str: 生成一份關于 GitHub 倉庫的簡要分析報告。 內部會調用獲取倉庫信息和分析 Issue 的工具。 # 調用第一個工具獲取基礎信息 print(f[INFO] 正在獲取倉庫 {owner}/{repo} 的基礎信息...) info_result get_github_repo_info(owner, repo) info_data json.loads(info_result) if error in info_data: return f獲取倉庫基礎信息失敗{info_data[error]} # 調用第二個工具分析 Issues print(f[INFO] 正在分析倉庫 {owner}/{repo} 的近期 Issues...) issues_result analyze_recent_issues(owner, repo, days30) issues_data json.loads(issues_result) if error in issues_data: return f分析 Issues 失敗{issues_data[error]} # 整合信息生成報告文本 report_lines [] report_lines.append(f# GitHub 倉庫分析報告{info_data.get(full_name, f{owner}/{repo})}) report_lines.append(f**描述**: {info_data.get(description, 無)}) report_lines.append(f**主要語言**: {info_data.get(language, 未知)}) report_lines.append(f**星標數**: {info_data.get(stars, N/A)}) report_lines.append(f**Fork 數**: {info_data.get(forks, N/A)}) report_lines.append(f**最近更新**: {info_data.get(updated_at, N/A)}) report_lines.append() report_lines.append(f## 近期活躍度分析 (最近30天)) report_lines.append(f共創(chuàng)建 {issues_data.get(total_recent_issues, 0)} 個 Issue。) report_lines.append(f- 仍開放的: {issues_data.get(open_issues, 0)}) report_lines.append(f- 已關閉的: {issues_data.get(closed_issues, 0)}) report_lines.append() report_lines.append(### 最近的部分 Issues) for issue in issues_data.get(issues, [])[:3]: # 展示最近3個 report_lines.append(f- [#{issue.get(number)}] {issue.get(title)} ({issue.get(state)}) - 由 {issue.get(user)} 創(chuàng)建于 {issue.get(created_at)}) report_lines.append() report_lines.append(*報告生成時間{}*.format(datetime.now().strftime(%Y-%m-%d %H:%M:%S))) return \n.join(report_lines) # 將復合技能也封裝成 Tool這樣 Agent 可以直接調用它 repo_report_tool StructuredTool.from_function( funcgenerate_github_repo_report, namegenerate_github_repo_report, description為指定的 GitHub 倉庫生成一份包含基礎信息和近期活躍度的分析報告。, args_schemaGenerateRepoReportInput, )6.2 測試復合技能創(chuàng)建測試文件test_advanced_skill.py。# test_advanced_skill.py from advanced_skills import repo_report_tool # 測試一個知名倉庫如 LangChain 的 LangSmith SDK result repo_report_tool.invoke({owner: langchain-ai, repo: langsmith}) print(GitHub 倉庫分析報告) print(result)運行此腳本你會看到控制臺先打印出[INFO]日志然后輸出一份格式化的 Markdown 報告。這個generate_github_repo_report就是一個復合技能的典型例子。它內部編排了多個子任務調用兩個 API并進行了數據整合與格式化。在企業(yè)場景中你可以用類似模式構建更復雜的技能例如generate_sales_report從 CRM、數據庫拉取數據分析生成 PPT 大綱。monitor_system_health調用多個監(jiān)控系統(tǒng) API匯總狀態(tài)發(fā)送警報。onboard_new_employee在 HR 系統(tǒng)、IT 工單系統(tǒng)、通訊工具中創(chuàng)建一系列記錄。7. 技能的管理、注冊與動態(tài)加載當技能數量增多時需要一套管理機制。常見的模式是使用一個技能注冊中心Registry。7.1 創(chuàng)建技能注冊中心創(chuàng)建文件skill_registry.py。# skill_registry.py from typing import Dict, Any, List from langchain_core.tools import BaseTool import importlib import pkgutil import sys class SkillRegistry: 一個簡單的技能注冊中心用于管理和加載所有可用的技能。 def __init__(self): self._tools: Dict[str, BaseTool] {} def register_tool(self, tool: BaseTool): 注冊一個技能工具。 if tool.name in self._tools: print(f[WARNING] 工具名 {tool.name} 已存在將被覆蓋。) self._tools[tool.name] tool print(f[INFO] 已注冊工具: {tool.name}) def register_tools(self, tools: List[BaseTool]): 批量注冊技能工具。 for tool in tools: self.register_tool(tool) def get_tool(self, name: str) - BaseTool: 根據名稱獲取技能工具。 return self._tools.get(name) def get_all_tools(self) - List[BaseTool]: 獲取所有已注冊的技能工具。 return list(self._tools.values()) def load_tools_from_module(self, module_name: str): 從一個 Python 模塊中動態(tài)加載所有 Tool 對象。 約定模塊中所有變量名以 _tool 結尾的對象都被視為技能工具。 try: module importlib.import_module(module_name) for attr_name in dir(module): if attr_name.endswith(_tool): attr getattr(module, attr_name) if isinstance(attr, BaseTool): self.register_tool(attr) except ImportError as e: print(f[ERROR] 無法導入模塊 {module_name}: {e}) def list_tools(self): 列出所有已注冊的工具及其描述。 print( 已注冊技能列表 ) for name, tool in self._tools.items(): print(f- {name}: {tool.description}) # 創(chuàng)建一個全局注冊中心實例 registry SkillRegistry()7.2 使用注冊中心修改run_agent.py使用注冊中心來管理技能。# run_agent_with_registry.py import os from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain_core.prompts import ChatPromptTemplate # 導入技能注冊中心和各個技能模塊 from skill_registry import registry from my_skills import weather_tool from advanced_skills import repo_info_tool, issues_analysis_tool, repo_report_tool # 1. 向注冊中心注冊技能 registry.register_tools([weather_tool, repo_info_tool, issues_analysis_tool, repo_report_tool]) # 或者從模塊自動加載 # registry.load_tools_from_module(my_skills) # registry.load_tools_from_module(advanced_skills) # 列出所有可用技能 registry.list_tools() # 2. 從注冊中心獲取所有工具 tools registry.get_all_tools() # 3. 初始化 LLM 和 Agent同之前 llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_messages([ (system, 你是一個強大的助手擁有多種技能。請根據用戶問題選擇最合適的工具。 可用工具 {tools} 請嚴格按工具要求提供參數。如果無法解決請說明原因。), (placeholder, {chat_history}), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llmllm, toolstools, promptprompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 4. 運行一個復雜查詢 complex_query 請幫我分析一下 langchain-ai/langsmith 這個 GitHub 倉庫的近期情況并生成一份報告。 print(f\n用戶: {complex_query}) result agent_executor.invoke({input: complex_query, chat_history: []}) print(f\n助手: {result[output]})運行這個腳本你會看到注冊中心列出了所有技能然后 Agent 在面對復雜查詢時自動選擇了最匹配的復合技能generate_github_repo_report來執(zhí)行而不是分別調用get_github_repo_info和analyze_recent_issues。這體現了智能體在擁有多個技能時的規(guī)劃和選擇能力。8. 性能優(yōu)化、錯誤處理與安全邊界8.1 性能優(yōu)化技能懶加載對于初始化耗時的技能如加載大模型不要在注冊時就完全初始化可以封裝一個工廠函數在首次調用時再加載。緩存對頻繁調用、結果變化不頻繁的外部 API 請求如天氣、股票價格添加緩存層如functools.lru_cache或 Redis。異步支持如果技能涉及大量 I/O 操作網絡請求、數據庫查詢考慮使用async/await實現異步技能以提升 Agent 在高并發(fā)下的吞吐量。LangChain 支持異步工具調用。8.2 錯誤處理與魯棒性一個健壯的技能必須處理各種異常。網絡超時與重試在調用外部 API 時使用try...except包裹并考慮實現指數退避重試機制。參數驗證除了 Pydantic Schema在函數內部也應對參數進行業(yè)務邏輯驗證。優(yōu)雅降級當主要功能失敗時嘗試提供降級方案或更友好的錯誤信息。日志記錄使用logging模塊記錄技能調用的開始、結束、參數和錯誤便于排查問題。import logging import time from tenacity import retry, stop_after_attempt, wait_exponential logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def robust_api_call(url: str, params: dict) - dict: 一個帶有重試和日志的健壯 API 調用函數示例。 logger.info(f調用 API: {url}, 參數: {params}) try: response requests.get(url, paramsparams, timeout15) response.raise_for_status() return response.json() except requests.exceptions.Timeout: logger.error(fAPI 調用超時: {url}) raise except requests.exceptions.RequestException as e: logger.error(fAPI 調用失敗: {url}, 錯誤: {e}) raise8.3 安全與合規(guī)邊界這是企業(yè)級應用的生命線。權限控制技能可能訪問敏感數據或執(zhí)行危險操作。必須在技能執(zhí)行前進行身份驗證和授權檢查。可以將用戶上下文傳遞給技能函數。輸入凈化對所有來自外部的輸入包括用戶輸入和 LLM 生成的參數進行嚴格的驗證和凈化防止注入攻擊。訪問外部資源確保技能調用的外部 API 或服務是合法、合規(guī)的并遵守其使用條款。數據隱私如果技能處理個人數據必須遵守 GDPR、CCPA 等數據保護法規(guī)。避免在日志中記錄敏感信息。操作審計記錄“誰在什么時候調用了什么技能參數是什么結果是什么”用于安全審計和問題追溯。9. 常見問題與排查方法在開發(fā)和運行 Agent Skills 時你可能會遇到以下典型問題。問題現象可能原因排查方式解決方案Agent 不調用技能1. 技能描述不清晰。2. LLM 溫度 (temperature) 過高導致輸出隨機。3. 系統(tǒng)提示詞未正確列出工具。1. 檢查verboseTrue的日志看 Agent 的思考過程。2. 檢查技能name和description是否準確。3. 簡化提示詞明確要求使用工具。1. 優(yōu)化技能描述使其更匹配預期問題。2. 將temperature設為 0 或更低。3. 在提示詞中強調“你必須使用工具”。技能調用參數錯誤1. LLM 未能正確理解參數格式。2. Pydantic Schema 定義太復雜或模糊。1. 查看Action Input日志參數是否是有效的 JSON。2. 檢查 Schema 中Field的description是否清晰。1. 為每個參數提供更精確、示例化的描述。2. 使用更簡單的數據類型如str,int。3. 考慮使用StructuredTool的args_schema進行強約束。技能執(zhí)行超時或失敗1. 外部 API 不可用或慢。2. 網絡問題。3. 技能函數內部有 bug。1. 在技能函數內部添加超時和異常捕獲。2. 單獨測試技能函數確認其能正常工作。3. 查看詳細的錯誤堆棧。1. 增加超時時間添加重試邏輯。2. 實現 fallback 機制或返回友好的錯誤信息。3. 完善技能函數的錯誤處理。多技能沖突或選擇不當多個技能描述相似LLM 困惑。觀察 Agent 選擇了哪個技能是否合理。1. 細化技能描述突出其獨特用途和邊界。2. 如果技能有重疊考慮合并或重構。依賴安裝失敗Python 包版本沖突或網絡問題。查看pip install的錯誤信息。1. 使用虛擬環(huán)境。2. 使用requirements.txt固定版本。3. 使用國內鏡像源加速下載。10. 總結與最佳實踐通過以上步驟我們完成了一個從簡單到復雜、從單技能到技能體系的 Agent Skills 實戰(zhàn)演練。我們來總結一下關鍵點和最佳實踐1. 技能設計要“高內聚、低耦合”每個技能應專注于完成一件明確的事情。復雜的業(yè)務流程應由 Agent 通過規(guī)劃調用多個簡單技能來完成或者封裝成一個復合技能。避免創(chuàng)建“巨無霸”技能。2. 描述即契約技能的name和description是 LLM 理解它的唯一途徑。描述務必準確、具體、包含關鍵詞。好的描述能極大提升 Agent 調用技能的準確率。3. 輸入 Schema 是護欄使用 Pydantic 嚴格定義輸入參數的類型和描述。這不僅是給 LLM 的指南也是代碼的自動驗證和文檔。4. 錯誤處理不是可選項技能必須能優(yōu)雅地處理失敗并返回對 Agent 和最終用戶都有意義的信息而不是拋出未捕獲的異常導致整個 Agent 崩潰。5. 從簡單開始逐步迭代不要一開始就設計龐大的技能庫。從一個核心技能開始與 Agent 聯(lián)調確保它能被正確理解和調用。然后逐步添加新技能并觀察它們之間的協(xié)作。6. 測試、測試、再測試為每個技能編寫單元測試。模擬 Agent 調用場景進行集成測試。測試正常流程更要測試邊界情況和異常輸入。7. 關注安全與成本尤其是調用外部 API 或執(zhí)行寫操作的技能必須加入權限校驗、操作確認和用量監(jiān)控防止惡意調用或意外產生高額費用。Agent Skills 是將大語言模型能力落地到具體業(yè)務場景的橋梁。掌握如何設計、實現和管理技能你就掌握了構建實用 AI Agent 應用的核心能力。建議從本文的示例代碼出發(fā)嘗試將你日常工作中重復、規(guī)則明確的流程改造成一個 Agent Skill體驗 AI 驅動的自動化帶來的效率提升。