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