戰(zhàn)：從零構(gòu)建具備天氣查詢與郵件發(fā)送技能的智能體)
在實(shí)際的大模型應(yīng)用開(kāi)發(fā)中很多開(kāi)發(fā)者會(huì)遇到一個(gè)瓶頸模型本身能力很強(qiáng)但如何讓它真正“動(dòng)起來(lái)”完成一個(gè)連貫、多步驟的復(fù)雜任務(wù)比如讓大模型不僅能回答天氣還能根據(jù)天氣為你規(guī)劃出行、預(yù)訂會(huì)議室、并發(fā)送郵件通知。這背后依賴的核心技術(shù)就是Agent智能體而賦予 Agent 執(zhí)行具體任務(wù)能力的則是Skills技能。對(duì)于剛接觸大模型落地的開(kāi)發(fā)者和技術(shù)愛(ài)好者而言理解并實(shí)踐 Agent Skills 是打通“模型對(duì)話”到“實(shí)際應(yīng)用”的關(guān)鍵一步。本文將從工程實(shí)踐角度帶你一步步掌握如何為大模型 Agent 構(gòu)建和集成 Skills。我們將不局限于理論而是通過(guò)一個(gè)從零開(kāi)始的實(shí)戰(zhàn)案例涵蓋環(huán)境準(zhǔn)備、技能定義、Agent 調(diào)度、本地部署與測(cè)試的完整閉環(huán)。你會(huì)學(xué)到如何將一個(gè)簡(jiǎn)單的“查詢天氣”和“發(fā)送郵件”的想法轉(zhuǎn)化為一個(gè)能自主決策、按需調(diào)用工具的可運(yùn)行智能體。無(wú)論你是希望將 AI 能力集成到現(xiàn)有業(yè)務(wù)系統(tǒng)的程序員還是對(duì) AI 應(yīng)用開(kāi)發(fā)充滿好奇的學(xué)習(xí)者這篇指南都將提供一條清晰的、可復(fù)現(xiàn)的路徑。1. 理解 Agent 與 Skills從“聊天”到“做事”的跨越在深入代碼之前必須厘清幾個(gè)核心概念。這能幫助你在后續(xù)開(kāi)發(fā)中做出正確的設(shè)計(jì)決策避免將 Agent 簡(jiǎn)單理解為“帶工具的聊天機(jī)器人”。1.1 什么是 Agent智能體在大模型語(yǔ)境下Agent 是一個(gè)能夠感知環(huán)境、進(jìn)行決策并執(zhí)行行動(dòng)以實(shí)現(xiàn)目標(biāo)的系統(tǒng)。你可以把它想象成一個(gè)擁有“大腦”大模型和“手腳”工具的虛擬助手。核心組件一個(gè)典型的 Agent 包含三個(gè)部分規(guī)劃Planning大腦大模型負(fù)責(zé)理解用戶目標(biāo)并將其分解為一系列可執(zhí)行的子任務(wù)或步驟。記憶Memory存儲(chǔ)對(duì)話歷史、工具調(diào)用結(jié)果和知識(shí)為后續(xù)決策提供上下文。工具使用Tool Use根據(jù)規(guī)劃調(diào)用外部的 Skills/Tools 來(lái)執(zhí)行具體操作如查詢數(shù)據(jù)庫(kù)、調(diào)用 API、操作文件等。與普通聊天的區(qū)別普通的大模型對(duì)話是“一問(wèn)一答”答案基于其訓(xùn)練數(shù)據(jù)。而 Agent 是“目標(biāo)導(dǎo)向”的它會(huì)主動(dòng)思考“為了完成用戶請(qǐng)求我需要先做什么再做什么”并調(diào)用外部能力來(lái)補(bǔ)足模型自身無(wú)法直接完成的事情如獲取實(shí)時(shí)數(shù)據(jù)、操作外部系統(tǒng)。1.2 什么是 Skills/Tools技能/工具Skills 或 Tools 是 Agent 可以調(diào)用的具體功能單元。它們是 Agent 的“手腳”將模型的“思考”轉(zhuǎn)化為對(duì)現(xiàn)實(shí)世界的“影響”。本質(zhì)一個(gè) Skill 通常對(duì)應(yīng)一個(gè)函數(shù)Function、一個(gè) API 接口或一個(gè)命令行工具。它有著明確的輸入?yún)?shù)、執(zhí)行邏輯和輸出結(jié)果。與大模型的關(guān)系大模型本身不執(zhí)行Skill。它的角色是1理解用戶需求后判斷是否需要調(diào)用 Skill2如果需要?jiǎng)t生成符合該 Skill 定義的調(diào)用參數(shù)JSON 格式3解析 Skill 執(zhí)行后的結(jié)果并組織成自然語(yǔ)言回復(fù)給用戶。常見(jiàn)類型信息獲取類如get_weather獲取天氣、search_web網(wǎng)絡(luò)搜索、query_database查詢數(shù)據(jù)庫(kù)。操作執(zhí)行類如send_email發(fā)送郵件、create_calendar_event創(chuàng)建日歷事件、execute_shell_command執(zhí)行Shell命令需謹(jǐn)慎。計(jì)算與處理類如calculate計(jì)算器、format_json格式化JSON。1.3 Agent 如何與 Skills 協(xié)同工作其工作流是一個(gè)典型的“思考-行動(dòng)-觀察”循環(huán)ReAct 模式用戶輸入“明天上海天氣如何如果下雨提醒我?guī)?。”Agent 規(guī)劃模型思考后認(rèn)為需要兩步a) 獲取上海明天天氣b) 根據(jù)天氣結(jié)果決定是否發(fā)送提醒。調(diào)用 Skill 1Agent 調(diào)用get_weatherSkill傳入?yún)?shù){“l(fā)ocation”: “上海” “date”: “tomorrow”}。觀察結(jié)果Skill 返回{“weather”: “rain” “temperature”: “18-22°C”}。Agent 再規(guī)劃模型觀察到“rain”判斷需要執(zhí)行提醒。調(diào)用 Skill 2Agent 調(diào)用send_reminderSkill傳入?yún)?shù){“message”: “明天上海有雨請(qǐng)帶傘?！眪。最終回復(fù)Agent 綜合所有結(jié)果向用戶回復(fù)“明天上海有雨氣溫18-22°C。我已經(jīng)為您設(shè)置了帶傘的提醒?！边@個(gè)流程的關(guān)鍵在于大模型負(fù)責(zé)高層的任務(wù)分解和決策而 Skills 負(fù)責(zé)底層的、確定性的執(zhí)行。接下來(lái)我們將通過(guò)實(shí)戰(zhàn)親手構(gòu)建這樣一個(gè)流程。2. 環(huán)境準(zhǔn)備與框架選型在開(kāi)始編碼前我們需要搭建開(kāi)發(fā)環(huán)境并選擇一個(gè)合適的 Agent 開(kāi)發(fā)框架?？蚣苣軒臀覀兲幚砼c大模型的對(duì)話、Skill 的注冊(cè)與管理、調(diào)用流程控制等通用邏輯讓我們專注于業(yè)務(wù)技能的實(shí)現(xiàn)。2.1 主流 Agent 開(kāi)發(fā)框架簡(jiǎn)介目前社區(qū)有多種框架各有側(cè)重。對(duì)于新手和大多數(shù)應(yīng)用場(chǎng)景我們推薦從LangChain或Semantic Kernel開(kāi)始?？蚣苤饕Z(yǔ)言特點(diǎn)適用場(chǎng)景LangChainPython / JS生態(tài)豐富社區(qū)活躍文檔齊全概念體系完整?？焖僭万?yàn)證研究探索復(fù)雜的鏈?zhǔn)秸{(diào)用。Semantic KernelPython / C# / Java微軟出品與.NET生態(tài)集成好強(qiáng)調(diào)“插件”模式。企業(yè)級(jí)應(yīng)用尤其是已有 .NET 技術(shù)棧的項(xiàng)目。LlamaIndexPython專注于數(shù)據(jù)索引與檢索構(gòu)建RAG應(yīng)用能力強(qiáng)。需要與私有知識(shí)庫(kù)深度結(jié)合的Agent。AutoGenPython支持多Agent協(xié)作對(duì)話場(chǎng)景模擬能力強(qiáng)。需要多個(gè)Agent分工協(xié)作的復(fù)雜任務(wù)。本文選擇LangChain (Python版)進(jìn)行演示因?yàn)樗鼘W(xué)習(xí)曲線相對(duì)平緩且網(wǎng)上資源最多遇到問(wèn)題容易找到解決方案。2.2 基礎(chǔ)環(huán)境搭建請(qǐng)確保你的系統(tǒng)已安裝 Python (推薦 3.8-3.11版本)。我們將使用venv創(chuàng)建獨(dú)立的虛擬環(huán)境。# 1. 創(chuàng)建項(xiàng)目目錄并進(jìn)入 mkdir agent-skills-demo cd agent-skills-demo # 2. 創(chuàng)建虛擬環(huán)境 (Windows 用戶使用 python -m venv venv) python3 -m venv venv # 3. 激活虛擬環(huán)境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 升級(jí)pip pip install --upgrade pip2.3 安裝核心依賴我們將安裝 LangChain 及其與 OpenAI 模型交互的包。如果你使用其他模型如通義千問(wèn)、文心一言等需安裝對(duì)應(yīng)的 LangChain 集成包。# 安裝 LangChain 核心包和 OpenAI 集成包 pip install langchain langchain-openai # 安裝用于定義Tools/Skills的社區(qū)包包含一些常用工具 pip install langchain-community # 安裝用于解析模型輸出的包重要用于將模型回復(fù)解析為工具調(diào)用 pip install langchain-core注意本文示例將使用 OpenAI 的 GPT 模型作為 Agent 的“大腦”。你需要準(zhǔn)備一個(gè)有效的 OpenAI API Key。如果你希望完全本地運(yùn)行后續(xù)章節(jié)會(huì)介紹使用 Ollama 部署本地模型作為替代方案。2.4 項(xiàng)目結(jié)構(gòu)初始化一個(gè)清晰的項(xiàng)目結(jié)構(gòu)有助于管理 Skills 和 Agent 配置。agent-skills-demo/ ├── venv/ # Python虛擬環(huán)境.gitignore忽略 ├── skills/ # 存放自定義技能模塊 │ ├── __init__.py │ ├── weather_tool.py # 天氣查詢技能 │ └── email_tool.py # 郵件發(fā)送技能 ├── agents/ # 存放Agent定義 │ ├── __init__.py │ └── task_agent.py # 任務(wù)執(zhí)行Agent ├── config.py # 配置文件如API密鑰 ├── requirements.txt # 項(xiàng)目依賴 └── main.py # 主程序入口創(chuàng)建上述目錄和文件除venv外mkdir skills agents touch skills/__init__.py skills/weather_tool.py skills/email_tool.py touch agents/__init__.py agents/task_agent.py touch config.py requirements.txt main.py將當(dāng)前安裝的依賴導(dǎo)出到requirements.txtpip freeze requirements.txt至此基礎(chǔ)環(huán)境準(zhǔn)備完畢。接下來(lái)我們將動(dòng)手實(shí)現(xiàn)第一個(gè) Skill。3. 實(shí)戰(zhàn)構(gòu)建你的第一個(gè)自定義 Skill我們將構(gòu)建一個(gè)模擬的get_weather技能。在生產(chǎn)環(huán)境中這個(gè)技能應(yīng)該調(diào)用真實(shí)的天氣 API如和風(fēng)天氣、OpenWeatherMap。為了簡(jiǎn)化演示我們模擬其邏輯。3.1 定義 Weather Skill編輯skills/weather_tool.py文件from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type class WeatherToolInput(BaseModel): 天氣查詢工具的輸入?yún)?shù)模式。 location: str Field(description需要查詢天氣的城市名稱例如北京、上海) date: Optional[str] Field(defaulttoday, description查詢?nèi)掌诶鐃oday, tomorrow, 2024-05-20。默認(rèn)為今天。) class WeatherTool(BaseTool): 一個(gè)模擬的天氣查詢工具。在實(shí)際應(yīng)用中應(yīng)替換為真實(shí)的天氣API調(diào)用。 name: str get_weather description: str ( 根據(jù)城市和日期查詢天氣信息。 輸入應(yīng)包含‘location’城市名和可選的‘date’日期。 ) args_schema: Type[BaseModel] WeatherToolInput def _run(self, location: str, date: str today) - str: 執(zhí)行工具的主邏輯。 # 模擬API調(diào)用和數(shù)據(jù)處理 # 真實(shí)場(chǎng)景下這里會(huì)是 requests.get(weather_api_url, params{...}) weather_data { 北京: {today: 晴15-25°C, tomorrow: 多云18-28°C}, 上海: {today: 小雨18-22°C, tomorrow: 陰19-24°C}, 深圳: {today: 雷陣雨25-30°C, tomorrow: 多云26-31°C}, } city_weather weather_data.get(location) if not city_weather: return f抱歉未找到城市 {location} 的天氣信息。 forecast city_weather.get(date, city_weather.get(today, 暫無(wú)數(shù)據(jù))) return f{location} {date} 的天氣是{forecast} async def _arun(self, location: str, date: str today) - str: 異步執(zhí)行版本。如果不需要異步可以直接調(diào)用同步方法。 return self._run(location, date)關(guān)鍵點(diǎn)解析繼承BaseTool所有 LangChain 工具都需要繼承此類。name和description至關(guān)重要大模型根據(jù)description來(lái)判斷何時(shí)調(diào)用此工具。描述應(yīng)清晰準(zhǔn)確。args_schema使用 Pydantic 模型定義輸入?yún)?shù)的結(jié)構(gòu)和類型。這能幫助大模型生成格式正確的調(diào)用參數(shù)。_run方法工具的核心執(zhí)行邏輯。這里我們用一個(gè)字典模擬了數(shù)據(jù)返回。_arun方法異步版本。如果工具涉及網(wǎng)絡(luò)I/O實(shí)現(xiàn)異步版本能提升效率。3.2 定義 Email Skill同樣我們模擬一個(gè)發(fā)送郵件的工具。編輯skills/email_tool.pyfrom langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Type import smtplib from email.mime.text import MIMEText from email.header import Header import config # 我們將配置放在config.py中 class EmailToolInput(BaseModel): 郵件發(fā)送工具的輸入?yún)?shù)模式。 recipient: str Field(description收件人郵箱地址) subject: str Field(description郵件主題) body: str Field(description郵件正文內(nèi)容) class EmailTool(BaseTool): 郵件發(fā)送工具。需要預(yù)先配置SMTP服務(wù)器信息。 name: str send_email description: str ( 發(fā)送一封電子郵件到指定的收件人。 輸入需要收件人地址recipient、主題subject和正文body。 ) args_schema: Type[BaseModel] EmailToolInput def _run(self, recipient: str, subject: str, body: str) - str: 執(zhí)行發(fā)送郵件的邏輯。 # 注意這是一個(gè)示例生產(chǎn)環(huán)境需要更安全的密碼管理如環(huán)境變量、密鑰管理服務(wù)。 # 這里從config模塊讀取配置 smtp_server config.SMTP_SERVER smtp_port config.SMTP_PORT sender_email config.SENDER_EMAIL sender_password config.SENDER_PASSWORD # 可能是授權(quán)碼而非登錄密碼 # 構(gòu)建郵件 message MIMEText(body, plain, utf-8) message[From] Header(sender_email) message[To] Header(recipient) message[Subject] Header(subject) try: # 連接服務(wù)器并發(fā)送 with smtplib.SMTP_SSL(smtp_server, smtp_port) as server: # 使用SSL server.login(sender_email, sender_password) server.sendmail(sender_email, [recipient], message.as_string()) return f郵件已成功發(fā)送至 {recipient} except Exception as e: return f郵件發(fā)送失敗錯(cuò)誤信息{str(e)} async def _arun(self, recipient: str, subject: str, body: str) - str: return self._run(recipient, subject, body)關(guān)鍵點(diǎn)解析依賴外部服務(wù)此工具依賴 SMTP 服務(wù)器。我們將其配置外置到config.py。錯(cuò)誤處理在_run方法中使用了 try-except 塊確保將任何異常轉(zhuǎn)化為字符串結(jié)果返回給 Agent避免整個(gè)流程因一個(gè)工具錯(cuò)誤而崩潰。安全警告代碼中直接引用了密碼這僅用于演示。在生產(chǎn)環(huán)境中務(wù)必使用環(huán)境變量或?qū)I(yè)的密鑰管理服務(wù)來(lái)存儲(chǔ)敏感信息。3.3 創(chuàng)建配置文件編輯config.py存放敏感信息和配置# config.py # 安全提示切勿將此文件提交至版本控制系統(tǒng)如Git。請(qǐng)將其加入 .gitignore。 # 實(shí)際項(xiàng)目中應(yīng)使用環(huán)境變量。 # OpenAI API 配置 OPENAI_API_KEY sk-your-openai-api-key-here # 替換為你的真實(shí)Key OPENAI_BASE_URL https://api.openai.com/v1 # 如果你使用代理或特定端點(diǎn)可修改此項(xiàng) # 郵件SMTP服務(wù)器配置 (以QQ郵箱為例需要開(kāi)啟SMTP服務(wù)并獲取授權(quán)碼) SMTP_SERVER smtp.qq.com SMTP_PORT 465 # QQ郵箱SSL端口 SENDER_EMAIL your-emailqq.com SENDER_PASSWORD your-authorization-code # 注意是授權(quán)碼不是郵箱密碼 # 其他模型配置如后續(xù)使用本地模型 LOCAL_MODEL_PATH 記得創(chuàng)建.gitignore文件忽略配置和虛擬環(huán)境venv/ __pycache__/ *.pyc config.py現(xiàn)在我們已經(jīng)有了兩個(gè)可用的 Skills。下一步是創(chuàng)建 Agent并將這些 Skills 裝配給它。4. 創(chuàng)建并運(yùn)行你的第一個(gè) Agent有了 Skills我們需要一個(gè)“大腦”來(lái)調(diào)度它們。我們將使用 LangChain 的create_react_agent來(lái)構(gòu)建一個(gè)遵循 ReAct 推理模式的 Agent。4.1 構(gòu)建 Task Agent編輯agents/task_agent.pyfrom langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from skills.weather_tool import WeatherTool from skills.email_tool import EmailTool import config def build_task_agent(): 構(gòu)建并返回一個(gè)配備了天氣和郵件工具的Agent執(zhí)行器。 # 1. 初始化大語(yǔ)言模型LLM作為Agent的大腦 # 這里使用 GPT-3.5-turbo對(duì)于工具調(diào)用任務(wù)足夠且成本較低。 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 溫度設(shè)為0使輸出更確定更適合工具調(diào)用 openai_api_keyconfig.OPENAI_API_KEY, base_urlconfig.OPENAI_BASE_URL, ) # 2. 準(zhǔn)備工具列表 tools [WeatherTool(), EmailTool()] # 3. 從LangChain Hub獲取一個(gè)預(yù)設(shè)的ReAct提示詞模板 # 這個(gè)模板會(huì)指導(dǎo)LLM按照“Thought/Action/Action Input/Observation”的格式進(jìn)行推理。 prompt hub.pull(hwchase17/react) # 4. 使用工具、LLM和提示詞創(chuàng)建ReAct Agent agent create_react_agent(llm, tools, prompt) # 5. 創(chuàng)建Agent執(zhí)行器它負(fù)責(zé)運(yùn)行Agent的循環(huán)直到返回最終答案。 # handle_parsing_errorsTrue 很重要當(dāng)模型輸出格式不符合工具調(diào)用格式時(shí)嘗試修復(fù)。 # verboseTrue 會(huì)在控制臺(tái)打印詳細(xì)的推理步驟便于調(diào)試。 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations5, # 限制最大循環(huán)次數(shù)防止無(wú)限循環(huán) early_stopping_methodgenerate, # 當(dāng)模型認(rèn)為不需要再調(diào)用工具時(shí)直接生成最終回復(fù) ) return agent_executor if __name__ __main__: # 本地測(cè)試這個(gè)Agent agent_executor build_task_agent() test_query 明天上海的天氣怎么樣如果下雨發(fā)郵件到 testexample.com 提醒我?guī)恪?print(f用戶提問(wèn): {test_query}) result agent_executor.invoke({input: test_query}) print(f\nAgent最終回復(fù): {result[output]})4.2 編寫(xiě)主程序并運(yùn)行測(cè)試編輯main.py作為應(yīng)用的啟動(dòng)入口# main.py from agents.task_agent import build_task_agent def main(): print(初始化任務(wù)智能體...) agent build_task_agent() print(\n智能體就緒請(qǐng)輸入您的問(wèn)題輸入 quit 或 exit 退出:) while True: try: user_input input(\n ) if user_input.lower() in [quit, exit]: print(再見(jiàn)) break if not user_input.strip(): continue # 調(diào)用Agent執(zhí)行器 result agent.invoke({input: user_input}) print(f\n {result[output]}) except KeyboardInterrupt: print(\n程序被中斷。) break except Exception as e: print(f\n處理請(qǐng)求時(shí)發(fā)生錯(cuò)誤: {e}) if __name__ __main__: main()4.3 首次運(yùn)行與驗(yàn)證在運(yùn)行前請(qǐng)確保config.py中的OPENAI_API_KEY已填寫(xiě)正確。激活虛擬環(huán)境如果已退出source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows運(yùn)行主程序python main.py觀察輸出 程序會(huì)加載模型和工具。當(dāng)你輸入測(cè)試問(wèn)題后由于verboseTrue控制臺(tái)會(huì)打印出類似以下的詳細(xì)推理過(guò)程Thought/Action/Action Input/Observation初始化任務(wù)智能體... 智能體就緒請(qǐng)輸入您的問(wèn)題輸入 quit 或 exit 退出: 明天上海的天氣怎么樣如果下雨發(fā)郵件到 testexample.com 提醒我?guī)恪? 進(jìn)入新的AgentExecutor鏈... 我需要先查詢明天上海的天氣然后根據(jù)天氣情況決定是否發(fā)送郵件。 行動(dòng)get_weather 行動(dòng)輸入{location: 上海, date: tomorrow} 觀察上海 tomorrow 的天氣是陰19-24°C 思考天氣是陰天沒(méi)有下雨所以不需要發(fā)送提醒郵件。我可以直接回復(fù)用戶。 最終答案明天上海是陰天氣溫在19到24攝氏度之間。根據(jù)預(yù)報(bào)沒(méi)有雨所以不需要提醒帶傘。 鏈結(jié)束。 明天上海是陰天氣溫在19到24攝氏度之間。根據(jù)預(yù)報(bào)沒(méi)有雨所以不需要提醒帶傘。這個(gè)輸出清晰地展示了 Agent 的思考過(guò)程它先決定調(diào)用天氣工具根據(jù)返回結(jié)果陰天判斷無(wú)需調(diào)用郵件工具最終生成回復(fù)。恭喜你已經(jīng)成功創(chuàng)建了一個(gè)具備多步推理和工具調(diào)用能力的智能體。接下來(lái)我們要解決一個(gè)關(guān)鍵問(wèn)題如何在不依賴 OpenAI 的情況下在本地運(yùn)行這個(gè) Agent5. 進(jìn)階使用 Ollama 本地部署與集成依賴云端 API 存在成本、延遲和隱私問(wèn)題。對(duì)于開(kāi)發(fā)測(cè)試或內(nèi)部應(yīng)用在本地部署開(kāi)源大模型是更優(yōu)選擇。Ollama是一個(gè)強(qiáng)大的工具可以讓你在本地輕松運(yùn)行如 Llama 3、Mistral、Qwen 等主流開(kāi)源模型。5.1 安裝與運(yùn)行 Ollama訪問(wèn) Ollama 官網(wǎng)根據(jù)你的操作系統(tǒng)macOS, Linux, Windows下載并安裝。安裝完成后打開(kāi)終端拉取一個(gè)模型。我們選擇輕量且性能不錯(cuò)的qwen2.5:7b通義千問(wèn)2.5 7B版本ollama pull qwen2.5:7b這會(huì)下載約 4-5GB 的模型文件。運(yùn)行模型服務(wù)ollama run qwen2.5:7b這會(huì)啟動(dòng)一個(gè)交互式對(duì)話。但我們需要的是 API 服務(wù)。讓 Ollama 在后臺(tái)以 API 模式運(yùn)行# 停止剛才的交互式會(huì)話 (CtrlC) # 啟動(dòng)API服務(wù)默認(rèn)監(jiān)聽(tīng) 11434 端口 ollama serve # 或者直接運(yùn)行 ollama serve 并在新終端窗口進(jìn)行后續(xù)操作5.2 修改 Agent 以使用本地模型我們需要修改agents/task_agent.py中的 LLM 初始化部分使其指向本地的 Ollama 服務(wù)。首先安裝 LangChain 與 Ollama 集成的包如果尚未安裝pip install langchain-ollama然后修改build_task_agent函數(shù)或創(chuàng)建一個(gè)新的函數(shù)如build_local_agent# 在 agents/task_agent.py 頂部導(dǎo)入 from langchain_ollama import ChatOllama def build_local_agent(): 構(gòu)建使用本地Ollama模型的Agent。 # 1. 初始化本地LLM llm ChatOllama( modelqwen2.5:7b, # 與 ollama pull 的模型名一致 base_urlhttp://localhost:11434, # Ollama 默認(rèn)API地址 temperature0, # 對(duì)于工具調(diào)用可能需要調(diào)整一些參數(shù)以提升格式遵循能力 # num_ctx4096, # 可調(diào)整上下文長(zhǎng)度 ) # 2. 準(zhǔn)備工具列表 (與之前相同) tools [WeatherTool(), EmailTool()] # 3. 獲取提示詞模板 prompt hub.pull(hwchase17/react) # 4. 5. 創(chuàng)建Agent和執(zhí)行器 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations5, early_stopping_methodgenerate, ) return agent_executor關(guān)鍵點(diǎn)解析ChatOllama這是 LangChain 為 Ollama 提供的專用聊天模型類。base_url指向本地運(yùn)行的 Ollama API 服務(wù)器。模型能力并非所有開(kāi)源模型都擅長(zhǎng)嚴(yán)格的工具調(diào)用格式JSON。qwen2.5、llama3、mistral等較新的模型對(duì)此支持較好。如果遇到格式解析錯(cuò)誤可能需要嘗試不同模型或微調(diào)提示詞。5.3 測(cè)試本地 Agent修改main.py可以選擇使用哪個(gè) Agent# main.py from agents.task_agent import build_task_agent, build_local_agent def main(use_localFalse): print(正在初始化智能體使用本地模型... if use_local else 正在初始化智能體使用OpenAI...) if use_local: agent build_local_agent() else: agent build_task_agent() # ... 其余交互代碼不變 ... if __name__ __main__: # 通過(guò)命令行參數(shù)或直接修改此處來(lái)選擇模式 use_local_model True # 設(shè)為 True 測(cè)試本地模型 main(use_localuse_local_model)運(yùn)行前確保 Ollama 服務(wù)正在運(yùn)行 (ollama serve)。然后運(yùn)行python main.py。首次調(diào)用時(shí)本地模型加載可能需要一些時(shí)間后續(xù)交互速度會(huì)快很多。注意本地模型的工具調(diào)用格式遵循能力可能不如 GPT-4 等專用優(yōu)化模型穩(wěn)定。如果遇到OutputParserException等解析錯(cuò)誤可以嘗試使用handle_parsing_errorsTrue我們已經(jīng)設(shè)置讓執(zhí)行器嘗試修復(fù)。換用其他工具調(diào)用格式支持更好的模型如llama3。使用更詳細(xì)的提示詞Prompt來(lái)指導(dǎo)模型輸出格式。6. 常見(jiàn)問(wèn)題排查與優(yōu)化實(shí)踐在實(shí)際開(kāi)發(fā)和運(yùn)行中你可能會(huì)遇到以下典型問(wèn)題。這里提供排查思路和優(yōu)化建議。6.1 Agent 常見(jiàn)問(wèn)題排查表問(wèn)題現(xiàn)象可能原因檢查步驟解決方案模型不調(diào)用工具直接回答1. 工具描述 (description) 不清晰。2. 提示詞 (prompt) 未強(qiáng)調(diào)工具使用。3. 模型能力不足本地模型常見(jiàn)。1. 檢查verbose日志看模型“思考”步驟。2. 查看工具描述是否準(zhǔn)確描述了功能和輸入。1. 優(yōu)化工具描述明確使用場(chǎng)景和輸入格式。2. 嘗試更換/微調(diào)提示詞模板。3. 換用工具調(diào)用能力更強(qiáng)的模型如 GPT-4 Llama 3.1。工具調(diào)用參數(shù)格式錯(cuò)誤1.args_schema定義與模型輸出不匹配。2. 模型未生成有效的 JSON。1. 查看verbose日志中Action Input的內(nèi)容。2. 檢查是否觸發(fā)了handle_parsing_errors。1. 確保args_schema的字段名和類型簡(jiǎn)單明確。2. 在提示詞中強(qiáng)調(diào)輸出必須是有效的 JSON 對(duì)象。3. 使用handle_parsing_errorsTrue進(jìn)行容錯(cuò)。Agent 陷入無(wú)限循環(huán)1. 工具返回結(jié)果未滿足模型預(yù)期導(dǎo)致其反復(fù)調(diào)用同一工具。2.max_iterations設(shè)置過(guò)高。1. 觀察循環(huán)調(diào)用的工具和參數(shù)。2. 檢查工具返回結(jié)果是否清晰、完整。1. 優(yōu)化工具返回信息使其更具決定性。2. 合理設(shè)置max_iterations如5-10。3. 設(shè)置early_stopping_methodgenerate。本地模型響應(yīng)慢或報(bào)錯(cuò)1. 硬件資源內(nèi)存、顯存不足。2. Ollama 服務(wù)未啟動(dòng)或端口被占用。3. 模型文件損壞。1. 檢查任務(wù)管理器/系統(tǒng)監(jiān)控。2. 運(yùn)行ollama list和curl http://localhost:11434/api/tags。3. 查看 Ollama 日志。1. 換用更小的模型如 3B, 7B。2. 確保ollama serve在運(yùn)行。3. 嘗試重新拉取模型ollama pull model。郵件/API等工具執(zhí)行失敗1. 網(wǎng)絡(luò)問(wèn)題。2. 認(rèn)證信息錯(cuò)誤API Key 密碼。3. 目標(biāo)服務(wù)限制如頻率限制。1. 在工具_(dá)run方法內(nèi)添加詳細(xì)日志或打印錯(cuò)誤。2. 單獨(dú)測(cè)試工具函數(shù)。3. 檢查防火墻或代理設(shè)置。1. 確保網(wǎng)絡(luò)連通性。2. 核對(duì)config.py中的配置信息。3. 為工具添加重試機(jī)制和更友好的錯(cuò)誤信息返回。6.2 生產(chǎn)環(huán)境最佳實(shí)踐當(dāng)你的 Agent 從 demo 走向真實(shí)業(yè)務(wù)時(shí)需要考慮以下幾點(diǎn)配置與密鑰管理絕對(duì)不要將 API Key、密碼等硬編碼在代碼或config.py中并提交到代碼倉(cāng)庫(kù)。使用環(huán)境變量通過(guò)os.getenv(“OPENAI_API_KEY”)讀取。使用.env文件結(jié)合python-dotenv庫(kù)管理本地開(kāi)發(fā)環(huán)境變量。生產(chǎn)環(huán)境使用云服務(wù)商提供的密鑰管理服務(wù)如 AWS Secrets Manager, Azure Key Vault。錯(cuò)誤處理與魯棒性工具層每個(gè) Skill 的_run方法都應(yīng)包含完整的異常捕獲返回明確的錯(cuò)誤信息字符串而不是拋出異常導(dǎo)致 Agent 崩潰。Agent 層利用AgentExecutor的handle_parsing_errors和max_iterations等參數(shù)防止失控。應(yīng)用層在main.py或你的 Web 服務(wù)層進(jìn)行全局異常捕獲和日志記錄。性能與成本緩存對(duì)頻繁查詢且結(jié)果變化不快的工具如天氣添加緩存層如functools.lru_cache或 Redis。異步如果 Skill 涉及大量 I/O網(wǎng)絡(luò)請(qǐng)求、數(shù)據(jù)庫(kù)查詢實(shí)現(xiàn)其_arun異步方法并使用AgentExecutor的異步接口ainvoke來(lái)提升并發(fā)性能。模型選擇根據(jù)任務(wù)復(fù)雜度平衡模型能力與成本/速度。簡(jiǎn)單任務(wù)用小型本地模型或 GPT-3.5復(fù)雜任務(wù)再用 GPT-4。技能Skills設(shè)計(jì)原則單一職責(zé)一個(gè) Skill 只做一件事并做好。描述清晰name和description是模型理解工具的窗口務(wù)必準(zhǔn)確、無(wú)歧義。輸入驗(yàn)證在_run方法開(kāi)始處對(duì)輸入?yún)?shù)進(jìn)行有效性校驗(yàn)。輸出規(guī)范返回結(jié)構(gòu)化的字符串信息便于模型解析和下一步?jīng)Q策。7. 擴(kuò)展方向與下一步學(xué)習(xí)建議掌握了基礎(chǔ) Agent 與 Skills 的構(gòu)建后你可以從以下幾個(gè)方向深化集成更多真實(shí)工具數(shù)據(jù)庫(kù)操作使用langchain_community.tools.SQLDatabaseToolkit讓 Agent 能查詢和操作數(shù)據(jù)庫(kù)。網(wǎng)絡(luò)搜索集成langchain_community.tools.DuckDuckGoSearchRun或 Tavily API讓 Agent 獲取實(shí)時(shí)信息。文件操作創(chuàng)建讀寫(xiě)本地文件、解析 PDF/Word 的技能。第三方 API連接你的業(yè)務(wù)系統(tǒng)如 CRM、ERP、工單系統(tǒng)等。實(shí)現(xiàn)復(fù)雜工作流多 Agent 協(xié)作使用AutoGen框架創(chuàng)建多個(gè)具有不同專長(zhǎng)規(guī)劃、執(zhí)行、審核的 Agent 協(xié)同完成復(fù)雜項(xiàng)目。記憶與上下文為 Agent 添加更強(qiáng)大的記憶系統(tǒng)如ConversationBufferWindowMemory保留最近N輪對(duì)話或VectorStoreRetrieverMemory將歷史存入向量數(shù)據(jù)庫(kù)進(jìn)行語(yǔ)義檢索。前端交互與部署Web 界面使用Gradio或Streamlit快速構(gòu)建一個(gè)與 Agent 對(duì)話的 Web 應(yīng)用。API 服務(wù)使用FastAPI將你的 Agent 封裝成 RESTful API供其他系統(tǒng)調(diào)用。容器化使用 Docker 將你的應(yīng)用及其依賴包括本地模型服務(wù)打包實(shí)現(xiàn)一鍵部署。深入原理與定制自定義提示詞研究并修改從 Hub 拉取的react提示詞模板使其更符合你的任務(wù)需求。自定義輸出解析器如果標(biāo)準(zhǔn)解析器無(wú)法處理你的模型輸出學(xué)習(xí)實(shí)現(xiàn)BaseOutputParser。Agent 類型探索除了 ReAct嘗試conversational-react-description帶聊天歷史、self-ask-with-search自問(wèn)自答搜索等其他 Agent 類型。構(gòu)建大模型 Agent 應(yīng)用是一個(gè)持續(xù)迭代的過(guò)程。從今天這個(gè)能查詢天氣和發(fā)郵件的簡(jiǎn)單智能體開(kāi)始通過(guò)不斷集成新的 Skills、優(yōu)化提示詞、改進(jìn)工作流你將能夠創(chuàng)造出真正理解需求、自動(dòng)執(zhí)行復(fù)雜任務(wù)的智能助手。 大模型Agent實(shí)戰(zhàn)：從零構(gòu)建具備天氣查詢與郵件發(fā)送技能的智能體
在實(shí)際的大模型應(yīng)用開(kāi)發(fā)中很多開(kāi)發(fā)者會(huì)遇到一個(gè)瓶頸模型本身能力很強(qiáng)但如何讓它真正“動(dòng)起來(lái)”完成一個(gè)連貫、多步驟的復(fù)雜任務(wù)比如讓大模型不僅能回答天氣還能根據(jù)天氣為你規(guī)劃出行、預(yù)訂會(huì)議室、并發(fā)送郵件通知。這背后依賴的核心技術(shù)就是Agent智能體而賦予 Agent 執(zhí)行具體任務(wù)能力的則是Skills技能。對(duì)于剛接觸大模型落地的開(kāi)發(fā)者和技術(shù)愛(ài)好者而言理解并實(shí)踐 Agent Skills 是打通“模型對(duì)話”到“實(shí)際應(yīng)用”的關(guān)鍵一步。本文將從工程實(shí)踐角度帶你一步步掌握如何為大模型 Agent 構(gòu)建和集成 Skills。我們將不局限于理論而是通過(guò)一個(gè)從零開(kāi)始的實(shí)戰(zhàn)案例涵蓋環(huán)境準(zhǔn)備、技能定義、Agent 調(diào)度、本地部署與測(cè)試的完整閉環(huán)。你會(huì)學(xué)到如何將一個(gè)簡(jiǎn)單的“查詢天氣”和“發(fā)送郵件”的想法轉(zhuǎn)化為一個(gè)能自主決策、按需調(diào)用工具的可運(yùn)行智能體。無(wú)論你是希望將 AI 能力集成到現(xiàn)有業(yè)務(wù)系統(tǒng)的程序員還是對(duì) AI 應(yīng)用開(kāi)發(fā)充滿好奇的學(xué)習(xí)者這篇指南都將提供一條清晰的、可復(fù)現(xiàn)的路徑。1. 理解 Agent 與 Skills從“聊天”到“做事”的跨越在深入代碼之前必須厘清幾個(gè)核心概念。這能幫助你在后續(xù)開(kāi)發(fā)中做出正確的設(shè)計(jì)決策避免將 Agent 簡(jiǎn)單理解為“帶工具的聊天機(jī)器人”。1.1 什么是 Agent智能體在大模型語(yǔ)境下Agent 是一個(gè)能夠感知環(huán)境、進(jìn)行決策并執(zhí)行行動(dòng)以實(shí)現(xiàn)目標(biāo)的系統(tǒng)。你可以把它想象成一個(gè)擁有“大腦”大模型和“手腳”工具的虛擬助手。核心組件一個(gè)典型的 Agent 包含三個(gè)部分規(guī)劃Planning大腦大模型負(fù)責(zé)理解用戶目標(biāo)并將其分解為一系列可執(zhí)行的子任務(wù)或步驟。記憶Memory存儲(chǔ)對(duì)話歷史、工具調(diào)用結(jié)果和知識(shí)為后續(xù)決策提供上下文。工具使用Tool Use根據(jù)規(guī)劃調(diào)用外部的 Skills/Tools 來(lái)執(zhí)行具體操作如查詢數(shù)據(jù)庫(kù)、調(diào)用 API、操作文件等。與普通聊天的區(qū)別普通的大模型對(duì)話是“一問(wèn)一答”答案基于其訓(xùn)練數(shù)據(jù)。而 Agent 是“目標(biāo)導(dǎo)向”的它會(huì)主動(dòng)思考“為了完成用戶請(qǐng)求我需要先做什么再做什么”并調(diào)用外部能力來(lái)補(bǔ)足模型自身無(wú)法直接完成的事情如獲取實(shí)時(shí)數(shù)據(jù)、操作外部系統(tǒng)。1.2 什么是 Skills/Tools技能/工具Skills 或 Tools 是 Agent 可以調(diào)用的具體功能單元。它們是 Agent 的“手腳”將模型的“思考”轉(zhuǎn)化為對(duì)現(xiàn)實(shí)世界的“影響”。本質(zhì)一個(gè) Skill 通常對(duì)應(yīng)一個(gè)函數(shù)Function、一個(gè) API 接口或一個(gè)命令行工具。它有著明確的輸入?yún)?shù)、執(zhí)行邏輯和輸出結(jié)果。與大模型的關(guān)系大模型本身不執(zhí)行Skill。它的角色是1理解用戶需求后判斷是否需要調(diào)用 Skill2如果需要?jiǎng)t生成符合該 Skill 定義的調(diào)用參數(shù)JSON 格式3解析 Skill 執(zhí)行后的結(jié)果并組織成自然語(yǔ)言回復(fù)給用戶。常見(jiàn)類型信息獲取類如get_weather獲取天氣、search_web網(wǎng)絡(luò)搜索、query_database查詢數(shù)據(jù)庫(kù)。操作執(zhí)行類如send_email發(fā)送郵件、create_calendar_event創(chuàng)建日歷事件、execute_shell_command執(zhí)行Shell命令需謹(jǐn)慎。計(jì)算與處理類如calculate計(jì)算器、format_json格式化JSON。1.3 Agent 如何與 Skills 協(xié)同工作其工作流是一個(gè)典型的“思考-行動(dòng)-觀察”循環(huán)ReAct 模式用戶輸入“明天上海天氣如何如果下雨提醒我?guī)?。”Agent 規(guī)劃模型思考后認(rèn)為需要兩步a) 獲取上海明天天氣b) 根據(jù)天氣結(jié)果決定是否發(fā)送提醒。調(diào)用 Skill 1Agent 調(diào)用get_weatherSkill傳入?yún)?shù){“l(fā)ocation”: “上海” “date”: “tomorrow”}。觀察結(jié)果Skill 返回{“weather”: “rain” “temperature”: “18-22°C”}。Agent 再規(guī)劃模型觀察到“rain”判斷需要執(zhí)行提醒。調(diào)用 Skill 2Agent 調(diào)用send_reminderSkill傳入?yún)?shù){“message”: “明天上海有雨請(qǐng)帶傘?！眪。最終回復(fù)Agent 綜合所有結(jié)果向用戶回復(fù)“明天上海有雨氣溫18-22°C。我已經(jīng)為您設(shè)置了帶傘的提醒?！边@個(gè)流程的關(guān)鍵在于大模型負(fù)責(zé)高層的任務(wù)分解和決策而 Skills 負(fù)責(zé)底層的、確定性的執(zhí)行。接下來(lái)我們將通過(guò)實(shí)戰(zhàn)親手構(gòu)建這樣一個(gè)流程。2. 環(huán)境準(zhǔn)備與框架選型在開(kāi)始編碼前我們需要搭建開(kāi)發(fā)環(huán)境并選擇一個(gè)合適的 Agent 開(kāi)發(fā)框架?？蚣苣軒臀覀兲幚砼c大模型的對(duì)話、Skill 的注冊(cè)與管理、調(diào)用流程控制等通用邏輯讓我們專注于業(yè)務(wù)技能的實(shí)現(xiàn)。2.1 主流 Agent 開(kāi)發(fā)框架簡(jiǎn)介目前社區(qū)有多種框架各有側(cè)重。對(duì)于新手和大多數(shù)應(yīng)用場(chǎng)景我們推薦從LangChain或Semantic Kernel開(kāi)始?？蚣苤饕Z(yǔ)言特點(diǎn)適用場(chǎng)景LangChainPython / JS生態(tài)豐富社區(qū)活躍文檔齊全概念體系完整?？焖僭万?yàn)證研究探索復(fù)雜的鏈?zhǔn)秸{(diào)用。Semantic KernelPython / C# / Java微軟出品與.NET生態(tài)集成好強(qiáng)調(diào)“插件”模式。企業(yè)級(jí)應(yīng)用尤其是已有 .NET 技術(shù)棧的項(xiàng)目。LlamaIndexPython專注于數(shù)據(jù)索引與檢索構(gòu)建RAG應(yīng)用能力強(qiáng)。需要與私有知識(shí)庫(kù)深度結(jié)合的Agent。AutoGenPython支持多Agent協(xié)作對(duì)話場(chǎng)景模擬能力強(qiáng)。需要多個(gè)Agent分工協(xié)作的復(fù)雜任務(wù)。本文選擇LangChain (Python版)進(jìn)行演示因?yàn)樗鼘W(xué)習(xí)曲線相對(duì)平緩且網(wǎng)上資源最多遇到問(wèn)題容易找到解決方案。2.2 基礎(chǔ)環(huán)境搭建請(qǐng)確保你的系統(tǒng)已安裝 Python (推薦 3.8-3.11版本)。我們將使用venv創(chuàng)建獨(dú)立的虛擬環(huán)境。# 1. 創(chuàng)建項(xiàng)目目錄并進(jìn)入 mkdir agent-skills-demo cd agent-skills-demo # 2. 創(chuàng)建虛擬環(huán)境 (Windows 用戶使用 python -m venv venv) python3 -m venv venv # 3. 激活虛擬環(huán)境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 4. 升級(jí)pip pip install --upgrade pip2.3 安裝核心依賴我們將安裝 LangChain 及其與 OpenAI 模型交互的包。如果你使用其他模型如通義千問(wèn)、文心一言等需安裝對(duì)應(yīng)的 LangChain 集成包。# 安裝 LangChain 核心包和 OpenAI 集成包 pip install langchain langchain-openai # 安裝用于定義Tools/Skills的社區(qū)包包含一些常用工具 pip install langchain-community # 安裝用于解析模型輸出的包重要用于將模型回復(fù)解析為工具調(diào)用 pip install langchain-core注意本文示例將使用 OpenAI 的 GPT 模型作為 Agent 的“大腦”。你需要準(zhǔn)備一個(gè)有效的 OpenAI API Key。如果你希望完全本地運(yùn)行后續(xù)章節(jié)會(huì)介紹使用 Ollama 部署本地模型作為替代方案。2.4 項(xiàng)目結(jié)構(gòu)初始化一個(gè)清晰的項(xiàng)目結(jié)構(gòu)有助于管理 Skills 和 Agent 配置。agent-skills-demo/ ├── venv/ # Python虛擬環(huán)境.gitignore忽略 ├── skills/ # 存放自定義技能模塊 │ ├── __init__.py │ ├── weather_tool.py # 天氣查詢技能 │ └── email_tool.py # 郵件發(fā)送技能 ├── agents/ # 存放Agent定義 │ ├── __init__.py │ └── task_agent.py # 任務(wù)執(zhí)行Agent ├── config.py # 配置文件如API密鑰 ├── requirements.txt # 項(xiàng)目依賴 └── main.py # 主程序入口創(chuàng)建上述目錄和文件除venv外mkdir skills agents touch skills/__init__.py skills/weather_tool.py skills/email_tool.py touch agents/__init__.py agents/task_agent.py touch config.py requirements.txt main.py將當(dāng)前安裝的依賴導(dǎo)出到requirements.txtpip freeze requirements.txt至此基礎(chǔ)環(huán)境準(zhǔn)備完畢。接下來(lái)我們將動(dòng)手實(shí)現(xiàn)第一個(gè) Skill。3. 實(shí)戰(zhàn)構(gòu)建你的第一個(gè)自定義 Skill我們將構(gòu)建一個(gè)模擬的get_weather技能。在生產(chǎn)環(huán)境中這個(gè)技能應(yīng)該調(diào)用真實(shí)的天氣 API如和風(fēng)天氣、OpenWeatherMap。為了簡(jiǎn)化演示我們模擬其邏輯。3.1 定義 Weather Skill編輯skills/weather_tool.py文件from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type class WeatherToolInput(BaseModel): 天氣查詢工具的輸入?yún)?shù)模式。 location: str Field(description需要查詢天氣的城市名稱例如北京、上海) date: Optional[str] Field(defaulttoday, description查詢?nèi)掌诶鐃oday, tomorrow, 2024-05-20。默認(rèn)為今天。) class WeatherTool(BaseTool): 一個(gè)模擬的天氣查詢工具。在實(shí)際應(yīng)用中應(yīng)替換為真實(shí)的天氣API調(diào)用。 name: str get_weather description: str ( 根據(jù)城市和日期查詢天氣信息。 輸入應(yīng)包含‘location’城市名和可選的‘date’日期。 ) args_schema: Type[BaseModel] WeatherToolInput def _run(self, location: str, date: str today) - str: 執(zhí)行工具的主邏輯。 # 模擬API調(diào)用和數(shù)據(jù)處理 # 真實(shí)場(chǎng)景下這里會(huì)是 requests.get(weather_api_url, params{...}) weather_data { 北京: {today: 晴15-25°C, tomorrow: 多云18-28°C}, 上海: {today: 小雨18-22°C, tomorrow: 陰19-24°C}, 深圳: {today: 雷陣雨25-30°C, tomorrow: 多云26-31°C}, } city_weather weather_data.get(location) if not city_weather: return f抱歉未找到城市 {location} 的天氣信息。 forecast city_weather.get(date, city_weather.get(today, 暫無(wú)數(shù)據(jù))) return f{location} {date} 的天氣是{forecast} async def _arun(self, location: str, date: str today) - str: 異步執(zhí)行版本。如果不需要異步可以直接調(diào)用同步方法。 return self._run(location, date)關(guān)鍵點(diǎn)解析繼承BaseTool所有 LangChain 工具都需要繼承此類。name和description至關(guān)重要大模型根據(jù)description來(lái)判斷何時(shí)調(diào)用此工具。描述應(yīng)清晰準(zhǔn)確。args_schema使用 Pydantic 模型定義輸入?yún)?shù)的結(jié)構(gòu)和類型。這能幫助大模型生成格式正確的調(diào)用參數(shù)。_run方法工具的核心執(zhí)行邏輯。這里我們用一個(gè)字典模擬了數(shù)據(jù)返回。_arun方法異步版本。如果工具涉及網(wǎng)絡(luò)I/O實(shí)現(xiàn)異步版本能提升效率。3.2 定義 Email Skill同樣我們模擬一個(gè)發(fā)送郵件的工具。編輯skills/email_tool.pyfrom langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Type import smtplib from email.mime.text import MIMEText from email.header import Header import config # 我們將配置放在config.py中 class EmailToolInput(BaseModel): 郵件發(fā)送工具的輸入?yún)?shù)模式。 recipient: str Field(description收件人郵箱地址) subject: str Field(description郵件主題) body: str Field(description郵件正文內(nèi)容) class EmailTool(BaseTool): 郵件發(fā)送工具。需要預(yù)先配置SMTP服務(wù)器信息。 name: str send_email description: str ( 發(fā)送一封電子郵件到指定的收件人。 輸入需要收件人地址recipient、主題subject和正文body。 ) args_schema: Type[BaseModel] EmailToolInput def _run(self, recipient: str, subject: str, body: str) - str: 執(zhí)行發(fā)送郵件的邏輯。 # 注意這是一個(gè)示例生產(chǎn)環(huán)境需要更安全的密碼管理如環(huán)境變量、密鑰管理服務(wù)。 # 這里從config模塊讀取配置 smtp_server config.SMTP_SERVER smtp_port config.SMTP_PORT sender_email config.SENDER_EMAIL sender_password config.SENDER_PASSWORD # 可能是授權(quán)碼而非登錄密碼 # 構(gòu)建郵件 message MIMEText(body, plain, utf-8) message[From] Header(sender_email) message[To] Header(recipient) message[Subject] Header(subject) try: # 連接服務(wù)器并發(fā)送 with smtplib.SMTP_SSL(smtp_server, smtp_port) as server: # 使用SSL server.login(sender_email, sender_password) server.sendmail(sender_email, [recipient], message.as_string()) return f郵件已成功發(fā)送至 {recipient} except Exception as e: return f郵件發(fā)送失敗錯(cuò)誤信息{str(e)} async def _arun(self, recipient: str, subject: str, body: str) - str: return self._run(recipient, subject, body)關(guān)鍵點(diǎn)解析依賴外部服務(wù)此工具依賴 SMTP 服務(wù)器。我們將其配置外置到config.py。錯(cuò)誤處理在_run方法中使用了 try-except 塊確保將任何異常轉(zhuǎn)化為字符串結(jié)果返回給 Agent避免整個(gè)流程因一個(gè)工具錯(cuò)誤而崩潰。安全警告代碼中直接引用了密碼這僅用于演示。在生產(chǎn)環(huán)境中務(wù)必使用環(huán)境變量或?qū)I(yè)的密鑰管理服務(wù)來(lái)存儲(chǔ)敏感信息。3.3 創(chuàng)建配置文件編輯config.py存放敏感信息和配置# config.py # 安全提示切勿將此文件提交至版本控制系統(tǒng)如Git。請(qǐng)將其加入 .gitignore。 # 實(shí)際項(xiàng)目中應(yīng)使用環(huán)境變量。 # OpenAI API 配置 OPENAI_API_KEY sk-your-openai-api-key-here # 替換為你的真實(shí)Key OPENAI_BASE_URL https://api.openai.com/v1 # 如果你使用代理或特定端點(diǎn)可修改此項(xiàng) # 郵件SMTP服務(wù)器配置 (以QQ郵箱為例需要開(kāi)啟SMTP服務(wù)并獲取授權(quán)碼) SMTP_SERVER smtp.qq.com SMTP_PORT 465 # QQ郵箱SSL端口 SENDER_EMAIL your-emailqq.com SENDER_PASSWORD your-authorization-code # 注意是授權(quán)碼不是郵箱密碼 # 其他模型配置如后續(xù)使用本地模型 LOCAL_MODEL_PATH 記得創(chuàng)建.gitignore文件忽略配置和虛擬環(huán)境venv/ __pycache__/ *.pyc config.py現(xiàn)在我們已經(jīng)有了兩個(gè)可用的 Skills。下一步是創(chuàng)建 Agent并將這些 Skills 裝配給它。4. 創(chuàng)建并運(yùn)行你的第一個(gè) Agent有了 Skills我們需要一個(gè)“大腦”來(lái)調(diào)度它們。我們將使用 LangChain 的create_react_agent來(lái)構(gòu)建一個(gè)遵循 ReAct 推理模式的 Agent。4.1 構(gòu)建 Task Agent編輯agents/task_agent.pyfrom langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from skills.weather_tool import WeatherTool from skills.email_tool import EmailTool import config def build_task_agent(): 構(gòu)建并返回一個(gè)配備了天氣和郵件工具的Agent執(zhí)行器。 # 1. 初始化大語(yǔ)言模型LLM作為Agent的大腦 # 這里使用 GPT-3.5-turbo對(duì)于工具調(diào)用任務(wù)足夠且成本較低。 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 溫度設(shè)為0使輸出更確定更適合工具調(diào)用 openai_api_keyconfig.OPENAI_API_KEY, base_urlconfig.OPENAI_BASE_URL, ) # 2. 準(zhǔn)備工具列表 tools [WeatherTool(), EmailTool()] # 3. 從LangChain Hub獲取一個(gè)預(yù)設(shè)的ReAct提示詞模板 # 這個(gè)模板會(huì)指導(dǎo)LLM按照“Thought/Action/Action Input/Observation”的格式進(jìn)行推理。 prompt hub.pull(hwchase17/react) # 4. 使用工具、LLM和提示詞創(chuàng)建ReAct Agent agent create_react_agent(llm, tools, prompt) # 5. 創(chuàng)建Agent執(zhí)行器它負(fù)責(zé)運(yùn)行Agent的循環(huán)直到返回最終答案。 # handle_parsing_errorsTrue 很重要當(dāng)模型輸出格式不符合工具調(diào)用格式時(shí)嘗試修復(fù)。 # verboseTrue 會(huì)在控制臺(tái)打印詳細(xì)的推理步驟便于調(diào)試。 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations5, # 限制最大循環(huán)次數(shù)防止無(wú)限循環(huán) early_stopping_methodgenerate, # 當(dāng)模型認(rèn)為不需要再調(diào)用工具時(shí)直接生成最終回復(fù) ) return agent_executor if __name__ __main__: # 本地測(cè)試這個(gè)Agent agent_executor build_task_agent() test_query 明天上海的天氣怎么樣如果下雨發(fā)郵件到 testexample.com 提醒我?guī)恪?print(f用戶提問(wèn): {test_query}) result agent_executor.invoke({input: test_query}) print(f\nAgent最終回復(fù): {result[output]})4.2 編寫(xiě)主程序并運(yùn)行測(cè)試編輯main.py作為應(yīng)用的啟動(dòng)入口# main.py from agents.task_agent import build_task_agent def main(): print(初始化任務(wù)智能體...) agent build_task_agent() print(\n智能體就緒請(qǐng)輸入您的問(wèn)題輸入 quit 或 exit 退出:) while True: try: user_input input(\n ) if user_input.lower() in [quit, exit]: print(再見(jiàn)) break if not user_input.strip(): continue # 調(diào)用Agent執(zhí)行器 result agent.invoke({input: user_input}) print(f\n {result[output]}) except KeyboardInterrupt: print(\n程序被中斷。) break except Exception as e: print(f\n處理請(qǐng)求時(shí)發(fā)生錯(cuò)誤: {e}) if __name__ __main__: main()4.3 首次運(yùn)行與驗(yàn)證在運(yùn)行前請(qǐng)確保config.py中的OPENAI_API_KEY已填寫(xiě)正確。激活虛擬環(huán)境如果已退出source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows運(yùn)行主程序python main.py觀察輸出 程序會(huì)加載模型和工具。當(dāng)你輸入測(cè)試問(wèn)題后由于verboseTrue控制臺(tái)會(huì)打印出類似以下的詳細(xì)推理過(guò)程Thought/Action/Action Input/Observation初始化任務(wù)智能體... 智能體就緒請(qǐng)輸入您的問(wèn)題輸入 quit 或 exit 退出: 明天上海的天氣怎么樣如果下雨發(fā)郵件到 testexample.com 提醒我?guī)恪? 進(jìn)入新的AgentExecutor鏈... 我需要先查詢明天上海的天氣然后根據(jù)天氣情況決定是否發(fā)送郵件。 行動(dòng)get_weather 行動(dòng)輸入{location: 上海, date: tomorrow} 觀察上海 tomorrow 的天氣是陰19-24°C 思考天氣是陰天沒(méi)有下雨所以不需要發(fā)送提醒郵件。我可以直接回復(fù)用戶。 最終答案明天上海是陰天氣溫在19到24攝氏度之間。根據(jù)預(yù)報(bào)沒(méi)有雨所以不需要提醒帶傘。 鏈結(jié)束。 明天上海是陰天氣溫在19到24攝氏度之間。根據(jù)預(yù)報(bào)沒(méi)有雨所以不需要提醒帶傘。這個(gè)輸出清晰地展示了 Agent 的思考過(guò)程它先決定調(diào)用天氣工具根據(jù)返回結(jié)果陰天判斷無(wú)需調(diào)用郵件工具最終生成回復(fù)。恭喜你已經(jīng)成功創(chuàng)建了一個(gè)具備多步推理和工具調(diào)用能力的智能體。接下來(lái)我們要解決一個(gè)關(guān)鍵問(wèn)題如何在不依賴 OpenAI 的情況下在本地運(yùn)行這個(gè) Agent5. 進(jìn)階使用 Ollama 本地部署與集成依賴云端 API 存在成本、延遲和隱私問(wèn)題。對(duì)于開(kāi)發(fā)測(cè)試或內(nèi)部應(yīng)用在本地部署開(kāi)源大模型是更優(yōu)選擇。Ollama是一個(gè)強(qiáng)大的工具可以讓你在本地輕松運(yùn)行如 Llama 3、Mistral、Qwen 等主流開(kāi)源模型。5.1 安裝與運(yùn)行 Ollama訪問(wèn) Ollama 官網(wǎng)根據(jù)你的操作系統(tǒng)macOS, Linux, Windows下載并安裝。安裝完成后打開(kāi)終端拉取一個(gè)模型。我們選擇輕量且性能不錯(cuò)的qwen2.5:7b通義千問(wèn)2.5 7B版本ollama pull qwen2.5:7b這會(huì)下載約 4-5GB 的模型文件。運(yùn)行模型服務(wù)ollama run qwen2.5:7b這會(huì)啟動(dòng)一個(gè)交互式對(duì)話。但我們需要的是 API 服務(wù)。讓 Ollama 在后臺(tái)以 API 模式運(yùn)行# 停止剛才的交互式會(huì)話 (CtrlC) # 啟動(dòng)API服務(wù)默認(rèn)監(jiān)聽(tīng) 11434 端口 ollama serve # 或者直接運(yùn)行 ollama serve 并在新終端窗口進(jìn)行后續(xù)操作5.2 修改 Agent 以使用本地模型我們需要修改agents/task_agent.py中的 LLM 初始化部分使其指向本地的 Ollama 服務(wù)。首先安裝 LangChain 與 Ollama 集成的包如果尚未安裝pip install langchain-ollama然后修改build_task_agent函數(shù)或創(chuàng)建一個(gè)新的函數(shù)如build_local_agent# 在 agents/task_agent.py 頂部導(dǎo)入 from langchain_ollama import ChatOllama def build_local_agent(): 構(gòu)建使用本地Ollama模型的Agent。 # 1. 初始化本地LLM llm ChatOllama( modelqwen2.5:7b, # 與 ollama pull 的模型名一致 base_urlhttp://localhost:11434, # Ollama 默認(rèn)API地址 temperature0, # 對(duì)于工具調(diào)用可能需要調(diào)整一些參數(shù)以提升格式遵循能力 # num_ctx4096, # 可調(diào)整上下文長(zhǎng)度 ) # 2. 準(zhǔn)備工具列表 (與之前相同) tools [WeatherTool(), EmailTool()] # 3. 獲取提示詞模板 prompt hub.pull(hwchase17/react) # 4. 5. 創(chuàng)建Agent和執(zhí)行器 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations5, early_stopping_methodgenerate, ) return agent_executor關(guān)鍵點(diǎn)解析ChatOllama這是 LangChain 為 Ollama 提供的專用聊天模型類。base_url指向本地運(yùn)行的 Ollama API 服務(wù)器。模型能力并非所有開(kāi)源模型都擅長(zhǎng)嚴(yán)格的工具調(diào)用格式JSON。qwen2.5、llama3、mistral等較新的模型對(duì)此支持較好。如果遇到格式解析錯(cuò)誤可能需要嘗試不同模型或微調(diào)提示詞。5.3 測(cè)試本地 Agent修改main.py可以選擇使用哪個(gè) Agent# main.py from agents.task_agent import build_task_agent, build_local_agent def main(use_localFalse): print(正在初始化智能體使用本地模型... if use_local else 正在初始化智能體使用OpenAI...) if use_local: agent build_local_agent() else: agent build_task_agent() # ... 其余交互代碼不變 ... if __name__ __main__: # 通過(guò)命令行參數(shù)或直接修改此處來(lái)選擇模式 use_local_model True # 設(shè)為 True 測(cè)試本地模型 main(use_localuse_local_model)運(yùn)行前確保 Ollama 服務(wù)正在運(yùn)行 (ollama serve)。然后運(yùn)行python main.py。首次調(diào)用時(shí)本地模型加載可能需要一些時(shí)間后續(xù)交互速度會(huì)快很多。注意本地模型的工具調(diào)用格式遵循能力可能不如 GPT-4 等專用優(yōu)化模型穩(wěn)定。如果遇到OutputParserException等解析錯(cuò)誤可以嘗試使用handle_parsing_errorsTrue我們已經(jīng)設(shè)置讓執(zhí)行器嘗試修復(fù)。換用其他工具調(diào)用格式支持更好的模型如llama3。使用更詳細(xì)的提示詞Prompt來(lái)指導(dǎo)模型輸出格式。6. 常見(jiàn)問(wèn)題排查與優(yōu)化實(shí)踐在實(shí)際開(kāi)發(fā)和運(yùn)行中你可能會(huì)遇到以下典型問(wèn)題。這里提供排查思路和優(yōu)化建議。6.1 Agent 常見(jiàn)問(wèn)題排查表問(wèn)題現(xiàn)象可能原因檢查步驟解決方案模型不調(diào)用工具直接回答1. 工具描述 (description) 不清晰。2. 提示詞 (prompt) 未強(qiáng)調(diào)工具使用。3. 模型能力不足本地模型常見(jiàn)。1. 檢查verbose日志看模型“思考”步驟。2. 查看工具描述是否準(zhǔn)確描述了功能和輸入。1. 優(yōu)化工具描述明確使用場(chǎng)景和輸入格式。2. 嘗試更換/微調(diào)提示詞模板。3. 換用工具調(diào)用能力更強(qiáng)的模型如 GPT-4 Llama 3.1。工具調(diào)用參數(shù)格式錯(cuò)誤1.args_schema定義與模型輸出不匹配。2. 模型未生成有效的 JSON。1. 查看verbose日志中Action Input的內(nèi)容。2. 檢查是否觸發(fā)了handle_parsing_errors。1. 確保args_schema的字段名和類型簡(jiǎn)單明確。2. 在提示詞中強(qiáng)調(diào)輸出必須是有效的 JSON 對(duì)象。3. 使用handle_parsing_errorsTrue進(jìn)行容錯(cuò)。Agent 陷入無(wú)限循環(huán)1. 工具返回結(jié)果未滿足模型預(yù)期導(dǎo)致其反復(fù)調(diào)用同一工具。2.max_iterations設(shè)置過(guò)高。1. 觀察循環(huán)調(diào)用的工具和參數(shù)。2. 檢查工具返回結(jié)果是否清晰、完整。1. 優(yōu)化工具返回信息使其更具決定性。2. 合理設(shè)置max_iterations如5-10。3. 設(shè)置early_stopping_methodgenerate。本地模型響應(yīng)慢或報(bào)錯(cuò)1. 硬件資源內(nèi)存、顯存不足。2. Ollama 服務(wù)未啟動(dòng)或端口被占用。3. 模型文件損壞。1. 檢查任務(wù)管理器/系統(tǒng)監(jiān)控。2. 運(yùn)行ollama list和curl http://localhost:11434/api/tags。3. 查看 Ollama 日志。1. 換用更小的模型如 3B, 7B。2. 確保ollama serve在運(yùn)行。3. 嘗試重新拉取模型ollama pull model。郵件/API等工具執(zhí)行失敗1. 網(wǎng)絡(luò)問(wèn)題。2. 認(rèn)證信息錯(cuò)誤API Key 密碼。3. 目標(biāo)服務(wù)限制如頻率限制。1. 在工具_(dá)run方法內(nèi)添加詳細(xì)日志或打印錯(cuò)誤。2. 單獨(dú)測(cè)試工具函數(shù)。3. 檢查防火墻或代理設(shè)置。1. 確保網(wǎng)絡(luò)連通性。2. 核對(duì)config.py中的配置信息。3. 為工具添加重試機(jī)制和更友好的錯(cuò)誤信息返回。6.2 生產(chǎn)環(huán)境最佳實(shí)踐當(dāng)你的 Agent 從 demo 走向真實(shí)業(yè)務(wù)時(shí)需要考慮以下幾點(diǎn)配置與密鑰管理絕對(duì)不要將 API Key、密碼等硬編碼在代碼或config.py中并提交到代碼倉(cāng)庫(kù)。使用環(huán)境變量通過(guò)os.getenv(“OPENAI_API_KEY”)讀取。使用.env文件結(jié)合python-dotenv庫(kù)管理本地開(kāi)發(fā)環(huán)境變量。生產(chǎn)環(huán)境使用云服務(wù)商提供的密鑰管理服務(wù)如 AWS Secrets Manager, Azure Key Vault。錯(cuò)誤處理與魯棒性工具層每個(gè) Skill 的_run方法都應(yīng)包含完整的異常捕獲返回明確的錯(cuò)誤信息字符串而不是拋出異常導(dǎo)致 Agent 崩潰。Agent 層利用AgentExecutor的handle_parsing_errors和max_iterations等參數(shù)防止失控。應(yīng)用層在main.py或你的 Web 服務(wù)層進(jìn)行全局異常捕獲和日志記錄。性能與成本緩存對(duì)頻繁查詢且結(jié)果變化不快的工具如天氣添加緩存層如functools.lru_cache或 Redis。異步如果 Skill 涉及大量 I/O網(wǎng)絡(luò)請(qǐng)求、數(shù)據(jù)庫(kù)查詢實(shí)現(xiàn)其_arun異步方法并使用AgentExecutor的異步接口ainvoke來(lái)提升并發(fā)性能。模型選擇根據(jù)任務(wù)復(fù)雜度平衡模型能力與成本/速度。簡(jiǎn)單任務(wù)用小型本地模型或 GPT-3.5復(fù)雜任務(wù)再用 GPT-4。技能Skills設(shè)計(jì)原則單一職責(zé)一個(gè) Skill 只做一件事并做好。描述清晰name和description是模型理解工具的窗口務(wù)必準(zhǔn)確、無(wú)歧義。輸入驗(yàn)證在_run方法開(kāi)始處對(duì)輸入?yún)?shù)進(jìn)行有效性校驗(yàn)。輸出規(guī)范返回結(jié)構(gòu)化的字符串信息便于模型解析和下一步?jīng)Q策。7. 擴(kuò)展方向與下一步學(xué)習(xí)建議掌握了基礎(chǔ) Agent 與 Skills 的構(gòu)建后你可以從以下幾個(gè)方向深化集成更多真實(shí)工具數(shù)據(jù)庫(kù)操作使用langchain_community.tools.SQLDatabaseToolkit讓 Agent 能查詢和操作數(shù)據(jù)庫(kù)。網(wǎng)絡(luò)搜索集成langchain_community.tools.DuckDuckGoSearchRun或 Tavily API讓 Agent 獲取實(shí)時(shí)信息。文件操作創(chuàng)建讀寫(xiě)本地文件、解析 PDF/Word 的技能。第三方 API連接你的業(yè)務(wù)系統(tǒng)如 CRM、ERP、工單系統(tǒng)等。實(shí)現(xiàn)復(fù)雜工作流多 Agent 協(xié)作使用AutoGen框架創(chuàng)建多個(gè)具有不同專長(zhǎng)規(guī)劃、執(zhí)行、審核的 Agent 協(xié)同完成復(fù)雜項(xiàng)目。記憶與上下文為 Agent 添加更強(qiáng)大的記憶系統(tǒng)如ConversationBufferWindowMemory保留最近N輪對(duì)話或VectorStoreRetrieverMemory將歷史存入向量數(shù)據(jù)庫(kù)進(jìn)行語(yǔ)義檢索。前端交互與部署Web 界面使用Gradio或Streamlit快速構(gòu)建一個(gè)與 Agent 對(duì)話的 Web 應(yīng)用。API 服務(wù)使用FastAPI將你的 Agent 封裝成 RESTful API供其他系統(tǒng)調(diào)用。容器化使用 Docker 將你的應(yīng)用及其依賴包括本地模型服務(wù)打包實(shí)現(xiàn)一鍵部署。深入原理與定制自定義提示詞研究并修改從 Hub 拉取的react提示詞模板使其更符合你的任務(wù)需求。自定義輸出解析器如果標(biāo)準(zhǔn)解析器無(wú)法處理你的模型輸出學(xué)習(xí)實(shí)現(xiàn)BaseOutputParser。Agent 類型探索除了 ReAct嘗試conversational-react-description帶聊天歷史、self-ask-with-search自問(wèn)自答搜索等其他 Agent 類型。構(gòu)建大模型 Agent 應(yīng)用是一個(gè)持續(xù)迭代的過(guò)程。從今天這個(gè)能查詢天氣和發(fā)郵件的簡(jiǎn)單智能體開(kāi)始通過(guò)不斷集成新的 Skills、優(yōu)化提示詞、改進(jìn)工作流你將能夠創(chuàng)造出真正理解需求、自動(dòng)執(zhí)行復(fù)雜任務(wù)的智能助手。