AI Agent：讓Skill有記憶、角色和主動性)
如果你刷技術(shù)圈比較勤應(yīng)該已經(jīng)注意到AI Agent這個詞快被聊爛了。但說實話大部分談 Agent 的文章都在講概念、講架構(gòu)圖真正能跟著一步步落地的實操分享反而少。我自己從最早寫死 Prompt 玩大模型到做成有狀態(tài)、有技能包、能自己決定下一步動作的東西中間踩的坑比想象中多得多。這篇文章我就用完全手把手的方式來拆一遍標(biāo)題是“手把手書寫你的第一個 AI Agent當(dāng) Skill 有了記憶、角色和主動性”重點就在記憶、角色、主動性這三個詞上。這三個詞恰好是普通 Prompt 封裝和真正的 Agent 之間最本質(zhì)的分界線。我不會只貼一段代碼給你看而是把每一步背后的設(shè)計依據(jù)、取舍邏輯、容易忽略的細(xì)節(jié)全部鋪開講?？赐曛竽銘?yīng)該能在自己的項目里復(fù)現(xiàn)一個帶 Skill 機(jī)制、有短期長期記憶、有人設(shè)約束、具備基本主動調(diào)度能力的 Agent 雛形。這玩意不是玩具很多商業(yè)化產(chǎn)品的底座也就是這么長的。1. 先把核心問題聊透沒有 Skill 的 Agent和大模型套殼有什么區(qū)別1.1 痛點來自 Prompt 工程的三個天花板我先說一個場景你自己體會一下是不是遇到類似情況。假設(shè)你想讓模型扮演一個“嵌入式開發(fā)助手”幫用戶分析日志、生成寄存器配置、檢查 GPIO 初始化代碼。如果只是用 Prompt 把角色設(shè)定寫死再扔給模型你會遇到三個類問題。第一模型調(diào)用的“技能”全藏在提示詞里。不管你是做日志分析、DTS 修改還是 build 錯誤排查本質(zhì)都是上下文模板拼接。日志格式一變Prompt 就得改。更難受的是當(dāng)任務(wù)鏈路長起來比如“分析日志 - 定位外設(shè)異常 - 生成補丁 - 跑靜態(tài)檢查”這個流程邏輯是代碼里寫死的模型根本沒有自主規(guī)劃的空間。第二每次都像失憶一樣。上一步剛確認(rèn)完芯片型號是ESP32-S3下一步讓它生成初始化代碼時它又開始問你“請?zhí)峁┠男酒吞枴?。對話歷史不是沒傳而是傳了也不一定能穩(wěn)定約束后續(xù)決策尤其當(dāng)上下文超過一定長度早期關(guān)鍵信息被稀釋得很厲害。第三模型沒有主動性。它以“提問-回答”的單輪范式活著你問一句它回一句。真正干活的時候你希望它能自己決定“我需要先看一下寄存器手冊里的說明再決定怎么改配置”然后真的去調(diào)工具、讀文檔、嘗試、校驗、出結(jié)果。這已經(jīng)不是提示詞能解決的范圍了。這三個痛點是環(huán)環(huán)相扣的。技能碎片化導(dǎo)致能力邊界模糊記憶缺失導(dǎo)致決策質(zhì)量低主動性缺失導(dǎo)致整個系統(tǒng)只能停在“高級聊天機(jī)器人”層面。而圍繞Skill構(gòu)建的自定義 Agent 架構(gòu)恰好就是沖著這三點去的。1.2 Skill 和 Agent 的關(guān)系不是包含而是“能力的具象化”這里要先厘清一個概念。很多人把Skill理解成“給 Agent 準(zhǔn)備的一套提示詞模板”這太窄了。還有一種說法是 Skill 就是外部工具函數(shù)這也不夠。我傾向把 Skill 看作是“Agent 可以調(diào)用的一組帶描述、帶輸入輸出契約、帶執(zhí)行邏輯、帶狀態(tài)讀寫權(quán)限的能力單元”。舉個好消化的類比。把 Agent 想象成一個真人新員工。這個人聰明、理解力強(qiáng)但他剛?cè)肼毷裁礃I(yè)務(wù)都不會。他需要幾樣?xùn)|西才能干活崗位說明書角色定位、工作手冊Skill 定義、記事本記憶系統(tǒng)、以及主管授權(quán)他主動推進(jìn)任務(wù)主動性。所以 Skill 不只是“知識”它還包含行為邏輯。在這個框架下Agent 是執(zhí)行者Skill 是執(zhí)行者可選擇的行為包。Agent 為什么要“有” Skill因為 Skill 把模型不可控的自然語言能力轉(zhuǎn)化為可控的、可復(fù)用的、帶約束的模塊。模型負(fù)責(zé)判斷“我現(xiàn)在該調(diào)用哪個 Skill、如何組合”Skill 負(fù)責(zé)把模型意圖翻譯成確定性邏輯。這個分工是 Agent 架構(gòu)里最核心的一層。2. 設(shè)計 Agent 的四個要素記憶、角色、主動性、工具調(diào)用2.1 記憶機(jī)制不只是塞上下文而是做狀態(tài)分層標(biāo)題里第一個關(guān)鍵詞是“記憶”。我給你一個簡化的記憶分層模型。短期記憶當(dāng)前任務(wù)上下文里產(chǎn)生的關(guān)鍵信息比如用戶剛剛指定了項目目錄、選了某種通信協(xié)議。放內(nèi)存或會話變量里即可。長期記憶跨會話保留的偏好、歷史結(jié)論、常用配置。需要持久化輕量方案是 SQLite 或本地 JSON 文件重型方案可以上向量數(shù)據(jù)庫。工作記憶Agent 當(dāng)前的思考草稿、中間結(jié)果、計劃清單。這一層容易被忽略但它決定了 Agent 能不能“邊干邊記”。實現(xiàn)上有一個非常實用的設(shè)計模式把記憶封裝成 Agent 可讀寫的工具而不是直接改系統(tǒng) Prompt。也就是說模型通過調(diào)用“寫入記憶”這個動作來留存信息通過“檢索記憶”這個動作來獲取歷史相關(guān)內(nèi)容。這樣做最大的好處是記憶的存取時機(jī)由模型根據(jù)任務(wù)自主決定而不是每一輪都把所有歷史無腦拼進(jìn) Prompt。這個設(shè)計有直接好處上下文長度可管理關(guān)鍵信息不會被沖散跨會話體驗?zāi)苷嬲纬?。我在自己項目里?SQLite 做了個極簡版字段就四個記憶編碼、記憶類型、記憶內(nèi)容、創(chuàng)建時間。Agent 檢索時按關(guān)鍵詞匹配和創(chuàng)建時間排序取前幾條效果已經(jīng)比硬塞上下文好非常多。2.2 角色設(shè)定不是“你是一個助手”這么簡單角色這個詞很多人做得太淺。早期我寫 Agent角色設(shè)定就是一句“你是一位資深嵌入式工程師”完事。后來發(fā)現(xiàn)這個“角色”對模型行為的約束非常弱模型照樣會一本正經(jīng)胡說八道照樣會在不確定的時候亂猜。真正有效的角色設(shè)定應(yīng)該包含三層信息。第一層是身份邊界你能做什么不能做什么。比如“你是代碼評審助手只負(fù)責(zé)庫函數(shù)層面的靜態(tài)分析不做板級硬件調(diào)試”。第二層是輸出風(fēng)格約束匯報的表達(dá)習(xí)慣、是否給出代碼示例、遇到不確定時是明說還是猜測。第三層是價值觀與安全邊界涉及到可能破壞系統(tǒng)的命令必須二次詢問。這三層里身份邊界和風(fēng)格約束很多人會寫但安全邊界很少被重視。實操中安全邊界最好的實現(xiàn)方式不是寫死在角色 Prompt 里而是配備“攔截型 Skill”。比如你定義了一個執(zhí)行Shell命令的 Skill那這個 Skill 內(nèi)部必須帶危險命令校驗邏輯而不是靠模型自覺。角色負(fù)責(zé)“不主動越界”Skill 負(fù)責(zé)“越界也執(zhí)行不了”。兩道閘門都裝上系統(tǒng)才可靠。2.3 主動性從響應(yīng)式到任務(wù)自治的機(jī)制躍遷主動性是這三個詞里最容易被誤解的。有人覺得主動 Agent 不等人問自己開口說“我來幫您……”這其實只是表面的主動。真正的主動性是任務(wù)調(diào)度上的自治能力當(dāng)用戶給定一個模糊目標(biāo)Agent 能自行拆解子任務(wù)、決定子任務(wù)的執(zhí)行順序、處理執(zhí)行中出現(xiàn)的異常、甚至發(fā)現(xiàn)前置信息不足時主動查資料或提問澄清。這套機(jī)制在工程上是靠“循環(huán)”實現(xiàn)的。經(jīng)典的結(jié)構(gòu)是Agent Loop大致流程我整理成下面這個邏輯循環(huán)開始 1. 從任務(wù)隊列中取出當(dāng)前最優(yōu)先的子任務(wù) 2. 模型根據(jù)「當(dāng)前狀態(tài) 可用 Skill 列表 記憶摘要」決定下一步動作 3. 如果動作是調(diào)用 Skill - 執(zhí)行 - 把結(jié)果寫回狀態(tài) - 更新記憶 - 回到第 1 步 4. 如果動作是回復(fù)用戶 - 輸出最終結(jié)果 - 結(jié)束循環(huán) 5. 如果動作是請求更多信息 - 拋出澄清問題 - 暫停循環(huán)等待用戶輸入這里最關(guān)鍵的技術(shù)細(xì)節(jié)是第 2 步。模型如何知道有哪些 Skill 可用靠的不是它在訓(xùn)練數(shù)據(jù)里見過而是你把 Skill 的名字、用途、參數(shù)說明喂給了它。每輪迭代前Agent 都會拿著“當(dāng)前任務(wù) Skill 清單”去決策相當(dāng)于每走一步都重新規(guī)劃一次。這樣的設(shè)計遠(yuǎn)比“預(yù)設(shè)好整個任務(wù)鏈路然后順序執(zhí)行”更魯棒。具體到實現(xiàn)有兩條路線。路線 A 是圖遍歷型你預(yù)先畫好狀態(tài)機(jī)Agent 在狀態(tài)節(jié)點之間跳轉(zhuǎn)。適合流程非常固定的場景。路線 B 是自由規(guī)劃型Agent 每次循環(huán)都自主選下一個動作不受預(yù)設(shè)流程約束。適合探索性任務(wù)也是現(xiàn)在公認(rèn)更接近通用 Agent 的路線。新手建議從路線 B 入手代碼量不大而且能直觀感受模型“自己動腦子”的效果。2.4 Skill 和 Function Calling 到底怎么分工讀到這里你應(yīng)該有個感覺Agent 手里的武器就是 Skill。那有的人會問大模型本身支持 Function Calling / Tool Use為什么還要自造一個 Skill 概念這兩者是什么關(guān)系我用大白話解釋一下。Function Calling 是模型輸出層面的一種結(jié)構(gòu)化調(diào)用協(xié)議它讓模型學(xué)會輸出“我想調(diào)用某個函數(shù)、傳這些參數(shù)”。它解決的是“模型怎么把意圖變成可執(zhí)行指令”這個問題。但 Skill 是更高一層的抽象它解決的問題是“這個能力單元內(nèi)部怎么實現(xiàn)、怎么和 Agent 的上下文與記憶協(xié)作”。也就是說一個 Skill 內(nèi)部完全可以調(diào)用多個 Function也可以不發(fā)函數(shù)調(diào)用只做文本處理再寫回記憶。Skill 是對 Function 的編排和封裝同時它自身也可以有狀態(tài)和記憶讀寫能力。理解了這層你就不會被“接入大模型就算 Agent”這種說法帶偏了。3. 動手前必須選型的三個關(guān)鍵點3.1 底層模型怎么選不是越貴越好要看你需要的“推理密度”想做 Agent第一件事是選模型。我的建議是別盲目上最大參數(shù)的商業(yè)模型先用一個推理密度適中的模型把鏈路跑通。注意我這里說的“推理密度”是單位任務(wù)里模型需要做多少次決策。如果你的 Agent 是簡單問答型大部分模型都夠用。但如果你的 Agent 需要自主編排工具、處理多層狀態(tài)那這個模型必須足夠“聽話”不然你會看到它頻繁發(fā)明不存在的函數(shù)名、漏傳參數(shù)、修改記憶時格式錯亂。就我個人經(jīng)驗支持結(jié)構(gòu)化輸出、且對工具調(diào)用格式訓(xùn)練比較充分的模型在 Agent 場景下體驗會好不少。還有一個務(wù)實的選擇把“主規(guī)劃模型”和“子任務(wù)執(zhí)行模型”分開。規(guī)劃模型負(fù)責(zé)循環(huán)決策可以用能力高一檔的模型一些機(jī)械執(zhí)行型 Skill 內(nèi)部直接調(diào)便宜模型甚至規(guī)則邏輯沒必要全走貴模型。開銷能差出好幾倍這是個非常實用的小技巧。3.2 Agent 框架和純手寫之間怎么選市面上以 Agent 為賣點的框架不少動不動就是編排運行時、插件市場看起來很嚇人。我個人的看法是第一次做 Agent請你先“手寫骨架再考慮框架”。原因有兩個。第一框架封裝度太高你會迷失在抽象概念里很難理解記憶、角色、主動性究竟是怎么流轉(zhuǎn)的。第二很多框架的核心玩法就是幫你拼接各類工具但一旦你遇到不滿足的邊界場景改框架內(nèi)部的調(diào)度邏輯往往比重新寫一個還麻煩。反過來我也不勸你一根筋全手寫。大模型 SDK、向量存儲、數(shù)據(jù)庫這些基礎(chǔ)設(shè)施該用就用但 Agent 的核心循環(huán)、Skill 注冊表、記憶操作接口這些“靈魂組件”建議第一版自己寫一遍。這個“手寫”的過程才是真正建立技術(shù)直覺的地方等你踩過一輪以后再去用框架你會非常清楚框架的每個 API 解決的是什么問題。3.3 任務(wù)場景要收斂第一個 Agent 別“既要又要”選場景這個事我要多說兩句。很多初學(xué)者上來就想做一個“全能生活助理”讓它管日程、查天氣、訂外賣、寫周報結(jié)果一個都做不穩(wěn)。這里有一個設(shè)計原則叫能力半徑受控。第一個 Agent 最好只做一類任務(wù)但把這類任務(wù)做到閉環(huán)。舉例來說“日志異常分析 Agent”就是個特別合適的起步場景。它只有三個 Skill讀日志文件、查歷史故障知識庫、生成分析報告。任務(wù)半徑小狀態(tài)有限記憶的作用明顯很容易驗證效果。等這個跑順了再往上加 Skill、增加任務(wù)類型就不會到處著火。我相當(dāng)推薦這種從窄到寬的演進(jìn)路徑。4. 從零搭建 Skill 運行時目錄、配置、加載機(jī)制4.1 Skill 的目錄組織與配置格式我習(xí)慣將每個 Skill 拆成獨立目錄放它的描述配置和實現(xiàn)邏輯。一個標(biāo)準(zhǔn)目錄長這樣skills/ ├── read_log_file/ │ ├── SKILL.md │ └── main.py ├── query_issue_kb/ │ ├── SKILL.md │ ├── main.py │ └── data_base.json └── generate_report/ ├── SKILL.md └── main.pySKILL.md是我給每個 Skill 配的“身份證”里面寫好 Agent 決策時需要用到的元信息。格式樣例--- name: read_log_file description: 讀取日志文件內(nèi)容支持按時間范圍和關(guān)鍵詞過濾。 when_to_use: 當(dāng)用戶要求分析日志、定位異常、篩選特定事件時使用。 parameters: - name: file_path type: string required: true description: 日志文件的絕對路徑或相對路徑。 - name: keyword type: string required: false description: 僅返回包含該關(guān)鍵詞的行。 - name: since type: string required: false description: ISO 格式的開始時間如 2026-08-01T00:00:00。 --- # read_log_file 該 Skill 負(fù)責(zé)讀取本地日志文件提取關(guān)鍵信息并做初步清洗。 實現(xiàn)中要注意大文件不可以一次讀入內(nèi)存必須按行流式處理。這套配置看起來沒什么玄機(jī)但真正起作用的是when_to_use字段。模型在每個循環(huán)節(jié)點拿到全部 Skill 清單后會先靠name和description做粗篩再把候選 Skill 的完整配置拿出來細(xì)讀。如果description寫得太空泛模型要么不選它要么在無關(guān)場景誤選它。新手最容易忽略的就是這個字段的調(diào)優(yōu)它非常影響 Agent 的工具選擇準(zhǔn)確率。4.2 Skill 實現(xiàn)為什么要統(tǒng)一接口協(xié)議每個 Skill 的main.py基本邏輯可以不同但對外暴露的接口協(xié)議必須統(tǒng)一。我設(shè)計的最小協(xié)議大概這樣class BaseSkill: skill_name: str def __init__(self, context: AgentContext): # context 里裝有記憶句柄、配置、會話歷史等 pass def execute(self, **kwargs) - SkillResult: # 返回值統(tǒng)一為 SkillResult內(nèi)含狀態(tài)四要素 passSkillResult我一般會帶上四個字段output: 該 Skill 想傳遞給模型的核心信息比如報告文本、查詢結(jié)果。new_memories: 需要寫入記憶存儲的內(nèi)容列表由 Skill 主動產(chǎn)生。status:success、failure、require_more三選一。metadata: 額外追蹤用的元信息如耗時、寫入條數(shù)。為什么非要帶new_memories字段因為 Skill 在執(zhí)行過程中很可能會發(fā)現(xiàn)有用的信息比如讀日志時發(fā)現(xiàn)某條 DMA 異常頻繁出現(xiàn)這個信息值得留存。如果 Skill 不能主動寫記憶那每個 Skill 的發(fā)現(xiàn)就只能通過大模型下一次讀取輸出文本來間接沉淀既不準(zhǔn)確又費 token。把記憶寫入動作放進(jìn)接口協(xié)議里本質(zhì)上是把“記憶沉淀”變成一種可編程的硬行為而不是可選的軟行為。4.3 注冊表與加載器讓 Agent 知道自己有什么能力Skill 目錄有了、協(xié)議的骨架有了還需要一個加載器把它們都注冊到 Agent 模型中。這步的核心是“構(gòu)造 Skill 清單文本”喂給模型做動作選擇。寫一個最簡單的加載器from pathlib import Path import importlib.util def load_all_skills(skill_root: str, ctx): skills {} for skill_dir in Path(skill_root).iterdir(): if not skill_dir.is_dir(): continue config_path skill_dir / SKILL.md main_path skill_dir / main.py if not config_path.exists() or not main_path.exists(): continue # 把 SKILL.md 的 front-matter 解析出來 meta parse_front_matter(config_path.read_text(encodingutf-8)) # 動態(tài)加載 main.py 模塊 spec importlib.util.spec_from_file_location( skill_dir.name, main_path ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) skill_instance module.Skill(ctx) skills[meta[name]] { meta: meta, instance: skill_instance } return skills別小看這個加載器它決定了你后續(xù)加新 Skill 是不是絲滑。當(dāng)你新增能力時只需要往skills目錄丟一個帶描述和實現(xiàn)的新文件夾重啟后 Agent 就能自動感知主體代碼一行都不用改。這套插件化思想是 Agent 能力能夠持續(xù)生長的基礎(chǔ)。另外解析 front-matter 時注意容錯別讓一個 Skill 的配置語法錯誤導(dǎo)致整個 Agent 啟動崩潰。5. 實現(xiàn)一個最小可復(fù)用的 Agent 核心循環(huán)5.1 狀態(tài)機(jī)的結(jié)構(gòu)設(shè)計前面概念講了不少現(xiàn)在進(jìn)入到寫代碼環(huán)節(jié)。我會做一個面向“日志異常分析”的最小 Agent它包含三個 Skill讀日志文件、查詢歷史故障知識庫、生成分析報告。這個任務(wù)足夠收斂又能把記憶、角色、主動性全部串起來。Agent 主循環(huán)的狀態(tài)管理我直接用字典保存完整代碼大概是import json import uuid class Agent: def __init__(self, llm, skill_loader, memory_store): self.llm llm self.skills skill_loader self.memory memory_store self.session_id str(uuid.uuid4()) def state_initial(self, user_request): # 初始化狀態(tài)目標(biāo)、任務(wù)描述、當(dāng)前進(jìn)度、決策歷史 return { session_id: self.session_id, goal: user_request, subtask_queue: [], plan: [], current_action_idx: 0, done: False } def decide_next_action(self, state): # 構(gòu)建 prompt包含角色設(shè)定 當(dāng)前狀態(tài)摘要 Skill 列表 可用記憶 messages self.compose_messages(state) # 模型決定下一步動作這里要求模型輸出 JSON response self.llm.chat(messages, response_formatjson) return self.parse_action(response)這里最需要精心設(shè)計的是compose_messages這個函數(shù)本質(zhì)上是把狀態(tài)、記憶、Skill 描述變成決策上下文喂給模型。我把它拆成三塊來看。角色設(shè)定塊。每次循環(huán)都注入但并不是一大段人設(shè)模板無腦堆疊而是把當(dāng)前任務(wù)目標(biāo)、角色邊界、行業(yè)背景寫進(jìn)去。例如“你是嵌入式方向資深代碼評審與日志分析助手只基于給定日志和知識庫信息下結(jié)論。禁止臆測寄存器位含義。若信息不足以得出結(jié)論必須明確說明缺乏依據(jù)?！边@里邊就有安全邊界和不確定處理策略。Skill 選擇清單塊。把所有可用 Skill 的name、description、parameters都列出來讓模型在每輪決策時都能看到自己能調(diào)用的“兵器庫”。這個動作倒不用每次貼全量。如果 Skill 數(shù)量大于十來個優(yōu)先讓模型做一次粗選再給粗選結(jié)果中的 Skill 暴露詳細(xì)參數(shù)。記憶摘要塊。從長期記憶里檢索與當(dāng)前任務(wù)相關(guān)的記錄比如歷史異常案例、用戶偏好、上次處理結(jié)論。記憶摘要是縮短“重新理解成本”的核心如果該塊缺失Agent 的“記憶”就名存實亡。實際執(zhí)行決策時我要求模型返回 JSON結(jié)構(gòu)統(tǒng)一為{ reasoning: 簡要說明為什么選這個動作, next_action: call_skill|reply|require_more, skill_name: read_log_file, parameters: { file_path: logs/uart.log, since: 2026-08-01T00:00:00 } }模型輸出了結(jié)構(gòu)化指令循環(huán)體就能像一個狀態(tài)機(jī)一樣往下走了。5.2 讓 Agent 真正跑起來的 Skill 執(zhí)行器寫執(zhí)行器時有一個細(xì)節(jié)非常關(guān)鍵Skill的執(zhí)行結(jié)果不一定是一次性成功的它可能返回的是中間信息、也可能拋異常。因此執(zhí)行器不能簡單地result skill.execute()就把結(jié)果塞給模型必須做一個統(tǒng)一的包裝和異常兜底。def run_skill(self, state, skill_name, params): if skill_name not in self.skills: return { status: failure, reason: funknown skill: {skill_name} } skill_def self.skills[skill_name] try: result skill_def[instance].execute(**params) except TypeError as e: # 參數(shù)不匹配兜底把異常信息返回給模型自行調(diào)整 return { status: parameter_error, message: f參數(shù)校驗失敗: {e}。請檢查參數(shù)說明后重試。 } except Exception as e: return { status: runtime_error, message: fSkill 執(zhí)行異常: {e} } return result針對參數(shù)不匹配的錯誤我給模型返回了一個“請檢查參數(shù)說明后重試”的信號這里面有一個重要的工程經(jīng)驗不要讓循環(huán)因為參數(shù)錯誤直接崩潰而要把錯誤交給模型去反思并修正。模型很多時候只是少傳了一個可選參數(shù)收到異常后它會自覺補調(diào)用參數(shù)。這種“模型自己修正自己”的機(jī)制能顯著提高多步驟任務(wù)的成功率。循環(huán)體在執(zhí)行完 Skill 后必須做一次“記憶吸收”把new_memories和中間觀測寫入記憶存儲。同時還需要更新狀態(tài)字典里的決策歷史格式簡單追加一條{action, skill_name, result_summary, time}即可。這些決策歷史將在下一輪決策中跟記憶摘要合并作為模型的輸入形成對任務(wù)全局的掌控感。5.3 寫一個能“記憶前文”的 Skill內(nèi)部狀態(tài)如何串起來為了展示“記憶”并非只能靠數(shù)據(jù)庫我特別演示一個帶內(nèi)部狀態(tài)翻轉(zhuǎn)的 Skill。這個 Skill 叫write_analysis_snapshot它負(fù)責(zé)把每一步的中間分析結(jié)果累積到一個會話級快照文件里。# skills/write_analysis_snapshot/main.py import json from pathlib import Path class Skill: name write_analysis_snapshot def __init__(self, context: AgentContext): self.context context self.snapshot_path context.data_dir / fsnapshot_{context.session_id}.json def execute(self, content: str, step: int): # 讀取既有快照不存在則初始化 snap {} if self.snapshot_path.exists(): snap json.loads(self.snapshot_path.read_text(encodingutf-8)) snap[fstep_{step}] content self.snapshot_path.write_text( json.dumps(snap, ensure_asciiFalse, indent2), encodingutf-8 ) return { output: f已保存第 {step} 步分析快照。, new_memories: [{ type: snapshot_update, content: f寫入快照 step_{step}, session_id: self.context.session_id }], status: success, metadata: {step: step, path: str(self.snapshot_path)} }這個例子的啟發(fā)性在于Skill不再只是無狀態(tài)函數(shù)它可以持有context操作會話級文件把一次任務(wù)過程中產(chǎn)生的中間狀態(tài)記錄下來。這對應(yīng)到現(xiàn)實場景就是Agent 分析了二十個日志文件后突然想回看第三步猜的寄存器配置不再需要從頭推演因為快照已經(jīng)在那里了。這比“讓模型自己記住”可靠得多。5.4 加一點“主動性”的味道Agent 自檢與繼續(xù)任務(wù)循環(huán)如何體現(xiàn)主動性我加一個叫self_check的調(diào)度能力。它的觸發(fā)條件不是用戶指令而是 Agent 在主循環(huán)中發(fā)現(xiàn)“子任務(wù)尚未完成且狀態(tài)不充分”的時候。比如日志分析 Agent 讀到一個中斷風(fēng)暴關(guān)鍵詞但當(dāng)前日志時間范圍只覆蓋了后半段它應(yīng)當(dāng)自己決定“我需要擴(kuò)大時間范圍重新讀一次日志”而不是停下來問用戶“您看接下來怎么辦”。這在代碼里表現(xiàn)為一個分支判斷當(dāng)模型決策返回的next_action是call_skill且目標(biāo) Skill 是read_log_file時循環(huán)體在更新完狀態(tài)后不結(jié)束繼續(xù)進(jìn)入下一輪決策。真正讓“主動”落在工程上的是給模型一個開放的動作空間并且明確告訴他“如果發(fā)現(xiàn)結(jié)果不完整你有權(quán)調(diào)用request_range_expansion這類 Skill 來自行補充任務(wù)”。我在狀態(tài)機(jī)里額外維護(hù)了一個attempt_count每執(zhí)行一輪循環(huán)就加一。當(dāng)它大于閾值比如 8循環(huán)強(qiáng)制退出把當(dāng)前摘要和已確認(rèn)結(jié)論交給用戶并對未決問題做透明度說明。設(shè)置這個上限是防止模型在一個錯誤的方向上反復(fù)自我修正永遠(yuǎn)跑不完。這里同樣體現(xiàn)了一個 Agent 設(shè)計原則既要給自由也要給邊界。6. 落地一份可查的記憶長期記憶與短時記憶的實現(xiàn)策略6.1 SQLite 方案與 JSON 方案對比關(guān)于記憶存儲很多教程會把向量數(shù)據(jù)庫說成默認(rèn)選項但我不建議你一上來就上重型組件。以最小閉環(huán)為目標(biāo)你只需要回答三個問題記憶存哪按什么查如何避免膨脹如果你只有幾十條記憶放在 JSON 文件里最方便。每次循環(huán)讀取整個文件、過濾出相關(guān)記錄丟給模型就行。缺點是數(shù)據(jù)量上來后全量讀取浪費 token也拖慢響應(yīng)。另一個方案是 SQLite輕量、無需獨立服務(wù)、支持條件查詢適合存幾千條以下的記憶記錄。這兩種方案前期的代碼復(fù)雜度差別不大SQLite 加一個標(biāo)準(zhǔn)庫即可搞定我推薦直接上 SQLite免得后期遷移。表結(jié)構(gòu)我就三張表極其簡單。-- 會話表 CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, user_id TEXT, created_at TEXT ); -- 事件事實表 CREATE TABLE memories ( memory_id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, memory_type TEXT, -- preference / fact / task_result / snapshot content TEXT, created_at TEXT ); -- 記憶來源索引表 CREATE TABLE memory_links ( link_id INTEGER PRIMARY KEY AUTOINCREMENT, memory_id INTEGER, source_skill TEXT, source_step INTEGER );這種設(shè)計刻意不去碰向量索引因為初期記憶規(guī)模很小SQLite 的LIKE查詢配合時間倒序已經(jīng)足夠。只有當(dāng)記憶條數(shù)奔著十萬條去、且你真的需要“語義相似召回”時才引入向量檢索這條路后頭好接。6.2 記憶寫入時的“歸納”習(xí)慣這條是我實際用的經(jīng)驗印象很深。剛開始我的 Agent 把日志原文大段寫入記憶沒過多久記憶庫就膨脹得沒法看了每次檢索都撈出一堆垃圾。后來我加了一條約束Skill 寫記憶前必須先做歸納而不是搬運全文。我在read_log_file的邏輯里加了剪裁函數(shù)超過一定長度的內(nèi)容不直接入記憶而是摘出關(guān)鍵行、數(shù)量統(tǒng)計、級別分布再讓大模型用一句話總結(jié)發(fā)生了什么。這個抽象的過程其實給 Agent 記憶質(zhì)量帶來了質(zhì)的提升。記住記憶的目標(biāo)不是“存檔”而是“讓未來的自己快速理解以前發(fā)生了什么”。降低記憶寫入的冗長度是長期維護(hù) Agent 最重要的一步。6.3 記憶的過期與優(yōu)先級讓 Agent 知道什么該忘這個點很多文章講不到但我認(rèn)為非常關(guān)鍵。記憶如果永遠(yuǎn)只增不減總有一天會把有效信息淹沒。我建議每個記憶帶一個priority字段從 0 到 5。偏好類記憶設(shè)置為 5 分例如“用戶偏好 C 語言實現(xiàn)方案”臨時過程信息設(shè)置為 1 分例如“某次運行輸出的第一行是 SPDIF data”。檢索時按(priority DESC, created_at DESC)拉取低于閾值的記錄不進(jìn)入模型上下文。同時增加一個簡單的每日清理動作刪除priority 1且創(chuàng)建時間超過 24 小時的記憶。這讓 Agent 的長期記憶更有彈性等任務(wù)跨周以后你回頭看這個設(shè)計能讓你少掉很多頭發(fā)。7. 給 Agent 注入角色感約束 Prompt、上下文模板與風(fēng)格護(hù)欄7.1 角色模板的工程化寫法前面說了角色要分三層我這里給一個可復(fù)用的模板結(jié)構(gòu)放在項目里叫agent_brain.md# Agent 角色說明書 你是「日志偵探」一名資深的嵌入式系統(tǒng)日志分析助理。 你擅長解析 UART/SPI/I2C 日志定位異常驅(qū)動、中斷風(fēng)暴、時序紊亂等問題。 ## 身份邊界 - 只依據(jù)用戶提供的日志與知識庫文件進(jìn)行分析。 - 禁止在沒有寄存器手冊的情況下猜測具體寄存器位含義。 - 不提供任何可導(dǎo)致設(shè)備物理損壞的操作建議。 ## 工作流程建議 1. 先讀取日志了解事件全貌。 2. 發(fā)現(xiàn)可疑模式時查詢歷史故障知識庫。 3. 結(jié)合記憶中的歷史結(jié)論形成推理鏈條。 4. 最終輸出結(jié)論時列出完整證據(jù)鏈。 ## 輸出風(fēng)格 - 先給結(jié)論后給證據(jù)。 - 每條結(jié)論需要有對應(yīng)日志行作為依據(jù)并標(biāo)注行號。 - 如果信息不足直接說“當(dāng)前信息不足以支撐該結(jié)論”。你可能會說這和普通 Prompt 有什么區(qū)別有但要配合代碼才會生效。我不會每輪循環(huán)無腦丟全部角色說明書而是把它切塊按需注入。只有在出現(xiàn)“是否需要懷疑方向”的決策點時才注入“工作流程建議”塊只有在要生成最終結(jié)論時才注入“輸出風(fēng)格”塊。這既控制了 token 開銷也讓模型在不同階段注意力更集中。7.2 輸出風(fēng)格護(hù)欄讓模型不“跑偏”的方法角色設(shè)定里有一部分不是給模型看的而是給后處理邏輯看的。我管它叫輸出風(fēng)格護(hù)欄。它可以實現(xiàn)為在模型生成完結(jié)果后跑一個輕量后處理函數(shù)檢查結(jié)果中是否包含“證據(jù)引用缺失”等違規(guī)情形。舉個例子日志分析 Agent 的最終報告要求每條結(jié)論必須有對應(yīng)日志行號。后處理函數(shù)逐個檢查結(jié)論文本如果某條結(jié)論后沒有形如L123的標(biāo)注就自動插入一句“該結(jié)論缺少行號參考已跳過”。別高估模型每次都會自覺遵守格式要求。端到端任務(wù)里越往后模型越容易松懈沒有后處理護(hù)欄報告格式最終會跑偏得很隨性。7.3 人設(shè)的“動態(tài)切換”機(jī)制一個 Agent 可以同時服務(wù)多種角色嗎可以但建議你給每個角色做一個獨立的角色上下文包而不是把多角色塞進(jìn)一段 Prompt 里來回切換。我用一個叫“角色上下文分流器”的方法在請求入口處先讓模型做一次輕量的意圖分類把“讓我看看日志”分到日志分析 Agent 通道把“幫我寫段代碼”分到代碼生成 Agent 通道。每個通道內(nèi)部都用完全獨立的角色設(shè)定、Skill 清單、記憶庫。這有個直接優(yōu)勢不同域的記憶天然隔離日志領(lǐng)域的觀察不會污染代碼生成領(lǐng)域的判斷。同時每個 Agent 能力范圍變小錯誤率也會降下來。很多商用 Agent 產(chǎn)品本質(zhì)上就是多個“單角色 Agent”的外殼路由這套架構(gòu)不花哨但非常穩(wěn)。8. 完整示例一個可復(fù)現(xiàn)的“帶記憶與主動性的日志分析 Agent”8.1 項目目錄與代碼骨架我直接給你一份可以直接跑的最小工程結(jié)構(gòu)方便你照著抄。log_agent/ ├── agent_brain.md ├── agent_core.py ├── llm.py ├── memory_store.py ├── skills/ │ ├── __init__.py │ ├── base.py │ ├── read_log_file/ │ │ ├── SKILL.md │ │ └── main.py │ ├── query_issue_kb/ │ │ ├── SKILL.md │ │ └── main.py │ ├── write_analysis_snapshot/ │ │ ├── SKILL.md │ │ └── main.py │ └── generate_report/ │ ├── SKILL.md │ └── main.py └── data/ ├── sqlite.db └── logs/ └── uart.logmemory_store.py里封裝 SQLite 的讀寫函數(shù)核心接口四個init_db()、add_memory()、search_memory()、cleanup_expired()。llm.py則做一層適配把通義、OpenAI 風(fēng)格 SDK 統(tǒng)一封裝成chat(messages, response_format)和embed(text)兩個方法。agent_core.py就是前面展示的主循環(huán)加執(zhí)行器實現(xiàn)組裝起來大概是這個流程啟動時加載 Skill 和記憶把用戶請求放入初始狀態(tài)循環(huán)調(diào)用decide_next_action直到doneTrue或到達(dá)輪次上限。8.2 跑一個完整任務(wù)演示假設(shè)用戶在交互框輸入“幫我分析data/logs/uart.log里為什么 UART 偶發(fā)亂碼并給出建議?！钡谝惠喲h(huán)模型讀到角色說明書 Skill 列表 當(dāng)前狀態(tài)。它選擇調(diào)用read_log_file傳參file_pathdata/logs/uart.log和keywordERROR。執(zhí)行器把日志中所有包含ERROR的行讀出來返回給模型并記錄一條摘要記憶。第二輪循環(huán)模型在決策歷史里發(fā)現(xiàn)日志中存在多個RX overrun事件。它知道項目學(xué)過的歷史故障知識庫里有overrun的相關(guān)案例于是調(diào)用query_issue_kb參數(shù)是keywordRX overrun。知識庫返回了歷史處理中的一條經(jīng)驗先查 FIFO 中斷閾值配置再查 DMA 描述符是否耗盡。第三輪循環(huán)模型發(fā)現(xiàn)這兩條信息已經(jīng)可以支撐初步結(jié)論但還缺一次完整印象。它決定調(diào)用write_analysis_snapshot把前兩輪的發(fā)現(xiàn)落一份到快照文件留給后續(xù)分析沉淀。第四輪循環(huán)模型調(diào)用generate_report。它綜合日志證據(jù)、知識庫經(jīng)驗和快照記錄生成一份包含三個證據(jù)點、兩個建議項的最終報告。輸出風(fēng)格按角色說明書要求每條證據(jù)都帶日志行號。到這里工作流結(jié)束Agent 返回報告給用戶。這就是一個完整的“有記憶、有角色、有主動性”的 Agent 工作過程。你看著很自然但如果沒有 Skill 的封裝、沒有記憶的沉淀、沒有每一輪“自己決定下一步”的循環(huán)機(jī)制單靠一次大模型調(diào)用是不可能走完這個鏈路的。8.3 效果評價與調(diào)優(yōu)方向跑完一輪后怎么確認(rèn)這個 Agent 是合格的我用的評價項很簡單任務(wù)完成率、工具調(diào)用準(zhǔn)確率、記憶檢索準(zhǔn)確率、最終報告的事實一致性。前三個指標(biāo)可以靠人工抽樣統(tǒng)計最后一個我會專門讓另一個 LLM 實例做裁判檢查報告結(jié)論是否能從執(zhí)行日志中找到證據(jù)支撐。如果任務(wù)完成率不高先別著急換模型。你按這個順序排查Skill 描述是不是準(zhǔn)確角色說明書是否約束了不當(dāng)輸出記憶檢索有沒有帶回正確信息執(zhí)行器異常兜底有沒有把修正機(jī)會還給模型。這個排查順序幾乎覆蓋了我的所有實戰(zhàn)調(diào)優(yōu)場景。9. 常見問題與排查技巧實錄9.1 為什么 Agent 總是選錯 Skill 或重復(fù)執(zhí)行同一步這個問題我遇到最多也最容易被歸咎于“模型笨”。實際上多數(shù)原因是 Skill 清單里的描述太相似了尤其是name、description和when_to_use區(qū)分度不夠模型犯迷糊。排查建議是把全部 Skill 名稱和描述打成一個大表站在模型視角看能不能一眼分清“什么時候選誰”。如果自己也分不清說明描述寫得過于抽象。重寫時要盡量寫清適用場景和反面場景比如read_log_file的描述可以寫成“當(dāng)你需要讀取/查看一個日志文件的原始內(nèi)容或篩選后的內(nèi)容行時使用。如果用戶希望直接得到分析結(jié)論而不是原始日志內(nèi)容推薦使用analyze_log技能”。重復(fù)執(zhí)行同一步的問題通常由狀態(tài)更新不及時引起。要檢查模型決策完有沒有把動作追加到decision_history并讓新狀態(tài)真正參與下一輪compose_messages。很多時候歷史沒喂回去模型以為自己還沒看過某個文件于是反復(fù)讀同一份日志。9.2 模型輸出亂 JSON 或虛構(gòu)參數(shù)怎么處理現(xiàn)在的大模型雖然支持結(jié)構(gòu)化輸出但偶爾仍然會出現(xiàn)格式不合法、參數(shù)名臆造問題。建議從兩個層面預(yù)防。第一個層面是模型層約束要求模型按 JSON Schema 輸出并設(shè)定temperature較低。第二個層面是代碼層約束增加一個repair_json函數(shù)用容錯解析邏輯過濾掉散落文本直接把最外層{...}提取出來再解析。如果解析還是失敗將原始輸出返回給模型并在提示里明確說明“你的輸出 JSON 解析失敗{錯誤信息}請只輸出合法 JSON”給它一個“補考”的機(jī)會。參數(shù)名虛構(gòu)通常是 Skill 配置里沒有對參數(shù)做嚴(yán)格枚舉。最簡單有效的辦法是在 Skill 描述文本里把參數(shù)說明再次寫清楚甚至給示例值。模型看到示例以后往往能瞬間學(xué)會正確傳參這比在代碼里做一堆參數(shù)校驗更省事。9.3 記憶庫膨脹、上下文超限怎么處理記憶庫膨脹最典型的征兆是每次決策的輸入里帶上了一大堆過期的舊信息模型決策速度變慢且容易被噪聲誤導(dǎo)。我之前靠 SQLite 的priority和created_at字段做了衰減處理已經(jīng)能緩解一大半問題。如果仍然上下文超限可以在compose_messages階段按三類做截斷角色說明書只保留關(guān)鍵片段記憶摘要取最近 5 條加最高優(yōu)先級 5 條決策歷史只保留最近 3 輪摘要。還有一個技巧每次模型執(zhí)行完一輪 Skill 后不要把它返回的所有文本原封不動存進(jìn)記憶庫而是先用一個壓縮摘要函數(shù)把關(guān)鍵結(jié)論提取出來。這個壓縮可以由 LLM 完成也可以直接采樣關(guān)鍵句。壓縮后入庫的記憶大大降低后續(xù)上下文的壓力效果立竿見影。9.4 主動性的邊界Agent 自己越想越偏怎么辦自由規(guī)劃型循環(huán)最怕的一件事情是模型在某個錯誤的中間結(jié)論上反復(fù)調(diào)用 Skill 自我驗證形成死循環(huán)。比如它懷疑某個中斷標(biāo)志被錯誤置位于是反復(fù)讀寄存器配置文檔每次都得不到明確答案然后它繼續(xù)換著關(guān)鍵詞查任務(wù)遲遲不結(jié)束。我的實操解法是雙重限制第一限制每個任務(wù)總循環(huán)次數(shù)比如 8 輪第二在decide_next_action的提示中顯式加入一條規(guī)則——如果最近兩次動作里已經(jīng)包含三次同 Skill 調(diào)用且沒有新事實產(chǎn)生允許你在不調(diào)用 Skill 的情況下直接整理已知信息并給用戶一個階段性的結(jié)論不要強(qiáng)行追求完美答案。這種“允許在不確定中收尾”的指令反而是讓 Agent 更可靠的關(guān)鍵它減少了無意義的空轉(zhuǎn)。9.5 Skill 數(shù)量多了之后Agent 決策反而變差怎么辦這是個非常現(xiàn)實的問題。Skill 清單一兩頁時還好數(shù)量漲到十個以上模型每次都要在長上下文里挑工具偶爾就會漏掉更優(yōu)的工具。解決路徑有兩條一條是分層路由首頁只展示幾個粗顆粒度的入口 Skill比如“日志分析”“代碼生成”“知識檢索”具體執(zhí)行子 Skill 由入口注冊時、選擇后的局部清單來暴露。另一條是對 Skill 做向量檢索匹配先按文本相似度召回 Top 5 個候選再把這些候選的描述交給模型精確決策。第二種方案在規(guī)模大的場景更有優(yōu)勢適合后邊需要擴(kuò)展的讀者嘗試。10. 我個人踩過的一些坑最后分享幾個非常具體、但教科書里不會寫的經(jīng)驗。第一Skill目錄的命名盡量用項目主題相關(guān)的短橫線風(fēng)格不要用中文名。我發(fā)現(xiàn)有些框架解析時能處理中文文件名但日志追蹤和異常報錯信息里一旦混入中文路徑字符排查起來會痛苦得多。第二Agent Loop里的每輪請求最好在消息結(jié)構(gòu)里帶上當(dāng)前的動作序號和總規(guī)劃哪怕是兩句話的摘要也能顯著增強(qiáng)模型對任務(wù)階段的感知力。比如狀態(tài)里寫一條progress: 第2步/共5步已完成日志讀取正在查詢知識庫模型下一輪決策時會更像在“順著進(jìn)度往下走”而不是重新開始找切入點。第三不要省掉“記憶寫入成功”的反饋信號。每次 Skill 返回new_memories并且寫入成功后要把“已成功記憶以下內(nèi)容xxx”反饋到模型上下文。模型如果知道自己的動作產(chǎn)生了持久化影響后續(xù)決策會明顯更篤定。這個小改動聽上去很玄學(xué)但我實測下來確實能讓 Agent 的行為顯得更“有意識”。第四如果你做的是面向記錄、知識積累類的 Agent強(qiáng)烈建議每一輪循環(huán)都把Skill調(diào)用參數(shù)和返回結(jié)果的摘要保存到本地日志方便之后復(fù)現(xiàn)問題和復(fù)盤。Agent 是一個動態(tài)決策系統(tǒng)不像普通程序那樣“輸入相同輸出相同”。沒有決策留痕你根本無從判斷某次劣質(zhì)輸出是模型抽風(fēng)、記憶誤導(dǎo)還是 Skill 本身報錯。這個審計日志是你調(diào)試 Agent 時最重要的抓手。這套東西看起來有不少概念其實核心就一句話Skill是 Agent 的行動抓手記憶是它的長期底盤角色是它的行為邊界主動循環(huán)是它的引擎。四者拼到一起它才不再是一個“你問一句、它答一句”的聊天機(jī)器人而是像一個真正有經(jīng)驗的新人——知輕重、記得事、會自己往后走。我第一次把這套循環(huán)跑通的時候看著模型自己在日志里查出隱患、查過歷史案例、做出帶證據(jù)鏈的報告還是挺震撼的。希望這篇一步步拆解的實操內(nèi)容也能幫你體會到這種“把模型變成能干活的人”的感覺。寫完第一版之后不要停在這里你可以再給它加新的 Skill、換更大的記憶方案、調(diào)整角色模板讓它越來越接近你想要的那個形態(tài)。 手把手實現(xiàn)AI Agent：讓Skill有記憶、角色和主動性
如果你刷技術(shù)圈比較勤應(yīng)該已經(jīng)注意到AI Agent這個詞快被聊爛了。但說實話大部分談 Agent 的文章都在講概念、講架構(gòu)圖真正能跟著一步步落地的實操分享反而少。我自己從最早寫死 Prompt 玩大模型到做成有狀態(tài)、有技能包、能自己決定下一步動作的東西中間踩的坑比想象中多得多。這篇文章我就用完全手把手的方式來拆一遍標(biāo)題是“手把手書寫你的第一個 AI Agent當(dāng) Skill 有了記憶、角色和主動性”重點就在記憶、角色、主動性這三個詞上。這三個詞恰好是普通 Prompt 封裝和真正的 Agent 之間最本質(zhì)的分界線。我不會只貼一段代碼給你看而是把每一步背后的設(shè)計依據(jù)、取舍邏輯、容易忽略的細(xì)節(jié)全部鋪開講?？赐曛竽銘?yīng)該能在自己的項目里復(fù)現(xiàn)一個帶 Skill 機(jī)制、有短期長期記憶、有人設(shè)約束、具備基本主動調(diào)度能力的 Agent 雛形。這玩意不是玩具很多商業(yè)化產(chǎn)品的底座也就是這么長的。1. 先把核心問題聊透沒有 Skill 的 Agent和大模型套殼有什么區(qū)別1.1 痛點來自 Prompt 工程的三個天花板我先說一個場景你自己體會一下是不是遇到類似情況。假設(shè)你想讓模型扮演一個“嵌入式開發(fā)助手”幫用戶分析日志、生成寄存器配置、檢查 GPIO 初始化代碼。如果只是用 Prompt 把角色設(shè)定寫死再扔給模型你會遇到三個類問題。第一模型調(diào)用的“技能”全藏在提示詞里。不管你是做日志分析、DTS 修改還是 build 錯誤排查本質(zhì)都是上下文模板拼接。日志格式一變Prompt 就得改。更難受的是當(dāng)任務(wù)鏈路長起來比如“分析日志 - 定位外設(shè)異常 - 生成補丁 - 跑靜態(tài)檢查”這個流程邏輯是代碼里寫死的模型根本沒有自主規(guī)劃的空間。第二每次都像失憶一樣。上一步剛確認(rèn)完芯片型號是ESP32-S3下一步讓它生成初始化代碼時它又開始問你“請?zhí)峁┠男酒吞枴?。對話歷史不是沒傳而是傳了也不一定能穩(wěn)定約束后續(xù)決策尤其當(dāng)上下文超過一定長度早期關(guān)鍵信息被稀釋得很厲害。第三模型沒有主動性。它以“提問-回答”的單輪范式活著你問一句它回一句。真正干活的時候你希望它能自己決定“我需要先看一下寄存器手冊里的說明再決定怎么改配置”然后真的去調(diào)工具、讀文檔、嘗試、校驗、出結(jié)果。這已經(jīng)不是提示詞能解決的范圍了。這三個痛點是環(huán)環(huán)相扣的。技能碎片化導(dǎo)致能力邊界模糊記憶缺失導(dǎo)致決策質(zhì)量低主動性缺失導(dǎo)致整個系統(tǒng)只能停在“高級聊天機(jī)器人”層面。而圍繞Skill構(gòu)建的自定義 Agent 架構(gòu)恰好就是沖著這三點去的。1.2 Skill 和 Agent 的關(guān)系不是包含而是“能力的具象化”這里要先厘清一個概念。很多人把Skill理解成“給 Agent 準(zhǔn)備的一套提示詞模板”這太窄了。還有一種說法是 Skill 就是外部工具函數(shù)這也不夠。我傾向把 Skill 看作是“Agent 可以調(diào)用的一組帶描述、帶輸入輸出契約、帶執(zhí)行邏輯、帶狀態(tài)讀寫權(quán)限的能力單元”。舉個好消化的類比。把 Agent 想象成一個真人新員工。這個人聰明、理解力強(qiáng)但他剛?cè)肼毷裁礃I(yè)務(wù)都不會。他需要幾樣?xùn)|西才能干活崗位說明書角色定位、工作手冊Skill 定義、記事本記憶系統(tǒng)、以及主管授權(quán)他主動推進(jìn)任務(wù)主動性。所以 Skill 不只是“知識”它還包含行為邏輯。在這個框架下Agent 是執(zhí)行者Skill 是執(zhí)行者可選擇的行為包。Agent 為什么要“有” Skill因為 Skill 把模型不可控的自然語言能力轉(zhuǎn)化為可控的、可復(fù)用的、帶約束的模塊。模型負(fù)責(zé)判斷“我現(xiàn)在該調(diào)用哪個 Skill、如何組合”Skill 負(fù)責(zé)把模型意圖翻譯成確定性邏輯。這個分工是 Agent 架構(gòu)里最核心的一層。2. 設(shè)計 Agent 的四個要素記憶、角色、主動性、工具調(diào)用2.1 記憶機(jī)制不只是塞上下文而是做狀態(tài)分層標(biāo)題里第一個關(guān)鍵詞是“記憶”。我給你一個簡化的記憶分層模型。短期記憶當(dāng)前任務(wù)上下文里產(chǎn)生的關(guān)鍵信息比如用戶剛剛指定了項目目錄、選了某種通信協(xié)議。放內(nèi)存或會話變量里即可。長期記憶跨會話保留的偏好、歷史結(jié)論、常用配置。需要持久化輕量方案是 SQLite 或本地 JSON 文件重型方案可以上向量數(shù)據(jù)庫。工作記憶Agent 當(dāng)前的思考草稿、中間結(jié)果、計劃清單。這一層容易被忽略但它決定了 Agent 能不能“邊干邊記”。實現(xiàn)上有一個非常實用的設(shè)計模式把記憶封裝成 Agent 可讀寫的工具而不是直接改系統(tǒng) Prompt。也就是說模型通過調(diào)用“寫入記憶”這個動作來留存信息通過“檢索記憶”這個動作來獲取歷史相關(guān)內(nèi)容。這樣做最大的好處是記憶的存取時機(jī)由模型根據(jù)任務(wù)自主決定而不是每一輪都把所有歷史無腦拼進(jìn) Prompt。這個設(shè)計有直接好處上下文長度可管理關(guān)鍵信息不會被沖散跨會話體驗?zāi)苷嬲纬?。我在自己項目里?SQLite 做了個極簡版字段就四個記憶編碼、記憶類型、記憶內(nèi)容、創(chuàng)建時間。Agent 檢索時按關(guān)鍵詞匹配和創(chuàng)建時間排序取前幾條效果已經(jīng)比硬塞上下文好非常多。2.2 角色設(shè)定不是“你是一個助手”這么簡單角色這個詞很多人做得太淺。早期我寫 Agent角色設(shè)定就是一句“你是一位資深嵌入式工程師”完事。后來發(fā)現(xiàn)這個“角色”對模型行為的約束非常弱模型照樣會一本正經(jīng)胡說八道照樣會在不確定的時候亂猜。真正有效的角色設(shè)定應(yīng)該包含三層信息。第一層是身份邊界你能做什么不能做什么。比如“你是代碼評審助手只負(fù)責(zé)庫函數(shù)層面的靜態(tài)分析不做板級硬件調(diào)試”。第二層是輸出風(fēng)格約束匯報的表達(dá)習(xí)慣、是否給出代碼示例、遇到不確定時是明說還是猜測。第三層是價值觀與安全邊界涉及到可能破壞系統(tǒng)的命令必須二次詢問。這三層里身份邊界和風(fēng)格約束很多人會寫但安全邊界很少被重視。實操中安全邊界最好的實現(xiàn)方式不是寫死在角色 Prompt 里而是配備“攔截型 Skill”。比如你定義了一個執(zhí)行Shell命令的 Skill那這個 Skill 內(nèi)部必須帶危險命令校驗邏輯而不是靠模型自覺。角色負(fù)責(zé)“不主動越界”Skill 負(fù)責(zé)“越界也執(zhí)行不了”。兩道閘門都裝上系統(tǒng)才可靠。2.3 主動性從響應(yīng)式到任務(wù)自治的機(jī)制躍遷主動性是這三個詞里最容易被誤解的。有人覺得主動 Agent 不等人問自己開口說“我來幫您……”這其實只是表面的主動。真正的主動性是任務(wù)調(diào)度上的自治能力當(dāng)用戶給定一個模糊目標(biāo)Agent 能自行拆解子任務(wù)、決定子任務(wù)的執(zhí)行順序、處理執(zhí)行中出現(xiàn)的異常、甚至發(fā)現(xiàn)前置信息不足時主動查資料或提問澄清。這套機(jī)制在工程上是靠“循環(huán)”實現(xiàn)的。經(jīng)典的結(jié)構(gòu)是Agent Loop大致流程我整理成下面這個邏輯循環(huán)開始 1. 從任務(wù)隊列中取出當(dāng)前最優(yōu)先的子任務(wù) 2. 模型根據(jù)「當(dāng)前狀態(tài) 可用 Skill 列表 記憶摘要」決定下一步動作 3. 如果動作是調(diào)用 Skill - 執(zhí)行 - 把結(jié)果寫回狀態(tài) - 更新記憶 - 回到第 1 步 4. 如果動作是回復(fù)用戶 - 輸出最終結(jié)果 - 結(jié)束循環(huán) 5. 如果動作是請求更多信息 - 拋出澄清問題 - 暫停循環(huán)等待用戶輸入這里最關(guān)鍵的技術(shù)細(xì)節(jié)是第 2 步。模型如何知道有哪些 Skill 可用靠的不是它在訓(xùn)練數(shù)據(jù)里見過而是你把 Skill 的名字、用途、參數(shù)說明喂給了它。每輪迭代前Agent 都會拿著“當(dāng)前任務(wù) Skill 清單”去決策相當(dāng)于每走一步都重新規(guī)劃一次。這樣的設(shè)計遠(yuǎn)比“預(yù)設(shè)好整個任務(wù)鏈路然后順序執(zhí)行”更魯棒。具體到實現(xiàn)有兩條路線。路線 A 是圖遍歷型你預(yù)先畫好狀態(tài)機(jī)Agent 在狀態(tài)節(jié)點之間跳轉(zhuǎn)。適合流程非常固定的場景。路線 B 是自由規(guī)劃型Agent 每次循環(huán)都自主選下一個動作不受預(yù)設(shè)流程約束。適合探索性任務(wù)也是現(xiàn)在公認(rèn)更接近通用 Agent 的路線。新手建議從路線 B 入手代碼量不大而且能直觀感受模型“自己動腦子”的效果。2.4 Skill 和 Function Calling 到底怎么分工讀到這里你應(yīng)該有個感覺Agent 手里的武器就是 Skill。那有的人會問大模型本身支持 Function Calling / Tool Use為什么還要自造一個 Skill 概念這兩者是什么關(guān)系我用大白話解釋一下。Function Calling 是模型輸出層面的一種結(jié)構(gòu)化調(diào)用協(xié)議它讓模型學(xué)會輸出“我想調(diào)用某個函數(shù)、傳這些參數(shù)”。它解決的是“模型怎么把意圖變成可執(zhí)行指令”這個問題。但 Skill 是更高一層的抽象它解決的問題是“這個能力單元內(nèi)部怎么實現(xiàn)、怎么和 Agent 的上下文與記憶協(xié)作”。也就是說一個 Skill 內(nèi)部完全可以調(diào)用多個 Function也可以不發(fā)函數(shù)調(diào)用只做文本處理再寫回記憶。Skill 是對 Function 的編排和封裝同時它自身也可以有狀態(tài)和記憶讀寫能力。理解了這層你就不會被“接入大模型就算 Agent”這種說法帶偏了。3. 動手前必須選型的三個關(guān)鍵點3.1 底層模型怎么選不是越貴越好要看你需要的“推理密度”想做 Agent第一件事是選模型。我的建議是別盲目上最大參數(shù)的商業(yè)模型先用一個推理密度適中的模型把鏈路跑通。注意我這里說的“推理密度”是單位任務(wù)里模型需要做多少次決策。如果你的 Agent 是簡單問答型大部分模型都夠用。但如果你的 Agent 需要自主編排工具、處理多層狀態(tài)那這個模型必須足夠“聽話”不然你會看到它頻繁發(fā)明不存在的函數(shù)名、漏傳參數(shù)、修改記憶時格式錯亂。就我個人經(jīng)驗支持結(jié)構(gòu)化輸出、且對工具調(diào)用格式訓(xùn)練比較充分的模型在 Agent 場景下體驗會好不少。還有一個務(wù)實的選擇把“主規(guī)劃模型”和“子任務(wù)執(zhí)行模型”分開。規(guī)劃模型負(fù)責(zé)循環(huán)決策可以用能力高一檔的模型一些機(jī)械執(zhí)行型 Skill 內(nèi)部直接調(diào)便宜模型甚至規(guī)則邏輯沒必要全走貴模型。開銷能差出好幾倍這是個非常實用的小技巧。3.2 Agent 框架和純手寫之間怎么選市面上以 Agent 為賣點的框架不少動不動就是編排運行時、插件市場看起來很嚇人。我個人的看法是第一次做 Agent請你先“手寫骨架再考慮框架”。原因有兩個。第一框架封裝度太高你會迷失在抽象概念里很難理解記憶、角色、主動性究竟是怎么流轉(zhuǎn)的。第二很多框架的核心玩法就是幫你拼接各類工具但一旦你遇到不滿足的邊界場景改框架內(nèi)部的調(diào)度邏輯往往比重新寫一個還麻煩。反過來我也不勸你一根筋全手寫。大模型 SDK、向量存儲、數(shù)據(jù)庫這些基礎(chǔ)設(shè)施該用就用但 Agent 的核心循環(huán)、Skill 注冊表、記憶操作接口這些“靈魂組件”建議第一版自己寫一遍。這個“手寫”的過程才是真正建立技術(shù)直覺的地方等你踩過一輪以后再去用框架你會非常清楚框架的每個 API 解決的是什么問題。3.3 任務(wù)場景要收斂第一個 Agent 別“既要又要”選場景這個事我要多說兩句。很多初學(xué)者上來就想做一個“全能生活助理”讓它管日程、查天氣、訂外賣、寫周報結(jié)果一個都做不穩(wěn)。這里有一個設(shè)計原則叫能力半徑受控。第一個 Agent 最好只做一類任務(wù)但把這類任務(wù)做到閉環(huán)。舉例來說“日志異常分析 Agent”就是個特別合適的起步場景。它只有三個 Skill讀日志文件、查歷史故障知識庫、生成分析報告。任務(wù)半徑小狀態(tài)有限記憶的作用明顯很容易驗證效果。等這個跑順了再往上加 Skill、增加任務(wù)類型就不會到處著火。我相當(dāng)推薦這種從窄到寬的演進(jìn)路徑。4. 從零搭建 Skill 運行時目錄、配置、加載機(jī)制4.1 Skill 的目錄組織與配置格式我習(xí)慣將每個 Skill 拆成獨立目錄放它的描述配置和實現(xiàn)邏輯。一個標(biāo)準(zhǔn)目錄長這樣skills/ ├── read_log_file/ │ ├── SKILL.md │ └── main.py ├── query_issue_kb/ │ ├── SKILL.md │ ├── main.py │ └── data_base.json └── generate_report/ ├── SKILL.md └── main.pySKILL.md是我給每個 Skill 配的“身份證”里面寫好 Agent 決策時需要用到的元信息。格式樣例--- name: read_log_file description: 讀取日志文件內(nèi)容支持按時間范圍和關(guān)鍵詞過濾。 when_to_use: 當(dāng)用戶要求分析日志、定位異常、篩選特定事件時使用。 parameters: - name: file_path type: string required: true description: 日志文件的絕對路徑或相對路徑。 - name: keyword type: string required: false description: 僅返回包含該關(guān)鍵詞的行。 - name: since type: string required: false description: ISO 格式的開始時間如 2026-08-01T00:00:00。 --- # read_log_file 該 Skill 負(fù)責(zé)讀取本地日志文件提取關(guān)鍵信息并做初步清洗。 實現(xiàn)中要注意大文件不可以一次讀入內(nèi)存必須按行流式處理。這套配置看起來沒什么玄機(jī)但真正起作用的是when_to_use字段。模型在每個循環(huán)節(jié)點拿到全部 Skill 清單后會先靠name和description做粗篩再把候選 Skill 的完整配置拿出來細(xì)讀。如果description寫得太空泛模型要么不選它要么在無關(guān)場景誤選它。新手最容易忽略的就是這個字段的調(diào)優(yōu)它非常影響 Agent 的工具選擇準(zhǔn)確率。4.2 Skill 實現(xiàn)為什么要統(tǒng)一接口協(xié)議每個 Skill 的main.py基本邏輯可以不同但對外暴露的接口協(xié)議必須統(tǒng)一。我設(shè)計的最小協(xié)議大概這樣class BaseSkill: skill_name: str def __init__(self, context: AgentContext): # context 里裝有記憶句柄、配置、會話歷史等 pass def execute(self, **kwargs) - SkillResult: # 返回值統(tǒng)一為 SkillResult內(nèi)含狀態(tài)四要素 passSkillResult我一般會帶上四個字段output: 該 Skill 想傳遞給模型的核心信息比如報告文本、查詢結(jié)果。new_memories: 需要寫入記憶存儲的內(nèi)容列表由 Skill 主動產(chǎn)生。status:success、failure、require_more三選一。metadata: 額外追蹤用的元信息如耗時、寫入條數(shù)。為什么非要帶new_memories字段因為 Skill 在執(zhí)行過程中很可能會發(fā)現(xiàn)有用的信息比如讀日志時發(fā)現(xiàn)某條 DMA 異常頻繁出現(xiàn)這個信息值得留存。如果 Skill 不能主動寫記憶那每個 Skill 的發(fā)現(xiàn)就只能通過大模型下一次讀取輸出文本來間接沉淀既不準(zhǔn)確又費 token。把記憶寫入動作放進(jìn)接口協(xié)議里本質(zhì)上是把“記憶沉淀”變成一種可編程的硬行為而不是可選的軟行為。4.3 注冊表與加載器讓 Agent 知道自己有什么能力Skill 目錄有了、協(xié)議的骨架有了還需要一個加載器把它們都注冊到 Agent 模型中。這步的核心是“構(gòu)造 Skill 清單文本”喂給模型做動作選擇。寫一個最簡單的加載器from pathlib import Path import importlib.util def load_all_skills(skill_root: str, ctx): skills {} for skill_dir in Path(skill_root).iterdir(): if not skill_dir.is_dir(): continue config_path skill_dir / SKILL.md main_path skill_dir / main.py if not config_path.exists() or not main_path.exists(): continue # 把 SKILL.md 的 front-matter 解析出來 meta parse_front_matter(config_path.read_text(encodingutf-8)) # 動態(tài)加載 main.py 模塊 spec importlib.util.spec_from_file_location( skill_dir.name, main_path ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) skill_instance module.Skill(ctx) skills[meta[name]] { meta: meta, instance: skill_instance } return skills別小看這個加載器它決定了你后續(xù)加新 Skill 是不是絲滑。當(dāng)你新增能力時只需要往skills目錄丟一個帶描述和實現(xiàn)的新文件夾重啟后 Agent 就能自動感知主體代碼一行都不用改。這套插件化思想是 Agent 能力能夠持續(xù)生長的基礎(chǔ)。另外解析 front-matter 時注意容錯別讓一個 Skill 的配置語法錯誤導(dǎo)致整個 Agent 啟動崩潰。5. 實現(xiàn)一個最小可復(fù)用的 Agent 核心循環(huán)5.1 狀態(tài)機(jī)的結(jié)構(gòu)設(shè)計前面概念講了不少現(xiàn)在進(jìn)入到寫代碼環(huán)節(jié)。我會做一個面向“日志異常分析”的最小 Agent它包含三個 Skill讀日志文件、查詢歷史故障知識庫、生成分析報告。這個任務(wù)足夠收斂又能把記憶、角色、主動性全部串起來。Agent 主循環(huán)的狀態(tài)管理我直接用字典保存完整代碼大概是import json import uuid class Agent: def __init__(self, llm, skill_loader, memory_store): self.llm llm self.skills skill_loader self.memory memory_store self.session_id str(uuid.uuid4()) def state_initial(self, user_request): # 初始化狀態(tài)目標(biāo)、任務(wù)描述、當(dāng)前進(jìn)度、決策歷史 return { session_id: self.session_id, goal: user_request, subtask_queue: [], plan: [], current_action_idx: 0, done: False } def decide_next_action(self, state): # 構(gòu)建 prompt包含角色設(shè)定 當(dāng)前狀態(tài)摘要 Skill 列表 可用記憶 messages self.compose_messages(state) # 模型決定下一步動作這里要求模型輸出 JSON response self.llm.chat(messages, response_formatjson) return self.parse_action(response)這里最需要精心設(shè)計的是compose_messages這個函數(shù)本質(zhì)上是把狀態(tài)、記憶、Skill 描述變成決策上下文喂給模型。我把它拆成三塊來看。角色設(shè)定塊。每次循環(huán)都注入但并不是一大段人設(shè)模板無腦堆疊而是把當(dāng)前任務(wù)目標(biāo)、角色邊界、行業(yè)背景寫進(jìn)去。例如“你是嵌入式方向資深代碼評審與日志分析助手只基于給定日志和知識庫信息下結(jié)論。禁止臆測寄存器位含義。若信息不足以得出結(jié)論必須明確說明缺乏依據(jù)?！边@里邊就有安全邊界和不確定處理策略。Skill 選擇清單塊。把所有可用 Skill 的name、description、parameters都列出來讓模型在每輪決策時都能看到自己能調(diào)用的“兵器庫”。這個動作倒不用每次貼全量。如果 Skill 數(shù)量大于十來個優(yōu)先讓模型做一次粗選再給粗選結(jié)果中的 Skill 暴露詳細(xì)參數(shù)。記憶摘要塊。從長期記憶里檢索與當(dāng)前任務(wù)相關(guān)的記錄比如歷史異常案例、用戶偏好、上次處理結(jié)論。記憶摘要是縮短“重新理解成本”的核心如果該塊缺失Agent 的“記憶”就名存實亡。實際執(zhí)行決策時我要求模型返回 JSON結(jié)構(gòu)統(tǒng)一為{ reasoning: 簡要說明為什么選這個動作, next_action: call_skill|reply|require_more, skill_name: read_log_file, parameters: { file_path: logs/uart.log, since: 2026-08-01T00:00:00 } }模型輸出了結(jié)構(gòu)化指令循環(huán)體就能像一個狀態(tài)機(jī)一樣往下走了。5.2 讓 Agent 真正跑起來的 Skill 執(zhí)行器寫執(zhí)行器時有一個細(xì)節(jié)非常關(guān)鍵Skill的執(zhí)行結(jié)果不一定是一次性成功的它可能返回的是中間信息、也可能拋異常。因此執(zhí)行器不能簡單地result skill.execute()就把結(jié)果塞給模型必須做一個統(tǒng)一的包裝和異常兜底。def run_skill(self, state, skill_name, params): if skill_name not in self.skills: return { status: failure, reason: funknown skill: {skill_name} } skill_def self.skills[skill_name] try: result skill_def[instance].execute(**params) except TypeError as e: # 參數(shù)不匹配兜底把異常信息返回給模型自行調(diào)整 return { status: parameter_error, message: f參數(shù)校驗失敗: {e}。請檢查參數(shù)說明后重試。 } except Exception as e: return { status: runtime_error, message: fSkill 執(zhí)行異常: {e} } return result針對參數(shù)不匹配的錯誤我給模型返回了一個“請檢查參數(shù)說明后重試”的信號這里面有一個重要的工程經(jīng)驗不要讓循環(huán)因為參數(shù)錯誤直接崩潰而要把錯誤交給模型去反思并修正。模型很多時候只是少傳了一個可選參數(shù)收到異常后它會自覺補調(diào)用參數(shù)。這種“模型自己修正自己”的機(jī)制能顯著提高多步驟任務(wù)的成功率。循環(huán)體在執(zhí)行完 Skill 后必須做一次“記憶吸收”把new_memories和中間觀測寫入記憶存儲。同時還需要更新狀態(tài)字典里的決策歷史格式簡單追加一條{action, skill_name, result_summary, time}即可。這些決策歷史將在下一輪決策中跟記憶摘要合并作為模型的輸入形成對任務(wù)全局的掌控感。5.3 寫一個能“記憶前文”的 Skill內(nèi)部狀態(tài)如何串起來為了展示“記憶”并非只能靠數(shù)據(jù)庫我特別演示一個帶內(nèi)部狀態(tài)翻轉(zhuǎn)的 Skill。這個 Skill 叫write_analysis_snapshot它負(fù)責(zé)把每一步的中間分析結(jié)果累積到一個會話級快照文件里。# skills/write_analysis_snapshot/main.py import json from pathlib import Path class Skill: name write_analysis_snapshot def __init__(self, context: AgentContext): self.context context self.snapshot_path context.data_dir / fsnapshot_{context.session_id}.json def execute(self, content: str, step: int): # 讀取既有快照不存在則初始化 snap {} if self.snapshot_path.exists(): snap json.loads(self.snapshot_path.read_text(encodingutf-8)) snap[fstep_{step}] content self.snapshot_path.write_text( json.dumps(snap, ensure_asciiFalse, indent2), encodingutf-8 ) return { output: f已保存第 {step} 步分析快照。, new_memories: [{ type: snapshot_update, content: f寫入快照 step_{step}, session_id: self.context.session_id }], status: success, metadata: {step: step, path: str(self.snapshot_path)} }這個例子的啟發(fā)性在于Skill不再只是無狀態(tài)函數(shù)它可以持有context操作會話級文件把一次任務(wù)過程中產(chǎn)生的中間狀態(tài)記錄下來。這對應(yīng)到現(xiàn)實場景就是Agent 分析了二十個日志文件后突然想回看第三步猜的寄存器配置不再需要從頭推演因為快照已經(jīng)在那里了。這比“讓模型自己記住”可靠得多。5.4 加一點“主動性”的味道Agent 自檢與繼續(xù)任務(wù)循環(huán)如何體現(xiàn)主動性我加一個叫self_check的調(diào)度能力。它的觸發(fā)條件不是用戶指令而是 Agent 在主循環(huán)中發(fā)現(xiàn)“子任務(wù)尚未完成且狀態(tài)不充分”的時候。比如日志分析 Agent 讀到一個中斷風(fēng)暴關(guān)鍵詞但當(dāng)前日志時間范圍只覆蓋了后半段它應(yīng)當(dāng)自己決定“我需要擴(kuò)大時間范圍重新讀一次日志”而不是停下來問用戶“您看接下來怎么辦”。這在代碼里表現(xiàn)為一個分支判斷當(dāng)模型決策返回的next_action是call_skill且目標(biāo) Skill 是read_log_file時循環(huán)體在更新完狀態(tài)后不結(jié)束繼續(xù)進(jìn)入下一輪決策。真正讓“主動”落在工程上的是給模型一個開放的動作空間并且明確告訴他“如果發(fā)現(xiàn)結(jié)果不完整你有權(quán)調(diào)用request_range_expansion這類 Skill 來自行補充任務(wù)”。我在狀態(tài)機(jī)里額外維護(hù)了一個attempt_count每執(zhí)行一輪循環(huán)就加一。當(dāng)它大于閾值比如 8循環(huán)強(qiáng)制退出把當(dāng)前摘要和已確認(rèn)結(jié)論交給用戶并對未決問題做透明度說明。設(shè)置這個上限是防止模型在一個錯誤的方向上反復(fù)自我修正永遠(yuǎn)跑不完。這里同樣體現(xiàn)了一個 Agent 設(shè)計原則既要給自由也要給邊界。6. 落地一份可查的記憶長期記憶與短時記憶的實現(xiàn)策略6.1 SQLite 方案與 JSON 方案對比關(guān)于記憶存儲很多教程會把向量數(shù)據(jù)庫說成默認(rèn)選項但我不建議你一上來就上重型組件。以最小閉環(huán)為目標(biāo)你只需要回答三個問題記憶存哪按什么查如何避免膨脹如果你只有幾十條記憶放在 JSON 文件里最方便。每次循環(huán)讀取整個文件、過濾出相關(guān)記錄丟給模型就行。缺點是數(shù)據(jù)量上來后全量讀取浪費 token也拖慢響應(yīng)。另一個方案是 SQLite輕量、無需獨立服務(wù)、支持條件查詢適合存幾千條以下的記憶記錄。這兩種方案前期的代碼復(fù)雜度差別不大SQLite 加一個標(biāo)準(zhǔn)庫即可搞定我推薦直接上 SQLite免得后期遷移。表結(jié)構(gòu)我就三張表極其簡單。-- 會話表 CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, user_id TEXT, created_at TEXT ); -- 事件事實表 CREATE TABLE memories ( memory_id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, memory_type TEXT, -- preference / fact / task_result / snapshot content TEXT, created_at TEXT ); -- 記憶來源索引表 CREATE TABLE memory_links ( link_id INTEGER PRIMARY KEY AUTOINCREMENT, memory_id INTEGER, source_skill TEXT, source_step INTEGER );這種設(shè)計刻意不去碰向量索引因為初期記憶規(guī)模很小SQLite 的LIKE查詢配合時間倒序已經(jīng)足夠。只有當(dāng)記憶條數(shù)奔著十萬條去、且你真的需要“語義相似召回”時才引入向量檢索這條路后頭好接。6.2 記憶寫入時的“歸納”習(xí)慣這條是我實際用的經(jīng)驗印象很深。剛開始我的 Agent 把日志原文大段寫入記憶沒過多久記憶庫就膨脹得沒法看了每次檢索都撈出一堆垃圾。后來我加了一條約束Skill 寫記憶前必須先做歸納而不是搬運全文。我在read_log_file的邏輯里加了剪裁函數(shù)超過一定長度的內(nèi)容不直接入記憶而是摘出關(guān)鍵行、數(shù)量統(tǒng)計、級別分布再讓大模型用一句話總結(jié)發(fā)生了什么。這個抽象的過程其實給 Agent 記憶質(zhì)量帶來了質(zhì)的提升。記住記憶的目標(biāo)不是“存檔”而是“讓未來的自己快速理解以前發(fā)生了什么”。降低記憶寫入的冗長度是長期維護(hù) Agent 最重要的一步。6.3 記憶的過期與優(yōu)先級讓 Agent 知道什么該忘這個點很多文章講不到但我認(rèn)為非常關(guān)鍵。記憶如果永遠(yuǎn)只增不減總有一天會把有效信息淹沒。我建議每個記憶帶一個priority字段從 0 到 5。偏好類記憶設(shè)置為 5 分例如“用戶偏好 C 語言實現(xiàn)方案”臨時過程信息設(shè)置為 1 分例如“某次運行輸出的第一行是 SPDIF data”。檢索時按(priority DESC, created_at DESC)拉取低于閾值的記錄不進(jìn)入模型上下文。同時增加一個簡單的每日清理動作刪除priority 1且創(chuàng)建時間超過 24 小時的記憶。這讓 Agent 的長期記憶更有彈性等任務(wù)跨周以后你回頭看這個設(shè)計能讓你少掉很多頭發(fā)。7. 給 Agent 注入角色感約束 Prompt、上下文模板與風(fēng)格護(hù)欄7.1 角色模板的工程化寫法前面說了角色要分三層我這里給一個可復(fù)用的模板結(jié)構(gòu)放在項目里叫agent_brain.md# Agent 角色說明書 你是「日志偵探」一名資深的嵌入式系統(tǒng)日志分析助理。 你擅長解析 UART/SPI/I2C 日志定位異常驅(qū)動、中斷風(fēng)暴、時序紊亂等問題。 ## 身份邊界 - 只依據(jù)用戶提供的日志與知識庫文件進(jìn)行分析。 - 禁止在沒有寄存器手冊的情況下猜測具體寄存器位含義。 - 不提供任何可導(dǎo)致設(shè)備物理損壞的操作建議。 ## 工作流程建議 1. 先讀取日志了解事件全貌。 2. 發(fā)現(xiàn)可疑模式時查詢歷史故障知識庫。 3. 結(jié)合記憶中的歷史結(jié)論形成推理鏈條。 4. 最終輸出結(jié)論時列出完整證據(jù)鏈。 ## 輸出風(fēng)格 - 先給結(jié)論后給證據(jù)。 - 每條結(jié)論需要有對應(yīng)日志行作為依據(jù)并標(biāo)注行號。 - 如果信息不足直接說“當(dāng)前信息不足以支撐該結(jié)論”。你可能會說這和普通 Prompt 有什么區(qū)別有但要配合代碼才會生效。我不會每輪循環(huán)無腦丟全部角色說明書而是把它切塊按需注入。只有在出現(xiàn)“是否需要懷疑方向”的決策點時才注入“工作流程建議”塊只有在要生成最終結(jié)論時才注入“輸出風(fēng)格”塊。這既控制了 token 開銷也讓模型在不同階段注意力更集中。7.2 輸出風(fēng)格護(hù)欄讓模型不“跑偏”的方法角色設(shè)定里有一部分不是給模型看的而是給后處理邏輯看的。我管它叫輸出風(fēng)格護(hù)欄。它可以實現(xiàn)為在模型生成完結(jié)果后跑一個輕量后處理函數(shù)檢查結(jié)果中是否包含“證據(jù)引用缺失”等違規(guī)情形。舉個例子日志分析 Agent 的最終報告要求每條結(jié)論必須有對應(yīng)日志行號。后處理函數(shù)逐個檢查結(jié)論文本如果某條結(jié)論后沒有形如L123的標(biāo)注就自動插入一句“該結(jié)論缺少行號參考已跳過”。別高估模型每次都會自覺遵守格式要求。端到端任務(wù)里越往后模型越容易松懈沒有后處理護(hù)欄報告格式最終會跑偏得很隨性。7.3 人設(shè)的“動態(tài)切換”機(jī)制一個 Agent 可以同時服務(wù)多種角色嗎可以但建議你給每個角色做一個獨立的角色上下文包而不是把多角色塞進(jìn)一段 Prompt 里來回切換。我用一個叫“角色上下文分流器”的方法在請求入口處先讓模型做一次輕量的意圖分類把“讓我看看日志”分到日志分析 Agent 通道把“幫我寫段代碼”分到代碼生成 Agent 通道。每個通道內(nèi)部都用完全獨立的角色設(shè)定、Skill 清單、記憶庫。這有個直接優(yōu)勢不同域的記憶天然隔離日志領(lǐng)域的觀察不會污染代碼生成領(lǐng)域的判斷。同時每個 Agent 能力范圍變小錯誤率也會降下來。很多商用 Agent 產(chǎn)品本質(zhì)上就是多個“單角色 Agent”的外殼路由這套架構(gòu)不花哨但非常穩(wěn)。8. 完整示例一個可復(fù)現(xiàn)的“帶記憶與主動性的日志分析 Agent”8.1 項目目錄與代碼骨架我直接給你一份可以直接跑的最小工程結(jié)構(gòu)方便你照著抄。log_agent/ ├── agent_brain.md ├── agent_core.py ├── llm.py ├── memory_store.py ├── skills/ │ ├── __init__.py │ ├── base.py │ ├── read_log_file/ │ │ ├── SKILL.md │ │ └── main.py │ ├── query_issue_kb/ │ │ ├── SKILL.md │ │ └── main.py │ ├── write_analysis_snapshot/ │ │ ├── SKILL.md │ │ └── main.py │ └── generate_report/ │ ├── SKILL.md │ └── main.py └── data/ ├── sqlite.db └── logs/ └── uart.logmemory_store.py里封裝 SQLite 的讀寫函數(shù)核心接口四個init_db()、add_memory()、search_memory()、cleanup_expired()。llm.py則做一層適配把通義、OpenAI 風(fēng)格 SDK 統(tǒng)一封裝成chat(messages, response_format)和embed(text)兩個方法。agent_core.py就是前面展示的主循環(huán)加執(zhí)行器實現(xiàn)組裝起來大概是這個流程啟動時加載 Skill 和記憶把用戶請求放入初始狀態(tài)循環(huán)調(diào)用decide_next_action直到doneTrue或到達(dá)輪次上限。8.2 跑一個完整任務(wù)演示假設(shè)用戶在交互框輸入“幫我分析data/logs/uart.log里為什么 UART 偶發(fā)亂碼并給出建議?！钡谝惠喲h(huán)模型讀到角色說明書 Skill 列表 當(dāng)前狀態(tài)。它選擇調(diào)用read_log_file傳參file_pathdata/logs/uart.log和keywordERROR。執(zhí)行器把日志中所有包含ERROR的行讀出來返回給模型并記錄一條摘要記憶。第二輪循環(huán)模型在決策歷史里發(fā)現(xiàn)日志中存在多個RX overrun事件。它知道項目學(xué)過的歷史故障知識庫里有overrun的相關(guān)案例于是調(diào)用query_issue_kb參數(shù)是keywordRX overrun。知識庫返回了歷史處理中的一條經(jīng)驗先查 FIFO 中斷閾值配置再查 DMA 描述符是否耗盡。第三輪循環(huán)模型發(fā)現(xiàn)這兩條信息已經(jīng)可以支撐初步結(jié)論但還缺一次完整印象。它決定調(diào)用write_analysis_snapshot把前兩輪的發(fā)現(xiàn)落一份到快照文件留給后續(xù)分析沉淀。第四輪循環(huán)模型調(diào)用generate_report。它綜合日志證據(jù)、知識庫經(jīng)驗和快照記錄生成一份包含三個證據(jù)點、兩個建議項的最終報告。輸出風(fēng)格按角色說明書要求每條證據(jù)都帶日志行號。到這里工作流結(jié)束Agent 返回報告給用戶。這就是一個完整的“有記憶、有角色、有主動性”的 Agent 工作過程。你看著很自然但如果沒有 Skill 的封裝、沒有記憶的沉淀、沒有每一輪“自己決定下一步”的循環(huán)機(jī)制單靠一次大模型調(diào)用是不可能走完這個鏈路的。8.3 效果評價與調(diào)優(yōu)方向跑完一輪后怎么確認(rèn)這個 Agent 是合格的我用的評價項很簡單任務(wù)完成率、工具調(diào)用準(zhǔn)確率、記憶檢索準(zhǔn)確率、最終報告的事實一致性。前三個指標(biāo)可以靠人工抽樣統(tǒng)計最后一個我會專門讓另一個 LLM 實例做裁判檢查報告結(jié)論是否能從執(zhí)行日志中找到證據(jù)支撐。如果任務(wù)完成率不高先別著急換模型。你按這個順序排查Skill 描述是不是準(zhǔn)確角色說明書是否約束了不當(dāng)輸出記憶檢索有沒有帶回正確信息執(zhí)行器異常兜底有沒有把修正機(jī)會還給模型。這個排查順序幾乎覆蓋了我的所有實戰(zhàn)調(diào)優(yōu)場景。9. 常見問題與排查技巧實錄9.1 為什么 Agent 總是選錯 Skill 或重復(fù)執(zhí)行同一步這個問題我遇到最多也最容易被歸咎于“模型笨”。實際上多數(shù)原因是 Skill 清單里的描述太相似了尤其是name、description和when_to_use區(qū)分度不夠模型犯迷糊。排查建議是把全部 Skill 名稱和描述打成一個大表站在模型視角看能不能一眼分清“什么時候選誰”。如果自己也分不清說明描述寫得過于抽象。重寫時要盡量寫清適用場景和反面場景比如read_log_file的描述可以寫成“當(dāng)你需要讀取/查看一個日志文件的原始內(nèi)容或篩選后的內(nèi)容行時使用。如果用戶希望直接得到分析結(jié)論而不是原始日志內(nèi)容推薦使用analyze_log技能”。重復(fù)執(zhí)行同一步的問題通常由狀態(tài)更新不及時引起。要檢查模型決策完有沒有把動作追加到decision_history并讓新狀態(tài)真正參與下一輪compose_messages。很多時候歷史沒喂回去模型以為自己還沒看過某個文件于是反復(fù)讀同一份日志。9.2 模型輸出亂 JSON 或虛構(gòu)參數(shù)怎么處理現(xiàn)在的大模型雖然支持結(jié)構(gòu)化輸出但偶爾仍然會出現(xiàn)格式不合法、參數(shù)名臆造問題。建議從兩個層面預(yù)防。第一個層面是模型層約束要求模型按 JSON Schema 輸出并設(shè)定temperature較低。第二個層面是代碼層約束增加一個repair_json函數(shù)用容錯解析邏輯過濾掉散落文本直接把最外層{...}提取出來再解析。如果解析還是失敗將原始輸出返回給模型并在提示里明確說明“你的輸出 JSON 解析失敗{錯誤信息}請只輸出合法 JSON”給它一個“補考”的機(jī)會。參數(shù)名虛構(gòu)通常是 Skill 配置里沒有對參數(shù)做嚴(yán)格枚舉。最簡單有效的辦法是在 Skill 描述文本里把參數(shù)說明再次寫清楚甚至給示例值。模型看到示例以后往往能瞬間學(xué)會正確傳參這比在代碼里做一堆參數(shù)校驗更省事。9.3 記憶庫膨脹、上下文超限怎么處理記憶庫膨脹最典型的征兆是每次決策的輸入里帶上了一大堆過期的舊信息模型決策速度變慢且容易被噪聲誤導(dǎo)。我之前靠 SQLite 的priority和created_at字段做了衰減處理已經(jīng)能緩解一大半問題。如果仍然上下文超限可以在compose_messages階段按三類做截斷角色說明書只保留關(guān)鍵片段記憶摘要取最近 5 條加最高優(yōu)先級 5 條決策歷史只保留最近 3 輪摘要。還有一個技巧每次模型執(zhí)行完一輪 Skill 后不要把它返回的所有文本原封不動存進(jìn)記憶庫而是先用一個壓縮摘要函數(shù)把關(guān)鍵結(jié)論提取出來。這個壓縮可以由 LLM 完成也可以直接采樣關(guān)鍵句。壓縮后入庫的記憶大大降低后續(xù)上下文的壓力效果立竿見影。9.4 主動性的邊界Agent 自己越想越偏怎么辦自由規(guī)劃型循環(huán)最怕的一件事情是模型在某個錯誤的中間結(jié)論上反復(fù)調(diào)用 Skill 自我驗證形成死循環(huán)。比如它懷疑某個中斷標(biāo)志被錯誤置位于是反復(fù)讀寄存器配置文檔每次都得不到明確答案然后它繼續(xù)換著關(guān)鍵詞查任務(wù)遲遲不結(jié)束。我的實操解法是雙重限制第一限制每個任務(wù)總循環(huán)次數(shù)比如 8 輪第二在decide_next_action的提示中顯式加入一條規(guī)則——如果最近兩次動作里已經(jīng)包含三次同 Skill 調(diào)用且沒有新事實產(chǎn)生允許你在不調(diào)用 Skill 的情況下直接整理已知信息并給用戶一個階段性的結(jié)論不要強(qiáng)行追求完美答案。這種“允許在不確定中收尾”的指令反而是讓 Agent 更可靠的關(guān)鍵它減少了無意義的空轉(zhuǎn)。9.5 Skill 數(shù)量多了之后Agent 決策反而變差怎么辦這是個非常現(xiàn)實的問題。Skill 清單一兩頁時還好數(shù)量漲到十個以上模型每次都要在長上下文里挑工具偶爾就會漏掉更優(yōu)的工具。解決路徑有兩條一條是分層路由首頁只展示幾個粗顆粒度的入口 Skill比如“日志分析”“代碼生成”“知識檢索”具體執(zhí)行子 Skill 由入口注冊時、選擇后的局部清單來暴露。另一條是對 Skill 做向量檢索匹配先按文本相似度召回 Top 5 個候選再把這些候選的描述交給模型精確決策。第二種方案在規(guī)模大的場景更有優(yōu)勢適合后邊需要擴(kuò)展的讀者嘗試。10. 我個人踩過的一些坑最后分享幾個非常具體、但教科書里不會寫的經(jīng)驗。第一Skill目錄的命名盡量用項目主題相關(guān)的短橫線風(fēng)格不要用中文名。我發(fā)現(xiàn)有些框架解析時能處理中文文件名但日志追蹤和異常報錯信息里一旦混入中文路徑字符排查起來會痛苦得多。第二Agent Loop里的每輪請求最好在消息結(jié)構(gòu)里帶上當(dāng)前的動作序號和總規(guī)劃哪怕是兩句話的摘要也能顯著增強(qiáng)模型對任務(wù)階段的感知力。比如狀態(tài)里寫一條progress: 第2步/共5步已完成日志讀取正在查詢知識庫模型下一輪決策時會更像在“順著進(jìn)度往下走”而不是重新開始找切入點。第三不要省掉“記憶寫入成功”的反饋信號。每次 Skill 返回new_memories并且寫入成功后要把“已成功記憶以下內(nèi)容xxx”反饋到模型上下文。模型如果知道自己的動作產(chǎn)生了持久化影響后續(xù)決策會明顯更篤定。這個小改動聽上去很玄學(xué)但我實測下來確實能讓 Agent 的行為顯得更“有意識”。第四如果你做的是面向記錄、知識積累類的 Agent強(qiáng)烈建議每一輪循環(huán)都把Skill調(diào)用參數(shù)和返回結(jié)果的摘要保存到本地日志方便之后復(fù)現(xiàn)問題和復(fù)盤。Agent 是一個動態(tài)決策系統(tǒng)不像普通程序那樣“輸入相同輸出相同”。沒有決策留痕你根本無從判斷某次劣質(zhì)輸出是模型抽風(fēng)、記憶誤導(dǎo)還是 Skill 本身報錯。這個審計日志是你調(diào)試 Agent 時最重要的抓手。這套東西看起來有不少概念其實核心就一句話Skill是 Agent 的行動抓手記憶是它的長期底盤角色是它的行為邊界主動循環(huán)是它的引擎。四者拼到一起它才不再是一個“你問一句、它答一句”的聊天機(jī)器人而是像一個真正有經(jīng)驗的新人——知輕重、記得事、會自己往后走。我第一次把這套循環(huán)跑通的時候看著模型自己在日志里查出隱患、查過歷史案例、做出帶證據(jù)鏈的報告還是挺震撼的。希望這篇一步步拆解的實操內(nèi)容也能幫你體會到這種“把模型變成能干活的人”的感覺。寫完第一版之后不要停在這里你可以再給它加新的 Skill、換更大的記憶方案、調(diào)整角色模板讓它越來越接近你想要的那個形態(tài)。