：從注冊表到代碼庫的工程化演進(jìn))
1. 項(xiàng)目概述從注冊表到代碼庫的AI技能演進(jìn)最近和幾個(gè)做AI Agent的朋友聊天發(fā)現(xiàn)一個(gè)挺有意思的現(xiàn)象大家聊起某個(gè)Agent的“技能”時(shí)說法五花八門。有人說“我調(diào)用了GPT-4的API”有人說“我集成了一個(gè)天氣查詢的插件”還有人說“我寫了個(gè)自定義函數(shù)來處理數(shù)據(jù)”。這讓我意識(shí)到在AI Agent這個(gè)快速發(fā)展的領(lǐng)域里“技能”這個(gè)概念本身正經(jīng)歷著一場從“黑盒調(diào)用”到“白盒構(gòu)建”的深刻轉(zhuǎn)變。這背后的核心就是從“Registry”注冊表思維到“Repository”代碼庫思維的遷移。簡單來說以前我們更多是去一個(gè)中心化的“應(yīng)用商店”里尋找并安裝現(xiàn)成的、封裝好的能力模塊而現(xiàn)在我們越來越傾向于將技能視為一段可讀、可改、可版本控制的代碼存放在自己的“代碼倉庫”里進(jìn)行全生命周期的管理。這種轉(zhuǎn)變不是偶然的。早期的AI應(yīng)用尤其是基于大語言模型LLM的聊天機(jī)器人其“技能”往往依賴于模型本身的能力或者通過簡單的提示詞工程Prompt Engineering來引導(dǎo)。這時(shí)候技能是“內(nèi)嵌”在模型里的或者說是通過一個(gè)“注冊表”式的配置來聲明需要調(diào)用哪些外部API。比如你告訴Agent“如果用戶問天氣你就去調(diào)用某某天氣接口?！?這個(gè)調(diào)用邏輯和接口細(xì)節(jié)對開發(fā)者來說可能是不透明或難以深度定制的。但隨著Agent要處理的任務(wù)越來越復(fù)雜從簡單的問答發(fā)展到能執(zhí)行多步驟工作流、能進(jìn)行復(fù)雜決策的智能體這種“黑盒”模式就捉襟見肘了。我們需要技能具備更強(qiáng)的適應(yīng)性、可調(diào)試性和可維護(hù)性。因此“From Registry to Repository”這個(gè)標(biāo)題精準(zhǔn)地捕捉了當(dāng)前AI Agent開發(fā)的前沿實(shí)踐和未來趨勢。它探討的是AI Agent的技能是如何被“編寫”出來的而不僅僅是配置當(dāng)業(yè)務(wù)需求或環(huán)境發(fā)生變化時(shí)我們?nèi)绾巍斑m配”和調(diào)整這些技能更重要的是在長期的迭代和團(tuán)隊(duì)協(xié)作中我們?nèi)绾蜗窆芾碥浖?xiàng)目一樣有效地“維護(hù)”這些技能的代碼、文檔和依賴關(guān)系這不僅僅是技術(shù)工具的升級(jí)更是一種開發(fā)范式和工程思維的進(jìn)化。接下來我將結(jié)合一線的實(shí)戰(zhàn)經(jīng)驗(yàn)拆解這其中的核心環(huán)節(jié)、技術(shù)選型與避坑指南。2. 核心思路為何技能管理需要代碼庫思維要理解從Registry到Repository的轉(zhuǎn)變我們得先看看兩者在AI Agent上下文中的具體指代和局限性。2.1 Registry模式即插即用的便利與局限在傳統(tǒng)的軟件或早期AI框架中“Registry”是一個(gè)很常見的概念。你可以把它想象成手機(jī)的“應(yīng)用商店”或者Node.js的“npm registry”。它的核心特點(diǎn)是中心化索引和標(biāo)準(zhǔn)化封裝。在AI Agent領(lǐng)域一個(gè)技能Registry可能包含預(yù)定義的工具/函數(shù)列表例如一個(gè)WeatherTool其輸入、輸出格式、調(diào)用方式都被嚴(yán)格定義。插件描述文件比如一個(gè)plugin.json里面聲明了插件的名稱、版本、作者、所需權(quán)限和入口點(diǎn)。遠(yuǎn)程API端點(diǎn)技能的邏輯完全運(yùn)行在遠(yuǎn)端服務(wù)器Agent只通過一個(gè)標(biāo)準(zhǔn)的接口協(xié)議如OpenAI的Function Calling或更通用的OpenAPI/Swagger規(guī)范進(jìn)行調(diào)用。這種模式的優(yōu)勢非常明顯開箱即用開發(fā)者無需關(guān)心技能的內(nèi)部實(shí)現(xiàn)只需簡單配置即可集成。易于發(fā)現(xiàn)和共享有一個(gè)中心化的地方可以瀏覽和搜索所有可用技能。版本和依賴管理Registry可以管理不同版本的技能確保兼容性。然而在復(fù)雜的、生產(chǎn)級(jí)的AI Agent開發(fā)中Registry模式的短板日益凸顯黑盒操作調(diào)試?yán)щy當(dāng)技能執(zhí)行出錯(cuò)或結(jié)果不符合預(yù)期時(shí)你很難深入內(nèi)部邏輯進(jìn)行排查。你只能看到輸入和輸出中間的“思考”過程或數(shù)據(jù)處理邏輯是個(gè)謎。定制化成本高如果某個(gè)天氣查詢技能返回的數(shù)據(jù)結(jié)構(gòu)不符合你的業(yè)務(wù)需求你很難直接修改它。你可能需要聯(lián)系原作者或者自己從頭實(shí)現(xiàn)一個(gè)失去了復(fù)用價(jià)值。難以組合和編排復(fù)雜的任務(wù)往往需要多個(gè)技能協(xié)同工作。Registry中的技能通常是孤立的缺乏標(biāo)準(zhǔn)的、可編程的方式來定義它們之間的數(shù)據(jù)流和依賴關(guān)系。部署和網(wǎng)絡(luò)依賴依賴遠(yuǎn)程Registry和API端點(diǎn)會(huì)引入網(wǎng)絡(luò)延遲、單點(diǎn)故障和額外的運(yùn)維復(fù)雜度。在離線或內(nèi)網(wǎng)環(huán)境中更是無法使用。實(shí)操心得我在早期項(xiàng)目中使用過一些提供“技能市場”的AI平臺(tái)。初期確實(shí)很快就能搭出一個(gè)能對話、能查資料的Demo。但一旦想讓它根據(jù)查詢結(jié)果自動(dòng)生成一份報(bào)告或者把多個(gè)查詢結(jié)果進(jìn)行對比分析時(shí)就卡住了。因?yàn)槊總€(gè)技能都是獨(dú)立的“孤島”沒有統(tǒng)一的“膠水”代碼把它們粘合起來更別提在粘合過程中加入自己的業(yè)務(wù)邏輯了。2.2 Repository模式將技能視為一等公民的代碼Repository模式即“代碼庫”思維正是為了解決上述問題。它核心的觀點(diǎn)是一個(gè)AI Agent的技能本質(zhì)上是一段或一系列具有明確輸入、輸出、副作用和失敗處理的程序代碼。因此它應(yīng)該享受和普通軟件代碼一樣的待遇用代碼編寫使用Python、JavaScript等通用編程語言實(shí)現(xiàn)而不僅僅是JSON配置。進(jìn)行版本控制使用Git來管理技能的迭代歷史方便回滾和協(xié)作。本地化存儲(chǔ)與運(yùn)行技能代碼存放在項(xiàng)目自身的代碼倉庫中可以離線運(yùn)行減少外部依賴?？蓽y試、可調(diào)試可以像單元測試一樣對技能進(jìn)行測試可以用調(diào)試器逐步跟蹤執(zhí)行過程。可組合、可繼承可以通過函數(shù)調(diào)用、類繼承、依賴注入等標(biāo)準(zhǔn)的軟件工程方法構(gòu)建復(fù)雜的技能體系。在這種模式下一個(gè)“技能”可能是一個(gè)Python類它有一個(gè)execute方法也可能是一個(gè)遵循特定協(xié)議的異步函數(shù)。它的依賴、配置、工具函數(shù)都清晰地寫在代碼里。AI Agent框架如LangChain、AutoGen、Semantic Kernel的角色從一個(gè)“技能管理中心”轉(zhuǎn)變?yōu)橐粋€(gè)“技能執(zhí)行運(yùn)行時(shí)”負(fù)責(zé)加載這些代碼模塊并在合適的時(shí)機(jī)調(diào)用它們。這種轉(zhuǎn)變帶來的根本性好處透明度與可控性你對技能的每一個(gè)邏輯分支都了如指掌可以輕易地添加日志、修改邏輯或修復(fù)bug。深度定制與演進(jìn)你可以基于一個(gè)基礎(chǔ)的“數(shù)據(jù)查詢”技能派生出符合自己業(yè)務(wù)數(shù)據(jù)模型的“訂單查詢”技能實(shí)現(xiàn)高效的代碼復(fù)用。復(fù)雜的編排與流程你可以用代碼清晰地定義技能之間的執(zhí)行順序、條件判斷和循環(huán)實(shí)現(xiàn)真正的工作流自動(dòng)化。工程化協(xié)作團(tuán)隊(duì)可以通過Code Review、CI/CD流水線來保證技能代碼的質(zhì)量這與現(xiàn)代軟件開發(fā)流程無縫集成。3. 技能編寫從提示詞工程到可執(zhí)行代碼明確了技能即代碼的理念后我們來看看一個(gè)技能具體是如何被“編寫”出來的。這個(gè)過程已經(jīng)遠(yuǎn)遠(yuǎn)超出了寫一段提示詞Prompt的范疇。3.1 技能的基本構(gòu)成要素一個(gè)完整的、可維護(hù)的AI Agent技能通常包含以下幾個(gè)部分我們可以用一個(gè)“文件查詢”技能作為例子技能描述Skill Description這是技能的“元數(shù)據(jù)”用于讓LLM理解這個(gè)技能是干什么的。它通常是一段自然語言描述但會(huì)以結(jié)構(gòu)化的方式如文檔字符串嵌入在代碼中。class FileSearchSkill: 文件搜索技能。 根據(jù)用戶提供的關(guān)鍵詞在指定的本地目錄或知識(shí)庫中查找相關(guān)的文檔或代碼文件并返回匹配的文件路徑和摘要片段。 此技能支持基于文件內(nèi)容的模糊搜索和基于文件名的精確搜索。 輸入/輸出模式Input/Output Schema嚴(yán)格定義技能接受的參數(shù)和返回的數(shù)據(jù)結(jié)構(gòu)。這是技能與LLM或其他技能交互的“合約”。使用Pydantic這類庫來定義Schema是當(dāng)前的最佳實(shí)踐。from pydantic import BaseModel, Field from typing import List, Optional class FileSearchInput(BaseModel): query: str Field(..., description搜索關(guān)鍵詞) search_path: str Field(default./docs, description要搜索的根目錄路徑) max_results: int Field(default5, description返回的最大結(jié)果數(shù)) search_mode: str Field(defaultcontent, description搜索模式content內(nèi)容或 filename文件名) class SearchResult(BaseModel): file_path: str relevance_score: float preview_snippet: Optional[str] None class FileSearchOutput(BaseModel): results: List[SearchResult] total_hits: int核心執(zhí)行邏輯Execution Logic這是技能的“肌肉”包含了實(shí)際的算法和操作。它應(yīng)該只專注于完成技能描述的任務(wù)并且做好錯(cuò)誤處理。class FileSearchSkill: # ... 描述和Schema定義 ... async def execute(self, input_data: FileSearchInput) - FileSearchOutput: 執(zhí)行文件搜索。 import os from pathlib import Path import mmap import re search_root Path(input_data.search_path) if not search_root.exists(): raise ValueError(f搜索路徑不存在: {input_data.search_path}) results [] pattern re.compile(re.escape(input_data.query), re.IGNORECASE) # 遍歷文件 for file_path in search_root.rglob(*): if file_path.is_file(): try: relevance 0.0 snippet None if input_data.search_mode filename: # 文件名匹配 if pattern.search(file_path.name): relevance 1.0 else: # content mode # 內(nèi)容匹配 (簡化版生產(chǎn)環(huán)境需優(yōu)化) try: with open(file_path, r, encodingutf-8, errorsignore) as f: content f.read(10000) # 只讀前一部分以提高性能 matches list(pattern.finditer(content)) if matches: relevance min(len(matches) / 10, 1.0) # 簡單評分 # 獲取第一個(gè)匹配的上下文作為片段 first_match matches[0] start max(0, first_match.start() - 50) end min(len(content), first_match.end() 50) snippet content[start:end] except (UnicodeDecodeError, IOError): continue # 跳過無法讀取的文件 if relevance 0: results.append(SearchResult( file_pathstr(file_path), relevance_scorerelevance, preview_snippetsnippet )) except Exception as e: # 記錄錯(cuò)誤但繼續(xù)搜索其他文件 print(f處理文件 {file_path} 時(shí)出錯(cuò): {e}) continue # 按相關(guān)性排序并限制數(shù)量 results.sort(keylambda x: x.relevance_score, reverseTrue) final_results results[:input_data.max_results] return FileSearchOutput( resultsfinal_results, total_hitslen(results) )依賴聲明Dependencies技能所依賴的外部庫。這應(yīng)該明確寫在項(xiàng)目的requirements.txt或pyproject.toml中。# requirements.txt pydantic2.0 # 這個(gè)技能本身只用了標(biāo)準(zhǔn)庫但復(fù)雜技能可能需要聲明更多測試用例Tests用于驗(yàn)證技能在各種輸入下是否能正確工作。這是保證技能質(zhì)量的關(guān)鍵。# test_file_search_skill.py import pytest from your_skill_module import FileSearchSkill, FileSearchInput pytest.mark.asyncio async def test_file_search_by_filename(tmp_path): # 創(chuàng)建測試文件 test_file tmp_path / test_hello.txt test_file.write_text(Some content) (tmp_path / ignore.pdf).write_text(pdf content) skill FileSearchSkill() input_data FileSearchInput(queryhello, search_pathstr(tmp_path), search_modefilename) output await skill.execute(input_data) assert output.total_hits 1 assert output.results[0].file_path str(test_file) pytest.mark.asyncio async def test_file_search_empty_result(): skill FileSearchSkill() input_data FileSearchInput(querynonexistentkeyword, search_path/tmp) output await skill.execute(input_data) assert output.total_hits 0 assert len(output.results) 0注意事項(xiàng)在編寫執(zhí)行邏輯時(shí)一個(gè)常見的坑是過度依賴LLM。比如把本可以用確定性代碼快速完成的任務(wù)如上面的文件遍歷和正則匹配也交給LLM去做“思考”和“判斷”這會(huì)極大增加延遲、成本和不確定性。技能代碼應(yīng)該是確定性的、高效的。LLM更適合用于需要理解、推理、生成自然語言或處理非結(jié)構(gòu)化信息的環(huán)節(jié)。好的技能設(shè)計(jì)是“確定性代碼”和“LLM調(diào)用”的有機(jī)結(jié)合。3.2 與LLM的交互模式從硬編碼到動(dòng)態(tài)規(guī)劃技能代碼寫好了如何讓LLM知道在什么時(shí)候、用什么參數(shù)去調(diào)用它呢這里有幾種主流模式函數(shù)調(diào)用Function Calling這是最直接的方式。你將技能的Schema輸入格式提供給LLM。當(dāng)LLM在對話中判斷需要調(diào)用該技能時(shí)它會(huì)輸出一個(gè)結(jié)構(gòu)化的調(diào)用請求包含函數(shù)名和參數(shù)。然后由你的程序來執(zhí)行對應(yīng)的技能代碼。OpenAI的API、Anthropic的Claude都原生支持此功能。優(yōu)點(diǎn)標(biāo)準(zhǔn)化與模型集成好。缺點(diǎn)調(diào)用決策完全由LLM做出有時(shí)會(huì)“幻覺”出不需要的調(diào)用或參數(shù)錯(cuò)誤。智能體框架封裝Agent Framework使用LangChain、AutoGen等框架。這些框架提供了更高層次的抽象比如Tool類。你將自己的技能代碼包裝成一個(gè)Tool實(shí)例然后交給框架的Agent去管理。框架會(huì)處理技能的描述、調(diào)用格式轉(zhuǎn)換以及和LLM的交互。from langchain.tools import Tool from langchain.agents import initialize_agent, AgentType from langchain.llms import OpenAI # 將我們的技能包裝成LangChain Tool file_search_tool Tool( nameFileSearch, funclambda q: file_search_skill.execute(q), # 這里需要適配函數(shù)簽名 description根據(jù)關(guān)鍵詞搜索本地文件。輸入應(yīng)為一個(gè)搜索關(guān)鍵詞字符串。 ) llm OpenAI(temperature0) agent initialize_agent([file_search_tool], llm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue) agent.run(幫我找一下所有關(guān)于‘預(yù)算’的文檔)優(yōu)點(diǎn)開發(fā)快生態(tài)豐富提供了記憶、鏈?zhǔn)秸{(diào)用等高級(jí)功能。缺點(diǎn)框架本身有一定學(xué)習(xí)成本且可能將一些底層細(xì)節(jié)隱藏起來不利于深度定制和調(diào)試。工作流引擎驅(qū)動(dòng)Workflow Engine在更復(fù)雜的場景下技能的調(diào)用不是由LLM實(shí)時(shí)決定的而是由一個(gè)預(yù)定義的工作流如基于YAML或代碼的DAG來驅(qū)動(dòng)。LLM可能只作為工作流中某個(gè)節(jié)點(diǎn)的“處理器”。Apache Airflow、Prefect或?qū)锳I設(shè)計(jì)的框架如Semantic Kernel的“Planner”概念就屬于此類。優(yōu)點(diǎn)流程確定可預(yù)測性強(qiáng)適合復(fù)雜、多步驟的自動(dòng)化任務(wù)。缺點(diǎn)靈活性較低無法處理工作流之外的突發(fā)情況。我的選擇建議是對于大多數(shù)應(yīng)用從函數(shù)調(diào)用模式開始是最樸實(shí)、最可控的。當(dāng)你需要快速構(gòu)建原型或利用大量社區(qū)工具時(shí)智能體框架是很好的選擇。當(dāng)你需要構(gòu)建穩(wěn)定、可監(jiān)控的生產(chǎn)級(jí)自動(dòng)化流程時(shí)工作流引擎模式更值得考慮。無論哪種模式技能的底層實(shí)現(xiàn)都應(yīng)該是獨(dú)立的、可測試的代碼模塊。4. 技能適配讓技能靈活應(yīng)對變化業(yè)務(wù)需求、數(shù)據(jù)格式、外部API總是在變。一個(gè)寫死的技能很快就會(huì)過時(shí)。因此“適配”能力是技能生命力的關(guān)鍵。4.1 參數(shù)化與配置驅(qū)動(dòng)最基礎(chǔ)的適配方式是將技能中可能變化的部分提取為參數(shù)或配置。這聽起來簡單但在設(shè)計(jì)時(shí)需要前瞻性。環(huán)境變量與配置文件數(shù)據(jù)庫連接字符串、API密鑰、默認(rèn)路徑等絕對不應(yīng)該硬編碼在技能代碼里。應(yīng)該通過配置文件如config.yaml或環(huán)境變量注入。# config.yaml skills: file_search: default_search_path: ./data/docs max_file_size_mb: 10 allowed_extensions: [.txt, .md, .pdf]# 技能初始化時(shí)讀取配置 import yaml with open(config.yaml) as f: config yaml.safe_load(f) search_skill FileSearchSkill(default_pathconfig[skills][file_search][default_search_path])動(dòng)態(tài)參數(shù)注入技能的某些行為可能需要根據(jù)運(yùn)行時(shí)上下文決定。例如一個(gè)“數(shù)據(jù)查詢”技能查詢的數(shù)據(jù)庫表名可能由用戶輸入或上游技能的結(jié)果決定。這時(shí)技能的執(zhí)行方法就應(yīng)該接受這些動(dòng)態(tài)參數(shù)。4.2 技能模板與繼承當(dāng)有一類技能功能相似但細(xì)節(jié)不同時(shí)使用面向?qū)ο蟮睦^承或組合模式來創(chuàng)建“技能模板”是高效的做法。假設(shè)我們有多種“通知”技能郵件通知、Slack通知、企業(yè)微信通知。它們核心邏輯都是“發(fā)送一條消息”但具體協(xié)議和參數(shù)不同。from abc import ABC, abstractmethod from pydantic import BaseModel class NotificationMessage(BaseModel): title: str body: str priority: str normal class NotificationSkill(ABC): 通知技能抽象基類 abstractmethod async def send(self, message: NotificationMessage) - bool: 發(fā)送通知返回是否成功 pass class EmailNotificationSkill(NotificationSkill): def __init__(self, smtp_server, sender_email): self.smtp_server smtp_server self.sender sender_email async def send(self, message: NotificationMessage) - bool: # 實(shí)現(xiàn)具體的郵件發(fā)送邏輯 print(f[Email] {message.title}: {message.body}) return True class SlackNotificationSkill(NotificationSkill): def __init__(self, webhook_url): self.webhook_url webhook_url async def send(self, message: NotificationMessage) - bool: # 實(shí)現(xiàn)具體的Slack Webhook調(diào)用邏輯 print(f[Slack] {message.title}: {message.body}) return True # 使用時(shí)可以根據(jù)配置動(dòng)態(tài)選擇技能 notification_config {type: slack, webhook_url: https://hooks.slack.com/...} if notification_config[type] slack: notifier SlackNotificationSkill(notification_config[webhook_url]) elif notification_config[type] email: notifier EmailNotificationSkill(...) # ... 調(diào)用 notifier.send(message)這樣當(dāng)需要新增一個(gè)“釘釘通知”技能時(shí)你只需要繼承NotificationSkill并實(shí)現(xiàn)send方法即可其他調(diào)用代碼無需修改。這符合“開閉原則”。4.3 利用LLM進(jìn)行動(dòng)態(tài)適配這是AI Agent技能獨(dú)有的強(qiáng)大適配能力讓LLM來幫助技能理解并處理未預(yù)見的輸入格式或需求。場景你有一個(gè)“查詢數(shù)據(jù)庫”技能它期望的輸入是一個(gè)結(jié)構(gòu)化的{table_name: “users”, filter: “age 30”}。但用戶用自然語言說“幫我找一下所有年齡超過30歲的用戶”。傳統(tǒng)做法你需要寫一個(gè)復(fù)雜的NLU自然語言理解模塊來解析這句話轉(zhuǎn)化為技能所需的參數(shù)。這很難覆蓋所有表達(dá)方式。LLM適配做法在技能執(zhí)行前插入一個(gè)“參數(shù)解析”步驟。這個(gè)步驟本身可以看作一個(gè)微型的、專用的LLM調(diào)用。class DatabaseQuerySkill: async def execute(self, natural_language_query: str) - QueryResult: # 第一步用LLM將自然語言轉(zhuǎn)換為結(jié)構(gòu)化查詢參數(shù) parameter_prompt f 你將用戶的自然語言查詢轉(zhuǎn)換為數(shù)據(jù)庫查詢參數(shù)。 數(shù)據(jù)庫有表users, products, orders。 輸出必須是JSON格式{{table_name: ..., filter_condition: SQL WHERE clause片段}} 用戶查詢{natural_language_query} structured_params await llm_client.generate_json(parameter_prompt) # 假設(shè) structured_params {table_name: users, filter_condition: age 30} # 第二步用解析后的參數(shù)執(zhí)行實(shí)際的、安全的數(shù)據(jù)庫查詢 return await self._run_actual_query(structured_params[table_name], structured_params[filter_condition])這里L(fēng)LM充當(dāng)了一個(gè)“萬能適配器”將非結(jié)構(gòu)化的輸入適配到技能的結(jié)構(gòu)化接口上。但這里有一個(gè)至關(guān)重要的安全原則永遠(yuǎn)不要讓LLM直接生成或執(zhí)行SQL語句上例中LLM只生成一個(gè)filter_condition的描述如“age 30”然后由你技能中確定性的代碼將這個(gè)描述安全地轉(zhuǎn)換為參數(shù)化查詢從而防止SQL注入攻擊。避坑指南LLM動(dòng)態(tài)適配雖然強(qiáng)大但會(huì)引入額外延遲和不確定性。不要濫用。只在對輸入格式靈活性要求極高且確定性解析規(guī)則過于復(fù)雜或無法窮舉時(shí)才使用。并且一定要在LLM的輸出后加上嚴(yán)格的驗(yàn)證和凈化層確保其輸出符合預(yù)期格式和業(yè)務(wù)安全規(guī)則。5. 技能維護(hù)像管理軟件一樣管理技能將技能代碼化后維護(hù)就自然而然地可以套用成熟的軟件工程實(shí)踐。5.1 版本控制與協(xié)作每個(gè)技能都應(yīng)該是一個(gè)獨(dú)立的代碼模塊存放在Git倉庫中。這帶來了諸多好處變更歷史清晰記錄誰、在什么時(shí)候、為什么修改了技能邏輯。當(dāng)新版本技能出現(xiàn)問題時(shí)可以快速git bisect定位引入bug的提交。分支策略可以為新功能如“支持全文高亮”創(chuàng)建特性分支feat/highlight開發(fā)測試完成后合并到主分支?？梢詣?chuàng)建hotfix分支緊急修復(fù)線上問題。Code Review團(tuán)隊(duì)成員對技能的修改發(fā)起Pull Request其他人可以審查代碼邏輯、安全性、性能并提出建議。這是保證技能代碼質(zhì)量的第一道防線。與CI/CD集成這是Repository模式相比Registry模式最大的運(yùn)維優(yōu)勢。5.2 持續(xù)集成與持續(xù)部署CI/CD為你的技能倉庫搭建CI/CD流水線可以實(shí)現(xiàn)自動(dòng)化測試和部署。一個(gè)典型的.github/workflows/test-skills.yml可能如下name: Test AI Skills on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | pip install -r requirements.txt pip install pytest pytest-asyncio - name: Run unit tests run: | pytest tests/ -v - name: Run integration tests (if any) run: | python -m pytest tests/integration/ --tbshort - name: Lint code run: | pip install black isort mypy black --check . isort --check-only . mypy src/這個(gè)流水線會(huì)在每次代碼推送或PR時(shí)自動(dòng)運(yùn)行確保單元測試通過。代碼風(fēng)格符合規(guī)范Black, isort。類型注解正確mypy。對于部署你可以有另一個(gè)流水線當(dāng)代碼合并到main分支后自動(dòng)將技能包構(gòu)建成Docker鏡像推送到你的私有容器倉庫并更新運(yùn)行中的AI Agent服務(wù)。5.3 測試策略技能的測試需要分層進(jìn)行測試類型測試內(nèi)容工具示例目的單元測試測試技能內(nèi)部函數(shù)的確定性邏輯。pytest,unittest驗(yàn)證代碼邏輯正確邊界條件處理得當(dāng)。集成測試測試技能與真實(shí)依賴如數(shù)據(jù)庫、外部API的交互。pytest 測試數(shù)據(jù)庫/ Mock Server驗(yàn)證技能在真實(shí)環(huán)境中的連通性和基本功能。契約測試測試技能的輸入/輸出Schema是否穩(wěn)定。pytest Pydantic Schema防止Schema的意外變更破壞上游調(diào)用者。LLM交互測試測試技能描述是否能被LLM正確理解并調(diào)用。使用LLM的本地小模型如llama.cpp或Mock驗(yàn)證技能元數(shù)據(jù)的有效性。端到端測試將技能放入一個(gè)完整的Agent中測試從用戶輸入到最終輸出的全過程。腳本模擬用戶對話驗(yàn)證技能在完整工作流中的表現(xiàn)。一個(gè)高級(jí)技巧錄制與回放Record and Replay。對于涉及LLM調(diào)用的技能其輸出具有非確定性。測試時(shí)你可以將第一次運(yùn)行LLM時(shí)得到的響應(yīng)假設(shè)它是正確的錄制下來保存為“金標(biāo)準(zhǔn)”Golden Master。在后續(xù)的測試中直接回放這個(gè)錄制的響應(yīng)而不是真實(shí)調(diào)用LLM。這保證了測試的確定性和速度同時(shí)驗(yàn)證了技能處理LLM響應(yīng)的邏輯是否正確。工具如vcr.py可以幫助實(shí)現(xiàn)這一點(diǎn)。5.4 監(jiān)控與可觀測性線上運(yùn)行的技能需要被監(jiān)控。你需要知道調(diào)用量每個(gè)技能被調(diào)用的頻率。成功率/錯(cuò)誤率技能執(zhí)行成功和失敗的比例。延遲技能從被調(diào)用到返回結(jié)果所花費(fèi)的時(shí)間。關(guān)鍵業(yè)務(wù)指標(biāo)例如一個(gè)“生成報(bào)告”技能可以監(jiān)控其生成報(bào)告的平均字?jǐn)?shù)、被用戶采納的比例等。實(shí)現(xiàn)上可以在每個(gè)技能的execute方法開始和結(jié)束時(shí)打點(diǎn)將數(shù)據(jù)發(fā)送到監(jiān)控系統(tǒng)如Prometheus Grafana或日志系統(tǒng)如ELK Stack。import time import logging from prometheus_client import Counter, Histogram SKILL_CALL_COUNT Counter(skill_calls_total, Total skill calls, [skill_name]) SKILL_DURATION Histogram(skill_duration_seconds, Skill execution duration, [skill_name]) SKILL_ERROR_COUNT Counter(skill_errors_total, Total skill errors, [skill_name]) class InstrumentedFileSearchSkill(FileSearchSkill): async def execute(self, input_data: FileSearchInput) - FileSearchOutput: SKILL_CALL_COUNT.labels(skill_namefile_search).inc() start_time time.time() try: result await super().execute(input_data) duration time.time() - start_time SKILL_DURATION.labels(skill_namefile_search).observe(duration) return result except Exception as e: SKILL_ERROR_COUNT.labels(skill_namefile_search).inc() logging.error(fFileSearchSkill failed: {e}, exc_infoTrue) raise6. 架構(gòu)模式與工具選型在實(shí)際項(xiàng)目中組織大量的技能代碼需要一定的架構(gòu)設(shè)計(jì)。這里介紹兩種常見模式。6.1 單體倉庫 vs 多倉庫單體倉庫Monorepo將所有技能的代碼放在同一個(gè)Git倉庫中。優(yōu)點(diǎn)依賴管理簡單代碼共享和重構(gòu)方便容易保證跨技能的一致性。缺點(diǎn)倉庫體積會(huì)變得很大權(quán)限控制較粗粒度構(gòu)建和測試可能變慢。適用場景技能數(shù)量不多幾十個(gè)以內(nèi)團(tuán)隊(duì)規(guī)模較小技能之間耦合緊密。多倉庫Polyrepo每個(gè)技能或一組緊密相關(guān)的技能擁有自己獨(dú)立的Git倉庫。優(yōu)點(diǎn)權(quán)限清晰獨(dú)立部署和版本化構(gòu)建和測試隔離性好。缺點(diǎn)跨技能共享通用代碼如工具類、基礎(chǔ)Schema較麻煩依賴版本容易沖突。適用場景技能數(shù)量眾多由不同團(tuán)隊(duì)負(fù)責(zé)技能間相對獨(dú)立。我的建議對于大多數(shù)中小型AI Agent項(xiàng)目從單體倉庫開始是更優(yōu)的選擇。它極大地簡化了初期的開發(fā)、測試和依賴管理?？梢允褂孟駊oetry或uv這樣的現(xiàn)代Python包管理工具在單體倉庫內(nèi)管理多個(gè)技能包的虛擬環(huán)境。6.2 技能發(fā)現(xiàn)與加載機(jī)制當(dāng)技能都作為代碼模塊存在后Agent如何動(dòng)態(tài)地發(fā)現(xiàn)和加載它們一個(gè)常見的模式是使用“插件系統(tǒng)”或“發(fā)現(xiàn)協(xié)議”?；谌肟邳c(diǎn)的發(fā)現(xiàn)Entry Points這是Python打包標(biāo)準(zhǔn)的一部分。每個(gè)技能包在pyproject.toml中聲明自己的入口點(diǎn)。# 在技能的 pyproject.toml 中 [project.entry-points.ai_agent.skills] file_search my_skills.file_search:FileSearchSkill data_plotter my_skills.visualization:DataPlotterSkill在Agent主程序中可以使用importlib.metadata來發(fā)現(xiàn)所有已安裝的技能。from importlib.metadata import entry_points def load_skills(): skills {} discovered_skills entry_points(groupai_agent.skills) for ep in discovered_skills: skill_class ep.load() # 動(dòng)態(tài)加載類 skills[ep.name] skill_class() return skills這種方式非常優(yōu)雅技能包可以通過pip install安裝Agent自動(dòng)發(fā)現(xiàn)?；谀夸洅呙璧陌l(fā)現(xiàn)更簡單直接的方式。約定一個(gè)特定的目錄如./skillsAgent啟動(dòng)時(shí)掃描該目錄下所有符合命名規(guī)范的Python文件如*_skill.py并自動(dòng)導(dǎo)入其中定義的技能類。import importlib.util from pathlib import Path def load_skills_from_dir(skills_dir: Path): skills {} for file_path in skills_dir.glob(*_skill.py): module_name file_path.stem spec importlib.util.spec_from_file_location(module_name, file_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) # 假設(shè)每個(gè)模塊都有一個(gè) export_skill 變量指向技能實(shí)例 if hasattr(module, export_skill): skills[module_name] module.export_skill return skills這種方式無需安裝適合快速開發(fā)和調(diào)試。6.3 工具鏈推薦包/依賴管理Poetry或UV。它們能很好地管理項(xiàng)目依賴、虛擬環(huán)境和打包發(fā)布特別是對于單體倉庫內(nèi)多包的情況。測試框架Pytest。功能強(qiáng)大插件生態(tài)豐富如pytest-asyncio用于異步測試。代碼風(fēng)格與質(zhì)量Black格式化、isort導(dǎo)入排序、Flake8或Ruff代碼檢查、mypy靜態(tài)類型檢查。將這些工具集成到CI和預(yù)提交鉤子pre-commit中。Schema定義與驗(yàn)證Pydantic V2。幾乎是Python生態(tài)中定義數(shù)據(jù)模型和驗(yàn)證輸入輸出的不二之選性能好功能全。文檔生成MkDocs或Sphinx。為你的技能代碼庫生成漂亮的API文檔。技能的文檔字符串Docstring就是最好的文檔來源。容器化Docker。將你的Agent及其所有技能依賴打包成鏡像確保環(huán)境一致性。7. 常見問題與實(shí)戰(zhàn)避坑在實(shí)際開發(fā)和運(yùn)維中你會(huì)遇到各種各樣的問題。以下是一些典型問題及其解決思路。7.1 技能執(zhí)行失敗的處理技能可能因?yàn)榫W(wǎng)絡(luò)超時(shí)、外部API變化、資源不足等原因失敗。一個(gè)健壯的Agent不能因?yàn)橐粋€(gè)技能失敗就整體崩潰。重試機(jī)制對于暫時(shí)性錯(cuò)誤如網(wǎng)絡(luò)抖動(dòng)可以實(shí)現(xiàn)指數(shù)退避的重試邏輯。import asyncio from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type retry( stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10), retryretry_if_exception_type((TimeoutError, IOError)) ) async def call_unstable_api(self, param): # 調(diào)用可能不穩(wěn)定的外部API ...優(yōu)雅降級(jí)當(dāng)主要技能失敗時(shí)提供一個(gè)備選方案。例如高清圖片生成失敗時(shí)返回一個(gè)低清版本或一個(gè)提示信息。超時(shí)控制為每個(gè)技能設(shè)置執(zhí)行超時(shí)防止其長時(shí)間阻塞Agent。import asyncio async def execute_with_timeout(skill, input_data, timeout30): try: return await asyncio.wait_for(skill.execute(input_data), timeouttimeout) except asyncio.TimeoutError: return {error: Skill execution timed out}錯(cuò)誤信息上拋將技能失敗的具體原因而非堆棧跟蹤以結(jié)構(gòu)化的方式返回給LLM或用戶讓LLM決定下一步該做什么如重試、換一種方式、向用戶道歉。7.2 技能間的依賴與循環(huán)調(diào)用當(dāng)技能A依賴技能B的結(jié)果而技能B又可能調(diào)用技能A時(shí)就形成了循環(huán)依賴可能導(dǎo)致死循環(huán)或遞歸過深。依賴注入明確聲明技能的依賴關(guān)系。在初始化時(shí)注入而不是在運(yùn)行時(shí)動(dòng)態(tài)查找。這使依賴關(guān)系清晰也便于測試時(shí)替換Mock對象。有向無環(huán)圖DAG檢查如果你用工作流引擎來編排技能大多數(shù)引擎會(huì)自動(dòng)檢測循環(huán)依賴。如果是LLM動(dòng)態(tài)規(guī)劃則需要在技能描述中明確說明其功能邊界并設(shè)置最大調(diào)用深度限制。上下文管理設(shè)計(jì)一個(gè)全局或會(huì)話級(jí)的“上下文”對象存儲(chǔ)已執(zhí)行技能的結(jié)果。當(dāng)一個(gè)技能需要另一個(gè)技能的結(jié)果時(shí)先從上下文中查找避免重復(fù)執(zhí)行。同時(shí)上下文也可以用于檢測循環(huán)如果發(fā)現(xiàn)當(dāng)前技能所需的輸入正在等待自己執(zhí)行的結(jié)果。7.3 技能的版本管理與兼容性當(dāng)技能接口Schema發(fā)生變化時(shí)如何保證已有的Agent工作流不中斷語義化版本對技能包使用語義化版本號(hào)如1.2.3。MAJOR版本號(hào)增加表示有不兼容的API變更MINOR版本號(hào)增加表示新增了向后兼容的功能PATCH版本號(hào)增加表示做了向后兼容的問題修復(fù)。多版本共存在Agent中可以同時(shí)加載同一個(gè)技能的不同主版本如FileSearchSkillV1和FileSearchSkillV2。通過技能名稱或元數(shù)據(jù)來區(qū)分。舊的Agent工作流繼續(xù)調(diào)用V1新的則可以調(diào)用V2。Schema演化與默認(rèn)值使用Pydantic時(shí)為新增的字段設(shè)置合理的默認(rèn)值這樣舊的調(diào)用者即使不提供該字段技能也能正常工作。對于要廢棄的字段可以先標(biāo)記為deprecated并在幾個(gè)版本后再移除。7.4 性能優(yōu)化隨著技能數(shù)量增加Agent的啟動(dòng)時(shí)間和內(nèi)存占用可能成為問題。懶加載Lazy Loading不要在Agent啟動(dòng)時(shí)一次性加載所有技能?？梢缘鹊侥硞€(gè)技能第一次被請求時(shí)再加載它。這可以通過上述的“發(fā)現(xiàn)”機(jī)制配合一個(gè)技能工廠類來實(shí)現(xiàn)。技能預(yù)熱對于初始化耗時(shí)較長的技能如加載大模型可以在系統(tǒng)空閑時(shí)或啟動(dòng)后異步進(jìn)行預(yù)熱。技能池化對于無狀態(tài)的技能可以創(chuàng)建多個(gè)實(shí)例放入池中處理并發(fā)請求。對于有狀態(tài)的技能需要仔細(xì)設(shè)計(jì)狀態(tài)管理。從Registry到Repository的轉(zhuǎn)變是AI Agent開發(fā)走向成熟和工程化的必經(jīng)之路。它要求我們不再把技能看作神秘的黑盒而是視為可構(gòu)建、可測試、可維護(hù)的軟件資產(chǎn)。這個(gè)過程起初可能會(huì)增加一些開發(fā)復(fù)雜度但它帶來的透明度、可控性和長期可維護(hù)性對于構(gòu)建可靠、可擴(kuò)展的AI Agent系統(tǒng)至關(guān)重要。我個(gè)人的體會(huì)是盡早擁抱這種“技能即代碼”的思維建立好技能開發(fā)、測試和部署的規(guī)范與流水線會(huì)在項(xiàng)目規(guī)模擴(kuò)大時(shí)為你省下無數(shù)排查和救火的時(shí)間。最后一個(gè)小建議從一個(gè)小而具體的技能開始用Repository模式完整地實(shí)踐一遍它的編寫、測試、部署和監(jiān)控流程你會(huì)對整個(gè)體系有更深刻的理解。 AI Agent技能開發(fā)：從注冊表到代碼庫的工程化演進(jìn)
1. 項(xiàng)目概述從注冊表到代碼庫的AI技能演進(jìn)最近和幾個(gè)做AI Agent的朋友聊天發(fā)現(xiàn)一個(gè)挺有意思的現(xiàn)象大家聊起某個(gè)Agent的“技能”時(shí)說法五花八門。有人說“我調(diào)用了GPT-4的API”有人說“我集成了一個(gè)天氣查詢的插件”還有人說“我寫了個(gè)自定義函數(shù)來處理數(shù)據(jù)”。這讓我意識(shí)到在AI Agent這個(gè)快速發(fā)展的領(lǐng)域里“技能”這個(gè)概念本身正經(jīng)歷著一場從“黑盒調(diào)用”到“白盒構(gòu)建”的深刻轉(zhuǎn)變。這背后的核心就是從“Registry”注冊表思維到“Repository”代碼庫思維的遷移。簡單來說以前我們更多是去一個(gè)中心化的“應(yīng)用商店”里尋找并安裝現(xiàn)成的、封裝好的能力模塊而現(xiàn)在我們越來越傾向于將技能視為一段可讀、可改、可版本控制的代碼存放在自己的“代碼倉庫”里進(jìn)行全生命周期的管理。這種轉(zhuǎn)變不是偶然的。早期的AI應(yīng)用尤其是基于大語言模型LLM的聊天機(jī)器人其“技能”往往依賴于模型本身的能力或者通過簡單的提示詞工程Prompt Engineering來引導(dǎo)。這時(shí)候技能是“內(nèi)嵌”在模型里的或者說是通過一個(gè)“注冊表”式的配置來聲明需要調(diào)用哪些外部API。比如你告訴Agent“如果用戶問天氣你就去調(diào)用某某天氣接口?！?這個(gè)調(diào)用邏輯和接口細(xì)節(jié)對開發(fā)者來說可能是不透明或難以深度定制的。但隨著Agent要處理的任務(wù)越來越復(fù)雜從簡單的問答發(fā)展到能執(zhí)行多步驟工作流、能進(jìn)行復(fù)雜決策的智能體這種“黑盒”模式就捉襟見肘了。我們需要技能具備更強(qiáng)的適應(yīng)性、可調(diào)試性和可維護(hù)性。因此“From Registry to Repository”這個(gè)標(biāo)題精準(zhǔn)地捕捉了當(dāng)前AI Agent開發(fā)的前沿實(shí)踐和未來趨勢。它探討的是AI Agent的技能是如何被“編寫”出來的而不僅僅是配置當(dāng)業(yè)務(wù)需求或環(huán)境發(fā)生變化時(shí)我們?nèi)绾巍斑m配”和調(diào)整這些技能更重要的是在長期的迭代和團(tuán)隊(duì)協(xié)作中我們?nèi)绾蜗窆芾碥浖?xiàng)目一樣有效地“維護(hù)”這些技能的代碼、文檔和依賴關(guān)系這不僅僅是技術(shù)工具的升級(jí)更是一種開發(fā)范式和工程思維的進(jìn)化。接下來我將結(jié)合一線的實(shí)戰(zhàn)經(jīng)驗(yàn)拆解這其中的核心環(huán)節(jié)、技術(shù)選型與避坑指南。2. 核心思路為何技能管理需要代碼庫思維要理解從Registry到Repository的轉(zhuǎn)變我們得先看看兩者在AI Agent上下文中的具體指代和局限性。2.1 Registry模式即插即用的便利與局限在傳統(tǒng)的軟件或早期AI框架中“Registry”是一個(gè)很常見的概念。你可以把它想象成手機(jī)的“應(yīng)用商店”或者Node.js的“npm registry”。它的核心特點(diǎn)是中心化索引和標(biāo)準(zhǔn)化封裝。在AI Agent領(lǐng)域一個(gè)技能Registry可能包含預(yù)定義的工具/函數(shù)列表例如一個(gè)WeatherTool其輸入、輸出格式、調(diào)用方式都被嚴(yán)格定義。插件描述文件比如一個(gè)plugin.json里面聲明了插件的名稱、版本、作者、所需權(quán)限和入口點(diǎn)。遠(yuǎn)程API端點(diǎn)技能的邏輯完全運(yùn)行在遠(yuǎn)端服務(wù)器Agent只通過一個(gè)標(biāo)準(zhǔn)的接口協(xié)議如OpenAI的Function Calling或更通用的OpenAPI/Swagger規(guī)范進(jìn)行調(diào)用。這種模式的優(yōu)勢非常明顯開箱即用開發(fā)者無需關(guān)心技能的內(nèi)部實(shí)現(xiàn)只需簡單配置即可集成。易于發(fā)現(xiàn)和共享有一個(gè)中心化的地方可以瀏覽和搜索所有可用技能。版本和依賴管理Registry可以管理不同版本的技能確保兼容性。然而在復(fù)雜的、生產(chǎn)級(jí)的AI Agent開發(fā)中Registry模式的短板日益凸顯黑盒操作調(diào)試?yán)щy當(dāng)技能執(zhí)行出錯(cuò)或結(jié)果不符合預(yù)期時(shí)你很難深入內(nèi)部邏輯進(jìn)行排查。你只能看到輸入和輸出中間的“思考”過程或數(shù)據(jù)處理邏輯是個(gè)謎。定制化成本高如果某個(gè)天氣查詢技能返回的數(shù)據(jù)結(jié)構(gòu)不符合你的業(yè)務(wù)需求你很難直接修改它。你可能需要聯(lián)系原作者或者自己從頭實(shí)現(xiàn)一個(gè)失去了復(fù)用價(jià)值。難以組合和編排復(fù)雜的任務(wù)往往需要多個(gè)技能協(xié)同工作。Registry中的技能通常是孤立的缺乏標(biāo)準(zhǔn)的、可編程的方式來定義它們之間的數(shù)據(jù)流和依賴關(guān)系。部署和網(wǎng)絡(luò)依賴依賴遠(yuǎn)程Registry和API端點(diǎn)會(huì)引入網(wǎng)絡(luò)延遲、單點(diǎn)故障和額外的運(yùn)維復(fù)雜度。在離線或內(nèi)網(wǎng)環(huán)境中更是無法使用。實(shí)操心得我在早期項(xiàng)目中使用過一些提供“技能市場”的AI平臺(tái)。初期確實(shí)很快就能搭出一個(gè)能對話、能查資料的Demo。但一旦想讓它根據(jù)查詢結(jié)果自動(dòng)生成一份報(bào)告或者把多個(gè)查詢結(jié)果進(jìn)行對比分析時(shí)就卡住了。因?yàn)槊總€(gè)技能都是獨(dú)立的“孤島”沒有統(tǒng)一的“膠水”代碼把它們粘合起來更別提在粘合過程中加入自己的業(yè)務(wù)邏輯了。2.2 Repository模式將技能視為一等公民的代碼Repository模式即“代碼庫”思維正是為了解決上述問題。它核心的觀點(diǎn)是一個(gè)AI Agent的技能本質(zhì)上是一段或一系列具有明確輸入、輸出、副作用和失敗處理的程序代碼。因此它應(yīng)該享受和普通軟件代碼一樣的待遇用代碼編寫使用Python、JavaScript等通用編程語言實(shí)現(xiàn)而不僅僅是JSON配置。進(jìn)行版本控制使用Git來管理技能的迭代歷史方便回滾和協(xié)作。本地化存儲(chǔ)與運(yùn)行技能代碼存放在項(xiàng)目自身的代碼倉庫中可以離線運(yùn)行減少外部依賴?？蓽y試、可調(diào)試可以像單元測試一樣對技能進(jìn)行測試可以用調(diào)試器逐步跟蹤執(zhí)行過程。可組合、可繼承可以通過函數(shù)調(diào)用、類繼承、依賴注入等標(biāo)準(zhǔn)的軟件工程方法構(gòu)建復(fù)雜的技能體系。在這種模式下一個(gè)“技能”可能是一個(gè)Python類它有一個(gè)execute方法也可能是一個(gè)遵循特定協(xié)議的異步函數(shù)。它的依賴、配置、工具函數(shù)都清晰地寫在代碼里。AI Agent框架如LangChain、AutoGen、Semantic Kernel的角色從一個(gè)“技能管理中心”轉(zhuǎn)變?yōu)橐粋€(gè)“技能執(zhí)行運(yùn)行時(shí)”負(fù)責(zé)加載這些代碼模塊并在合適的時(shí)機(jī)調(diào)用它們。這種轉(zhuǎn)變帶來的根本性好處透明度與可控性你對技能的每一個(gè)邏輯分支都了如指掌可以輕易地添加日志、修改邏輯或修復(fù)bug。深度定制與演進(jìn)你可以基于一個(gè)基礎(chǔ)的“數(shù)據(jù)查詢”技能派生出符合自己業(yè)務(wù)數(shù)據(jù)模型的“訂單查詢”技能實(shí)現(xiàn)高效的代碼復(fù)用。復(fù)雜的編排與流程你可以用代碼清晰地定義技能之間的執(zhí)行順序、條件判斷和循環(huán)實(shí)現(xiàn)真正的工作流自動(dòng)化。工程化協(xié)作團(tuán)隊(duì)可以通過Code Review、CI/CD流水線來保證技能代碼的質(zhì)量這與現(xiàn)代軟件開發(fā)流程無縫集成。3. 技能編寫從提示詞工程到可執(zhí)行代碼明確了技能即代碼的理念后我們來看看一個(gè)技能具體是如何被“編寫”出來的。這個(gè)過程已經(jīng)遠(yuǎn)遠(yuǎn)超出了寫一段提示詞Prompt的范疇。3.1 技能的基本構(gòu)成要素一個(gè)完整的、可維護(hù)的AI Agent技能通常包含以下幾個(gè)部分我們可以用一個(gè)“文件查詢”技能作為例子技能描述Skill Description這是技能的“元數(shù)據(jù)”用于讓LLM理解這個(gè)技能是干什么的。它通常是一段自然語言描述但會(huì)以結(jié)構(gòu)化的方式如文檔字符串嵌入在代碼中。class FileSearchSkill: 文件搜索技能。 根據(jù)用戶提供的關(guān)鍵詞在指定的本地目錄或知識(shí)庫中查找相關(guān)的文檔或代碼文件并返回匹配的文件路徑和摘要片段。 此技能支持基于文件內(nèi)容的模糊搜索和基于文件名的精確搜索。 輸入/輸出模式Input/Output Schema嚴(yán)格定義技能接受的參數(shù)和返回的數(shù)據(jù)結(jié)構(gòu)。這是技能與LLM或其他技能交互的“合約”。使用Pydantic這類庫來定義Schema是當(dāng)前的最佳實(shí)踐。from pydantic import BaseModel, Field from typing import List, Optional class FileSearchInput(BaseModel): query: str Field(..., description搜索關(guān)鍵詞) search_path: str Field(default./docs, description要搜索的根目錄路徑) max_results: int Field(default5, description返回的最大結(jié)果數(shù)) search_mode: str Field(defaultcontent, description搜索模式content內(nèi)容或 filename文件名) class SearchResult(BaseModel): file_path: str relevance_score: float preview_snippet: Optional[str] None class FileSearchOutput(BaseModel): results: List[SearchResult] total_hits: int核心執(zhí)行邏輯Execution Logic這是技能的“肌肉”包含了實(shí)際的算法和操作。它應(yīng)該只專注于完成技能描述的任務(wù)并且做好錯(cuò)誤處理。class FileSearchSkill: # ... 描述和Schema定義 ... async def execute(self, input_data: FileSearchInput) - FileSearchOutput: 執(zhí)行文件搜索。 import os from pathlib import Path import mmap import re search_root Path(input_data.search_path) if not search_root.exists(): raise ValueError(f搜索路徑不存在: {input_data.search_path}) results [] pattern re.compile(re.escape(input_data.query), re.IGNORECASE) # 遍歷文件 for file_path in search_root.rglob(*): if file_path.is_file(): try: relevance 0.0 snippet None if input_data.search_mode filename: # 文件名匹配 if pattern.search(file_path.name): relevance 1.0 else: # content mode # 內(nèi)容匹配 (簡化版生產(chǎn)環(huán)境需優(yōu)化) try: with open(file_path, r, encodingutf-8, errorsignore) as f: content f.read(10000) # 只讀前一部分以提高性能 matches list(pattern.finditer(content)) if matches: relevance min(len(matches) / 10, 1.0) # 簡單評分 # 獲取第一個(gè)匹配的上下文作為片段 first_match matches[0] start max(0, first_match.start() - 50) end min(len(content), first_match.end() 50) snippet content[start:end] except (UnicodeDecodeError, IOError): continue # 跳過無法讀取的文件 if relevance 0: results.append(SearchResult( file_pathstr(file_path), relevance_scorerelevance, preview_snippetsnippet )) except Exception as e: # 記錄錯(cuò)誤但繼續(xù)搜索其他文件 print(f處理文件 {file_path} 時(shí)出錯(cuò): {e}) continue # 按相關(guān)性排序并限制數(shù)量 results.sort(keylambda x: x.relevance_score, reverseTrue) final_results results[:input_data.max_results] return FileSearchOutput( resultsfinal_results, total_hitslen(results) )依賴聲明Dependencies技能所依賴的外部庫。這應(yīng)該明確寫在項(xiàng)目的requirements.txt或pyproject.toml中。# requirements.txt pydantic2.0 # 這個(gè)技能本身只用了標(biāo)準(zhǔn)庫但復(fù)雜技能可能需要聲明更多測試用例Tests用于驗(yàn)證技能在各種輸入下是否能正確工作。這是保證技能質(zhì)量的關(guān)鍵。# test_file_search_skill.py import pytest from your_skill_module import FileSearchSkill, FileSearchInput pytest.mark.asyncio async def test_file_search_by_filename(tmp_path): # 創(chuàng)建測試文件 test_file tmp_path / test_hello.txt test_file.write_text(Some content) (tmp_path / ignore.pdf).write_text(pdf content) skill FileSearchSkill() input_data FileSearchInput(queryhello, search_pathstr(tmp_path), search_modefilename) output await skill.execute(input_data) assert output.total_hits 1 assert output.results[0].file_path str(test_file) pytest.mark.asyncio async def test_file_search_empty_result(): skill FileSearchSkill() input_data FileSearchInput(querynonexistentkeyword, search_path/tmp) output await skill.execute(input_data) assert output.total_hits 0 assert len(output.results) 0注意事項(xiàng)在編寫執(zhí)行邏輯時(shí)一個(gè)常見的坑是過度依賴LLM。比如把本可以用確定性代碼快速完成的任務(wù)如上面的文件遍歷和正則匹配也交給LLM去做“思考”和“判斷”這會(huì)極大增加延遲、成本和不確定性。技能代碼應(yīng)該是確定性的、高效的。LLM更適合用于需要理解、推理、生成自然語言或處理非結(jié)構(gòu)化信息的環(huán)節(jié)。好的技能設(shè)計(jì)是“確定性代碼”和“LLM調(diào)用”的有機(jī)結(jié)合。3.2 與LLM的交互模式從硬編碼到動(dòng)態(tài)規(guī)劃技能代碼寫好了如何讓LLM知道在什么時(shí)候、用什么參數(shù)去調(diào)用它呢這里有幾種主流模式函數(shù)調(diào)用Function Calling這是最直接的方式。你將技能的Schema輸入格式提供給LLM。當(dāng)LLM在對話中判斷需要調(diào)用該技能時(shí)它會(huì)輸出一個(gè)結(jié)構(gòu)化的調(diào)用請求包含函數(shù)名和參數(shù)。然后由你的程序來執(zhí)行對應(yīng)的技能代碼。OpenAI的API、Anthropic的Claude都原生支持此功能。優(yōu)點(diǎn)標(biāo)準(zhǔn)化與模型集成好。缺點(diǎn)調(diào)用決策完全由LLM做出有時(shí)會(huì)“幻覺”出不需要的調(diào)用或參數(shù)錯(cuò)誤。智能體框架封裝Agent Framework使用LangChain、AutoGen等框架。這些框架提供了更高層次的抽象比如Tool類。你將自己的技能代碼包裝成一個(gè)Tool實(shí)例然后交給框架的Agent去管理。框架會(huì)處理技能的描述、調(diào)用格式轉(zhuǎn)換以及和LLM的交互。from langchain.tools import Tool from langchain.agents import initialize_agent, AgentType from langchain.llms import OpenAI # 將我們的技能包裝成LangChain Tool file_search_tool Tool( nameFileSearch, funclambda q: file_search_skill.execute(q), # 這里需要適配函數(shù)簽名 description根據(jù)關(guān)鍵詞搜索本地文件。輸入應(yīng)為一個(gè)搜索關(guān)鍵詞字符串。 ) llm OpenAI(temperature0) agent initialize_agent([file_search_tool], llm, agentAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue) agent.run(幫我找一下所有關(guān)于‘預(yù)算’的文檔)優(yōu)點(diǎn)開發(fā)快生態(tài)豐富提供了記憶、鏈?zhǔn)秸{(diào)用等高級(jí)功能。缺點(diǎn)框架本身有一定學(xué)習(xí)成本且可能將一些底層細(xì)節(jié)隱藏起來不利于深度定制和調(diào)試。工作流引擎驅(qū)動(dòng)Workflow Engine在更復(fù)雜的場景下技能的調(diào)用不是由LLM實(shí)時(shí)決定的而是由一個(gè)預(yù)定義的工作流如基于YAML或代碼的DAG來驅(qū)動(dòng)。LLM可能只作為工作流中某個(gè)節(jié)點(diǎn)的“處理器”。Apache Airflow、Prefect或?qū)锳I設(shè)計(jì)的框架如Semantic Kernel的“Planner”概念就屬于此類。優(yōu)點(diǎn)流程確定可預(yù)測性強(qiáng)適合復(fù)雜、多步驟的自動(dòng)化任務(wù)。缺點(diǎn)靈活性較低無法處理工作流之外的突發(fā)情況。我的選擇建議是對于大多數(shù)應(yīng)用從函數(shù)調(diào)用模式開始是最樸實(shí)、最可控的。當(dāng)你需要快速構(gòu)建原型或利用大量社區(qū)工具時(shí)智能體框架是很好的選擇。當(dāng)你需要構(gòu)建穩(wěn)定、可監(jiān)控的生產(chǎn)級(jí)自動(dòng)化流程時(shí)工作流引擎模式更值得考慮。無論哪種模式技能的底層實(shí)現(xiàn)都應(yīng)該是獨(dú)立的、可測試的代碼模塊。4. 技能適配讓技能靈活應(yīng)對變化業(yè)務(wù)需求、數(shù)據(jù)格式、外部API總是在變。一個(gè)寫死的技能很快就會(huì)過時(shí)。因此“適配”能力是技能生命力的關(guān)鍵。4.1 參數(shù)化與配置驅(qū)動(dòng)最基礎(chǔ)的適配方式是將技能中可能變化的部分提取為參數(shù)或配置。這聽起來簡單但在設(shè)計(jì)時(shí)需要前瞻性。環(huán)境變量與配置文件數(shù)據(jù)庫連接字符串、API密鑰、默認(rèn)路徑等絕對不應(yīng)該硬編碼在技能代碼里。應(yīng)該通過配置文件如config.yaml或環(huán)境變量注入。# config.yaml skills: file_search: default_search_path: ./data/docs max_file_size_mb: 10 allowed_extensions: [.txt, .md, .pdf]# 技能初始化時(shí)讀取配置 import yaml with open(config.yaml) as f: config yaml.safe_load(f) search_skill FileSearchSkill(default_pathconfig[skills][file_search][default_search_path])動(dòng)態(tài)參數(shù)注入技能的某些行為可能需要根據(jù)運(yùn)行時(shí)上下文決定。例如一個(gè)“數(shù)據(jù)查詢”技能查詢的數(shù)據(jù)庫表名可能由用戶輸入或上游技能的結(jié)果決定。這時(shí)技能的執(zhí)行方法就應(yīng)該接受這些動(dòng)態(tài)參數(shù)。4.2 技能模板與繼承當(dāng)有一類技能功能相似但細(xì)節(jié)不同時(shí)使用面向?qū)ο蟮睦^承或組合模式來創(chuàng)建“技能模板”是高效的做法。假設(shè)我們有多種“通知”技能郵件通知、Slack通知、企業(yè)微信通知。它們核心邏輯都是“發(fā)送一條消息”但具體協(xié)議和參數(shù)不同。from abc import ABC, abstractmethod from pydantic import BaseModel class NotificationMessage(BaseModel): title: str body: str priority: str normal class NotificationSkill(ABC): 通知技能抽象基類 abstractmethod async def send(self, message: NotificationMessage) - bool: 發(fā)送通知返回是否成功 pass class EmailNotificationSkill(NotificationSkill): def __init__(self, smtp_server, sender_email): self.smtp_server smtp_server self.sender sender_email async def send(self, message: NotificationMessage) - bool: # 實(shí)現(xiàn)具體的郵件發(fā)送邏輯 print(f[Email] {message.title}: {message.body}) return True class SlackNotificationSkill(NotificationSkill): def __init__(self, webhook_url): self.webhook_url webhook_url async def send(self, message: NotificationMessage) - bool: # 實(shí)現(xiàn)具體的Slack Webhook調(diào)用邏輯 print(f[Slack] {message.title}: {message.body}) return True # 使用時(shí)可以根據(jù)配置動(dòng)態(tài)選擇技能 notification_config {type: slack, webhook_url: https://hooks.slack.com/...} if notification_config[type] slack: notifier SlackNotificationSkill(notification_config[webhook_url]) elif notification_config[type] email: notifier EmailNotificationSkill(...) # ... 調(diào)用 notifier.send(message)這樣當(dāng)需要新增一個(gè)“釘釘通知”技能時(shí)你只需要繼承NotificationSkill并實(shí)現(xiàn)send方法即可其他調(diào)用代碼無需修改。這符合“開閉原則”。4.3 利用LLM進(jìn)行動(dòng)態(tài)適配這是AI Agent技能獨(dú)有的強(qiáng)大適配能力讓LLM來幫助技能理解并處理未預(yù)見的輸入格式或需求。場景你有一個(gè)“查詢數(shù)據(jù)庫”技能它期望的輸入是一個(gè)結(jié)構(gòu)化的{table_name: “users”, filter: “age 30”}。但用戶用自然語言說“幫我找一下所有年齡超過30歲的用戶”。傳統(tǒng)做法你需要寫一個(gè)復(fù)雜的NLU自然語言理解模塊來解析這句話轉(zhuǎn)化為技能所需的參數(shù)。這很難覆蓋所有表達(dá)方式。LLM適配做法在技能執(zhí)行前插入一個(gè)“參數(shù)解析”步驟。這個(gè)步驟本身可以看作一個(gè)微型的、專用的LLM調(diào)用。class DatabaseQuerySkill: async def execute(self, natural_language_query: str) - QueryResult: # 第一步用LLM將自然語言轉(zhuǎn)換為結(jié)構(gòu)化查詢參數(shù) parameter_prompt f 你將用戶的自然語言查詢轉(zhuǎn)換為數(shù)據(jù)庫查詢參數(shù)。 數(shù)據(jù)庫有表users, products, orders。 輸出必須是JSON格式{{table_name: ..., filter_condition: SQL WHERE clause片段}} 用戶查詢{natural_language_query} structured_params await llm_client.generate_json(parameter_prompt) # 假設(shè) structured_params {table_name: users, filter_condition: age 30} # 第二步用解析后的參數(shù)執(zhí)行實(shí)際的、安全的數(shù)據(jù)庫查詢 return await self._run_actual_query(structured_params[table_name], structured_params[filter_condition])這里L(fēng)LM充當(dāng)了一個(gè)“萬能適配器”將非結(jié)構(gòu)化的輸入適配到技能的結(jié)構(gòu)化接口上。但這里有一個(gè)至關(guān)重要的安全原則永遠(yuǎn)不要讓LLM直接生成或執(zhí)行SQL語句上例中LLM只生成一個(gè)filter_condition的描述如“age 30”然后由你技能中確定性的代碼將這個(gè)描述安全地轉(zhuǎn)換為參數(shù)化查詢從而防止SQL注入攻擊。避坑指南LLM動(dòng)態(tài)適配雖然強(qiáng)大但會(huì)引入額外延遲和不確定性。不要濫用。只在對輸入格式靈活性要求極高且確定性解析規(guī)則過于復(fù)雜或無法窮舉時(shí)才使用。并且一定要在LLM的輸出后加上嚴(yán)格的驗(yàn)證和凈化層確保其輸出符合預(yù)期格式和業(yè)務(wù)安全規(guī)則。5. 技能維護(hù)像管理軟件一樣管理技能將技能代碼化后維護(hù)就自然而然地可以套用成熟的軟件工程實(shí)踐。5.1 版本控制與協(xié)作每個(gè)技能都應(yīng)該是一個(gè)獨(dú)立的代碼模塊存放在Git倉庫中。這帶來了諸多好處變更歷史清晰記錄誰、在什么時(shí)候、為什么修改了技能邏輯。當(dāng)新版本技能出現(xiàn)問題時(shí)可以快速git bisect定位引入bug的提交。分支策略可以為新功能如“支持全文高亮”創(chuàng)建特性分支feat/highlight開發(fā)測試完成后合并到主分支?？梢詣?chuàng)建hotfix分支緊急修復(fù)線上問題。Code Review團(tuán)隊(duì)成員對技能的修改發(fā)起Pull Request其他人可以審查代碼邏輯、安全性、性能并提出建議。這是保證技能代碼質(zhì)量的第一道防線。與CI/CD集成這是Repository模式相比Registry模式最大的運(yùn)維優(yōu)勢。5.2 持續(xù)集成與持續(xù)部署CI/CD為你的技能倉庫搭建CI/CD流水線可以實(shí)現(xiàn)自動(dòng)化測試和部署。一個(gè)典型的.github/workflows/test-skills.yml可能如下name: Test AI Skills on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | pip install -r requirements.txt pip install pytest pytest-asyncio - name: Run unit tests run: | pytest tests/ -v - name: Run integration tests (if any) run: | python -m pytest tests/integration/ --tbshort - name: Lint code run: | pip install black isort mypy black --check . isort --check-only . mypy src/這個(gè)流水線會(huì)在每次代碼推送或PR時(shí)自動(dòng)運(yùn)行確保單元測試通過。代碼風(fēng)格符合規(guī)范Black, isort。類型注解正確mypy。對于部署你可以有另一個(gè)流水線當(dāng)代碼合并到main分支后自動(dòng)將技能包構(gòu)建成Docker鏡像推送到你的私有容器倉庫并更新運(yùn)行中的AI Agent服務(wù)。5.3 測試策略技能的測試需要分層進(jìn)行測試類型測試內(nèi)容工具示例目的單元測試測試技能內(nèi)部函數(shù)的確定性邏輯。pytest,unittest驗(yàn)證代碼邏輯正確邊界條件處理得當(dāng)。集成測試測試技能與真實(shí)依賴如數(shù)據(jù)庫、外部API的交互。pytest 測試數(shù)據(jù)庫/ Mock Server驗(yàn)證技能在真實(shí)環(huán)境中的連通性和基本功能。契約測試測試技能的輸入/輸出Schema是否穩(wěn)定。pytest Pydantic Schema防止Schema的意外變更破壞上游調(diào)用者。LLM交互測試測試技能描述是否能被LLM正確理解并調(diào)用。使用LLM的本地小模型如llama.cpp或Mock驗(yàn)證技能元數(shù)據(jù)的有效性。端到端測試將技能放入一個(gè)完整的Agent中測試從用戶輸入到最終輸出的全過程。腳本模擬用戶對話驗(yàn)證技能在完整工作流中的表現(xiàn)。一個(gè)高級(jí)技巧錄制與回放Record and Replay。對于涉及LLM調(diào)用的技能其輸出具有非確定性。測試時(shí)你可以將第一次運(yùn)行LLM時(shí)得到的響應(yīng)假設(shè)它是正確的錄制下來保存為“金標(biāo)準(zhǔn)”Golden Master。在后續(xù)的測試中直接回放這個(gè)錄制的響應(yīng)而不是真實(shí)調(diào)用LLM。這保證了測試的確定性和速度同時(shí)驗(yàn)證了技能處理LLM響應(yīng)的邏輯是否正確。工具如vcr.py可以幫助實(shí)現(xiàn)這一點(diǎn)。5.4 監(jiān)控與可觀測性線上運(yùn)行的技能需要被監(jiān)控。你需要知道調(diào)用量每個(gè)技能被調(diào)用的頻率。成功率/錯(cuò)誤率技能執(zhí)行成功和失敗的比例。延遲技能從被調(diào)用到返回結(jié)果所花費(fèi)的時(shí)間。關(guān)鍵業(yè)務(wù)指標(biāo)例如一個(gè)“生成報(bào)告”技能可以監(jiān)控其生成報(bào)告的平均字?jǐn)?shù)、被用戶采納的比例等。實(shí)現(xiàn)上可以在每個(gè)技能的execute方法開始和結(jié)束時(shí)打點(diǎn)將數(shù)據(jù)發(fā)送到監(jiān)控系統(tǒng)如Prometheus Grafana或日志系統(tǒng)如ELK Stack。import time import logging from prometheus_client import Counter, Histogram SKILL_CALL_COUNT Counter(skill_calls_total, Total skill calls, [skill_name]) SKILL_DURATION Histogram(skill_duration_seconds, Skill execution duration, [skill_name]) SKILL_ERROR_COUNT Counter(skill_errors_total, Total skill errors, [skill_name]) class InstrumentedFileSearchSkill(FileSearchSkill): async def execute(self, input_data: FileSearchInput) - FileSearchOutput: SKILL_CALL_COUNT.labels(skill_namefile_search).inc() start_time time.time() try: result await super().execute(input_data) duration time.time() - start_time SKILL_DURATION.labels(skill_namefile_search).observe(duration) return result except Exception as e: SKILL_ERROR_COUNT.labels(skill_namefile_search).inc() logging.error(fFileSearchSkill failed: {e}, exc_infoTrue) raise6. 架構(gòu)模式與工具選型在實(shí)際項(xiàng)目中組織大量的技能代碼需要一定的架構(gòu)設(shè)計(jì)。這里介紹兩種常見模式。6.1 單體倉庫 vs 多倉庫單體倉庫Monorepo將所有技能的代碼放在同一個(gè)Git倉庫中。優(yōu)點(diǎn)依賴管理簡單代碼共享和重構(gòu)方便容易保證跨技能的一致性。缺點(diǎn)倉庫體積會(huì)變得很大權(quán)限控制較粗粒度構(gòu)建和測試可能變慢。適用場景技能數(shù)量不多幾十個(gè)以內(nèi)團(tuán)隊(duì)規(guī)模較小技能之間耦合緊密。多倉庫Polyrepo每個(gè)技能或一組緊密相關(guān)的技能擁有自己獨(dú)立的Git倉庫。優(yōu)點(diǎn)權(quán)限清晰獨(dú)立部署和版本化構(gòu)建和測試隔離性好。缺點(diǎn)跨技能共享通用代碼如工具類、基礎(chǔ)Schema較麻煩依賴版本容易沖突。適用場景技能數(shù)量眾多由不同團(tuán)隊(duì)負(fù)責(zé)技能間相對獨(dú)立。我的建議對于大多數(shù)中小型AI Agent項(xiàng)目從單體倉庫開始是更優(yōu)的選擇。它極大地簡化了初期的開發(fā)、測試和依賴管理?？梢允褂孟駊oetry或uv這樣的現(xiàn)代Python包管理工具在單體倉庫內(nèi)管理多個(gè)技能包的虛擬環(huán)境。6.2 技能發(fā)現(xiàn)與加載機(jī)制當(dāng)技能都作為代碼模塊存在后Agent如何動(dòng)態(tài)地發(fā)現(xiàn)和加載它們一個(gè)常見的模式是使用“插件系統(tǒng)”或“發(fā)現(xiàn)協(xié)議”?；谌肟邳c(diǎn)的發(fā)現(xiàn)Entry Points這是Python打包標(biāo)準(zhǔn)的一部分。每個(gè)技能包在pyproject.toml中聲明自己的入口點(diǎn)。# 在技能的 pyproject.toml 中 [project.entry-points.ai_agent.skills] file_search my_skills.file_search:FileSearchSkill data_plotter my_skills.visualization:DataPlotterSkill在Agent主程序中可以使用importlib.metadata來發(fā)現(xiàn)所有已安裝的技能。from importlib.metadata import entry_points def load_skills(): skills {} discovered_skills entry_points(groupai_agent.skills) for ep in discovered_skills: skill_class ep.load() # 動(dòng)態(tài)加載類 skills[ep.name] skill_class() return skills這種方式非常優(yōu)雅技能包可以通過pip install安裝Agent自動(dòng)發(fā)現(xiàn)?；谀夸洅呙璧陌l(fā)現(xiàn)更簡單直接的方式。約定一個(gè)特定的目錄如./skillsAgent啟動(dòng)時(shí)掃描該目錄下所有符合命名規(guī)范的Python文件如*_skill.py并自動(dòng)導(dǎo)入其中定義的技能類。import importlib.util from pathlib import Path def load_skills_from_dir(skills_dir: Path): skills {} for file_path in skills_dir.glob(*_skill.py): module_name file_path.stem spec importlib.util.spec_from_file_location(module_name, file_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) # 假設(shè)每個(gè)模塊都有一個(gè) export_skill 變量指向技能實(shí)例 if hasattr(module, export_skill): skills[module_name] module.export_skill return skills這種方式無需安裝適合快速開發(fā)和調(diào)試。6.3 工具鏈推薦包/依賴管理Poetry或UV。它們能很好地管理項(xiàng)目依賴、虛擬環(huán)境和打包發(fā)布特別是對于單體倉庫內(nèi)多包的情況。測試框架Pytest。功能強(qiáng)大插件生態(tài)豐富如pytest-asyncio用于異步測試。代碼風(fēng)格與質(zhì)量Black格式化、isort導(dǎo)入排序、Flake8或Ruff代碼檢查、mypy靜態(tài)類型檢查。將這些工具集成到CI和預(yù)提交鉤子pre-commit中。Schema定義與驗(yàn)證Pydantic V2。幾乎是Python生態(tài)中定義數(shù)據(jù)模型和驗(yàn)證輸入輸出的不二之選性能好功能全。文檔生成MkDocs或Sphinx。為你的技能代碼庫生成漂亮的API文檔。技能的文檔字符串Docstring就是最好的文檔來源。容器化Docker。將你的Agent及其所有技能依賴打包成鏡像確保環(huán)境一致性。7. 常見問題與實(shí)戰(zhàn)避坑在實(shí)際開發(fā)和運(yùn)維中你會(huì)遇到各種各樣的問題。以下是一些典型問題及其解決思路。7.1 技能執(zhí)行失敗的處理技能可能因?yàn)榫W(wǎng)絡(luò)超時(shí)、外部API變化、資源不足等原因失敗。一個(gè)健壯的Agent不能因?yàn)橐粋€(gè)技能失敗就整體崩潰。重試機(jī)制對于暫時(shí)性錯(cuò)誤如網(wǎng)絡(luò)抖動(dòng)可以實(shí)現(xiàn)指數(shù)退避的重試邏輯。import asyncio from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type retry( stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10), retryretry_if_exception_type((TimeoutError, IOError)) ) async def call_unstable_api(self, param): # 調(diào)用可能不穩(wěn)定的外部API ...優(yōu)雅降級(jí)當(dāng)主要技能失敗時(shí)提供一個(gè)備選方案。例如高清圖片生成失敗時(shí)返回一個(gè)低清版本或一個(gè)提示信息。超時(shí)控制為每個(gè)技能設(shè)置執(zhí)行超時(shí)防止其長時(shí)間阻塞Agent。import asyncio async def execute_with_timeout(skill, input_data, timeout30): try: return await asyncio.wait_for(skill.execute(input_data), timeouttimeout) except asyncio.TimeoutError: return {error: Skill execution timed out}錯(cuò)誤信息上拋將技能失敗的具體原因而非堆棧跟蹤以結(jié)構(gòu)化的方式返回給LLM或用戶讓LLM決定下一步該做什么如重試、換一種方式、向用戶道歉。7.2 技能間的依賴與循環(huán)調(diào)用當(dāng)技能A依賴技能B的結(jié)果而技能B又可能調(diào)用技能A時(shí)就形成了循環(huán)依賴可能導(dǎo)致死循環(huán)或遞歸過深。依賴注入明確聲明技能的依賴關(guān)系。在初始化時(shí)注入而不是在運(yùn)行時(shí)動(dòng)態(tài)查找。這使依賴關(guān)系清晰也便于測試時(shí)替換Mock對象。有向無環(huán)圖DAG檢查如果你用工作流引擎來編排技能大多數(shù)引擎會(huì)自動(dòng)檢測循環(huán)依賴。如果是LLM動(dòng)態(tài)規(guī)劃則需要在技能描述中明確說明其功能邊界并設(shè)置最大調(diào)用深度限制。上下文管理設(shè)計(jì)一個(gè)全局或會(huì)話級(jí)的“上下文”對象存儲(chǔ)已執(zhí)行技能的結(jié)果。當(dāng)一個(gè)技能需要另一個(gè)技能的結(jié)果時(shí)先從上下文中查找避免重復(fù)執(zhí)行。同時(shí)上下文也可以用于檢測循環(huán)如果發(fā)現(xiàn)當(dāng)前技能所需的輸入正在等待自己執(zhí)行的結(jié)果。7.3 技能的版本管理與兼容性當(dāng)技能接口Schema發(fā)生變化時(shí)如何保證已有的Agent工作流不中斷語義化版本對技能包使用語義化版本號(hào)如1.2.3。MAJOR版本號(hào)增加表示有不兼容的API變更MINOR版本號(hào)增加表示新增了向后兼容的功能PATCH版本號(hào)增加表示做了向后兼容的問題修復(fù)。多版本共存在Agent中可以同時(shí)加載同一個(gè)技能的不同主版本如FileSearchSkillV1和FileSearchSkillV2。通過技能名稱或元數(shù)據(jù)來區(qū)分。舊的Agent工作流繼續(xù)調(diào)用V1新的則可以調(diào)用V2。Schema演化與默認(rèn)值使用Pydantic時(shí)為新增的字段設(shè)置合理的默認(rèn)值這樣舊的調(diào)用者即使不提供該字段技能也能正常工作。對于要廢棄的字段可以先標(biāo)記為deprecated并在幾個(gè)版本后再移除。7.4 性能優(yōu)化隨著技能數(shù)量增加Agent的啟動(dòng)時(shí)間和內(nèi)存占用可能成為問題。懶加載Lazy Loading不要在Agent啟動(dòng)時(shí)一次性加載所有技能?？梢缘鹊侥硞€(gè)技能第一次被請求時(shí)再加載它。這可以通過上述的“發(fā)現(xiàn)”機(jī)制配合一個(gè)技能工廠類來實(shí)現(xiàn)。技能預(yù)熱對于初始化耗時(shí)較長的技能如加載大模型可以在系統(tǒng)空閑時(shí)或啟動(dòng)后異步進(jìn)行預(yù)熱。技能池化對于無狀態(tài)的技能可以創(chuàng)建多個(gè)實(shí)例放入池中處理并發(fā)請求。對于有狀態(tài)的技能需要仔細(xì)設(shè)計(jì)狀態(tài)管理。從Registry到Repository的轉(zhuǎn)變是AI Agent開發(fā)走向成熟和工程化的必經(jīng)之路。它要求我們不再把技能看作神秘的黑盒而是視為可構(gòu)建、可測試、可維護(hù)的軟件資產(chǎn)。這個(gè)過程起初可能會(huì)增加一些開發(fā)復(fù)雜度但它帶來的透明度、可控性和長期可維護(hù)性對于構(gòu)建可靠、可擴(kuò)展的AI Agent系統(tǒng)至關(guān)重要。我個(gè)人的體會(huì)是盡早擁抱這種“技能即代碼”的思維建立好技能開發(fā)、測試和部署的規(guī)范與流水線會(huì)在項(xiàng)目規(guī)模擴(kuò)大時(shí)為你省下無數(shù)排查和救火的時(shí)間。最后一個(gè)小建議從一個(gè)小而具體的技能開始用Repository模式完整地實(shí)踐一遍它的編寫、測試、部署和監(jiān)控流程你會(huì)對整個(gè)體系有更深刻的理解。