我最近在打磨一個(gè)開(kāi)源項(xiàng)目名字叫Agent-Reach。說(shuō)實(shí)話(huà)這個(gè)名字起得有點(diǎn)土但它解決的痛點(diǎn)非常直接現(xiàn)在的 AI Agent 大多只是“嘴上說(shuō)得好聽(tīng)”真正讓它去查個(gè)天氣、寫(xiě)條記錄、操作一下數(shù)據(jù)庫(kù)它就露餡了。Agent-Reach 要做的就是給大模型智能體補(bǔ)上那根“能觸達(dá)到外部世界的手”——把模型說(shuō)出來(lái)的意圖翻譯成真實(shí)可執(zhí)行的 API 調(diào)用、數(shù)據(jù)庫(kù)操作和文件讀寫(xiě)。這個(gè)項(xiàng)目適合正在做 AI 應(yīng)用落地、搞過(guò)大模型 Function Calling 但覺(jué)得不夠順手、或者想把手頭自動(dòng)化腳本升級(jí)成“會(huì)說(shuō)人話(huà)的智能體”的開(kāi)發(fā)者。我會(huì)從架構(gòu)設(shè)計(jì)、核心機(jī)制、實(shí)操代碼、踩坑記錄四個(gè)維度把這套東西拆開(kāi)揉碎講清楚。不管你用的是 OpenAI 兼容協(xié)議還是國(guó)產(chǎn)大模型只要支持工具調(diào)用Agent-Reach 的思路都能直接套用。1. 先說(shuō)清楚Agent-Reach 到底解決什么問(wèn)題1.1 一個(gè)讓我失眠的對(duì)話(huà)上個(gè)月有個(gè)朋友問(wèn)我“我讓 GPT 幫我訂個(gè)會(huì)議室它能回我一串字但會(huì)議室到底訂沒(méi)訂上”這就是當(dāng)前大模型應(yīng)用最尷尬的地方。模型很聰明能理解“幫我訂明天下午三點(diǎn)的會(huì)議室”也能生成一串看起來(lái)像模像樣的答復(fù)但在它和你之間缺了一座橋。沒(méi)人把它的意圖拿去調(diào)會(huì)議系統(tǒng) API沒(méi)人校驗(yàn)?zāi)莻€(gè)時(shí)間段是否空閑也沒(méi)人把最終結(jié)果寫(xiě)回日歷。模型就像一個(gè)只會(huì)紙上談兵的參謀——戰(zhàn)略清晰落地為零。我當(dāng)時(shí)意識(shí)到問(wèn)題不在模型本身而在工程架構(gòu)。我們?nèi)钡牟皇歉斆鞯哪Ｐ投且粋€(gè)穩(wěn)定、可控、可擴(kuò)展的“觸達(dá)層”。這個(gè)觸達(dá)層需要把模型輸出的結(jié)構(gòu)化指令翻譯成真實(shí)世界的動(dòng)作并且把動(dòng)作的結(jié)果反饋回模型讓它能繼續(xù)推理。Agent-Reach 就是沖著這個(gè)需求來(lái)的。1.2 Agent-Reach 是什么能做什么Agent-Reach 本質(zhì)上是一個(gè)面向大語(yǔ)言模型智能體的工具調(diào)用框架。它管了這么幾件事把外部能力HTTP API、數(shù)據(jù)庫(kù)、Shell 命令、文件操作、消息通知封裝成統(tǒng)一的連接器單元。把連接器的能力描述成模型能讀懂的 JSON Schema 聲明。在模型和外部世界之間做參數(shù)校驗(yàn)、調(diào)度執(zhí)行、錯(cuò)誤處理、結(jié)果回傳。對(duì)每一次“觸達(dá)”做日志追蹤保證出問(wèn)題能復(fù)盤(pán)。聽(tīng)起來(lái)是不是像 Function Calling 的包裝對(duì)但不完全是。Function Calling 只是模型輸出一個(gè)“我想調(diào)用某函數(shù)、參數(shù)是什么”的 JSON 結(jié)構(gòu)。真正難的是后面的部分誰(shuí)來(lái)執(zhí)行執(zhí)行失敗怎么辦權(quán)限怎么控制上下文怎么不膨脹多個(gè)工具怎么編排這些才是 Agent 走向生產(chǎn)環(huán)境的攔路虎也是 Agent-Reach 重點(diǎn)解決的部分。1.3 適合誰(shuí)、不適合誰(shuí)說(shuō)實(shí)話(huà)Agent-Reach 不適合那種只想玩玩提示詞的同學(xué)。如果你的需求是“寫(xiě)個(gè) prompt 讓模型回答得更好”那這框架對(duì)你來(lái)說(shuō)太重了。它適合以下幾類(lèi)人正在做智能客服、辦公自動(dòng)化、數(shù)據(jù)分析助手等需要真實(shí)調(diào)用外部服務(wù)的應(yīng)用開(kāi)發(fā)者。已經(jīng)用 Function Calling 跑通了 demo但在并發(fā)、容錯(cuò)、工具數(shù)量增長(zhǎng)后開(kāi)始手忙腳亂的團(tuán)隊(duì)。想把自己的腳本工具優(yōu)雅地“喂”給大模型而不是靠正則或者硬編碼去解析模型回復(fù)的人。如果你只接一兩個(gè) API寫(xiě)死邏輯也行沒(méi)必要上框架。但當(dāng)工具數(shù)量超過(guò)五個(gè)、多個(gè) Agent 共享工具、或者你需要在生產(chǎn)環(huán)境穩(wěn)定運(yùn)行Agent-Reach 這種統(tǒng)一觸達(dá)層的價(jià)值就非常明顯了。我當(dāng)初就是被二十幾個(gè)工具分散在每個(gè)業(yè)務(wù)代碼里的狀態(tài)搞崩潰才下決心抽這一層。2. 整體架構(gòu)我為什么把“觸達(dá)”獨(dú)立成一層2.1 傳統(tǒng) Agent 的三種“假觸達(dá)”我見(jiàn)過(guò)很多項(xiàng)目的做法可以說(shuō)是“充滿(mǎn)了工匠精神的暴力美學(xué)”但每種都有致命傷。第一種是硬編碼解析。模型回答“好的已為您查詢(xún)北京天氣”然后代碼去回復(fù)文本里用正則摳城市名。這個(gè)方案看著簡(jiǎn)單但模型回復(fù)稍微換個(gè)句式正則就掛了而且你根本沒(méi)用到模型的結(jié)構(gòu)化輸出能力。第二種是工具函數(shù)散落各處。每個(gè)業(yè)務(wù)方自己寫(xiě)一個(gè)query_weather()、create_todo()在調(diào)用處手動(dòng)處理參數(shù)、手動(dòng) catch 異常。短期沒(méi)問(wèn)題等工具多起來(lái)你根本不知道哪個(gè)工具被用過(guò)、參數(shù)是什么、失敗了影響誰(shuí)。第三種是讓模型直接輸出可執(zhí)行代碼。這個(gè)最野讓模型生成 Python 代碼然后exec()去跑。安全性和可控性基本為零生產(chǎn)環(huán)境這么干等于裸奔。你會(huì)發(fā)現(xiàn)這三種方式都有一個(gè)共同問(wèn)題外部世界和模型之間的“翻譯官”職責(zé)不清。翻譯邏輯和業(yè)務(wù)邏輯纏在一起。Agent-Reach 的思路很簡(jiǎn)單——把“觸達(dá)”這件事從業(yè)務(wù)代碼里剝離出來(lái)做成一個(gè)獨(dú)立層所有工具必須通過(guò)這個(gè)層進(jìn)出。2.2 分層設(shè)計(jì)Agent / Reach / 外部世界我的項(xiàng)目結(jié)構(gòu)就是三個(gè)橫切層我把它們比作“大腦、手臂和外部環(huán)境”Agent 層負(fù)責(zé)對(duì)話(huà)、推理、規(guī)劃。它只跟結(jié)構(gòu)化的工具聲明打交道不關(guān)心工具內(nèi)部怎么實(shí)現(xiàn)。這一層可以是 OpenAI SDK、LangChain或者你自己寫(xiě)的循環(huán)。Reach 層這是 Agent-Reach 的核心。它維護(hù)工具注冊(cè)表、處理模型傳來(lái)的調(diào)用請(qǐng)求、做參數(shù)校驗(yàn)、調(diào)度連接器執(zhí)行、把結(jié)果整理后回填給 Agent。它像一個(gè)總調(diào)度室加質(zhì)檢部門(mén)。外部世界層被 Reach 層包裝起來(lái)的所有真實(shí)能力。一個(gè)天氣 API、一張數(shù)據(jù)庫(kù)表、一個(gè)運(yùn)維腳本甚至一個(gè)物聯(lián)網(wǎng)設(shè)備都對(duì)應(yīng)一個(gè)連接器實(shí)例。這樣分層最直接的好處是Agent 層不知道外面有多少個(gè)服務(wù)外部世界也不知道對(duì)面是哪個(gè)模型在指揮。中間層只要接口穩(wěn)定兩頭隨便換。今天你用 GPT明天想換國(guó)產(chǎn)模型只需要保證它也支持工具調(diào)用協(xié)議今天你接的是 A 公司的天氣服務(wù)明天換 B 公司只改一個(gè)連接器內(nèi)部實(shí)現(xiàn)不動(dòng) Agent 層。2.3 連接器的統(tǒng)一抽象半小時(shí)接一個(gè)新工具Agent-Reach 的底層抽象非常精簡(jiǎn)一個(gè)連接器就是一個(gè)類(lèi)核心接口只有三個(gè)字段加一個(gè)方法name工具的唯一標(biāo)識(shí)模型會(huì)用這個(gè)名字來(lái)發(fā)起調(diào)用。description自然語(yǔ)言描述告訴模型這個(gè)工具是干嘛的、什么時(shí)候該用。input_schemaJSON Schema定義調(diào)用參數(shù)的類(lèi)型、必填項(xiàng)、枚舉范圍。execute(params)真正干活的方法接收校驗(yàn)后的參數(shù)字典返回結(jié)構(gòu)化結(jié)果。pythonfrom abc import ABC, abstractmethod class Connector(ABC): name: str description: str input_schema: dict {} abstractmethod async def execute(self, params: dict) - dict: ...你沒(méi)看錯(cuò)就這些。很多朋友第一次看我問(wèn)“就這么點(diǎn)”我說(shuō)對(duì)就這么點(diǎn)。工具的復(fù)雜度由你決定——連接器內(nèi)部你可以去調(diào) HTTP、查數(shù)據(jù)庫(kù)、讀寫(xiě)文件、發(fā)消息但對(duì)外暴露的永遠(yuǎn)是這三樣?xùn)|西。正因?yàn)榻涌跇O簡(jiǎn)新接一個(gè)工具通常只要半小時(shí)。你只需要把精力花在寫(xiě)清楚description和input_schema這兩個(gè)是模型能不能正確使用工具的關(guān)鍵后面我會(huì)專(zhuān)門(mén)展開(kāi)。2.4 為什么不做全自動(dòng)而是做受控觸達(dá)有人會(huì)問(wèn)既然有了連接器為什么不直接讓 Agent 自由調(diào)用非要搞一個(gè)中間調(diào)度層來(lái)控制因?yàn)槲页赃^(guò)沒(méi)有管控的虧。早期我做過(guò)一個(gè)版本Agent 可以訪(fǎng)問(wèn)所有注冊(cè)工具結(jié)果有一次它在一個(gè)數(shù)據(jù)分析任務(wù)里連續(xù)調(diào)了十幾遍同一個(gè)大報(bào)表接口把下游服務(wù)打掛了。問(wèn)題不在于模型傻而在于模型在自由發(fā)揮時(shí)不會(huì)天然考慮限流、配額、冪等重試這些工程約束。Agent-Reach 這一層就是在模型的天馬行空和外部世界的現(xiàn)實(shí)約束之間加一道護(hù)欄。護(hù)欄包括三件事調(diào)用前校驗(yàn)參數(shù)不合法直接拒絕不給模型瞎傳的機(jī)會(huì)。調(diào)用中調(diào)度支持限流、超時(shí)控制、并發(fā)限制。調(diào)用后審計(jì)每一次調(diào)用記錄 trace_id、耗時(shí)、參數(shù)摘要、結(jié)果摘要。這套“受控觸達(dá)”的思路讓我后來(lái)在做多 Agent 協(xié)作和權(quán)限隔離時(shí)輕松了很多因?yàn)樗谐鋈肟诙际諗n到一個(gè)地方了。如果哪天模型被別人提示詞攻擊了想去調(diào)危險(xiǎn)工具你在 Reach 層還能做最后一道攔截。3. 核心機(jī)制從 LLM 的意圖到真實(shí)世界的調(diào)用3.1 Function Calling 怎么和連接器對(duì)上號(hào)現(xiàn)在主流的大模型大多支持 Function Calling也稱(chēng) Tool Calling它的工作流程是開(kāi)發(fā)者把工具列表隨請(qǐng)求一起發(fā)給模型模型在適當(dāng)?shù)臅r(shí)候返回一個(gè)結(jié)構(gòu)化指令里面帶tool_calls字段。python# 模型返回的結(jié)構(gòu)化指令示例 { tool_calls: [ { id: call_abc123, type: function, function: { name: get_weather, arguments: {\city\: \北京\, \unit\: \celsius\} } } ] }Agent-Reach 做的事情就是接收這個(gè)name和arguments去注冊(cè)表里找到對(duì)應(yīng)的連接器把a(bǔ)rgumentsJSON 字符串解析成字典然后執(zhí)行。整個(gè)過(guò)程看起來(lái)簡(jiǎn)單實(shí)際上有三個(gè)容易忽略的坑arguments是字符串不是對(duì)象很多新手直接response[tool_calls][0][function][arguments]拿回來(lái)當(dāng)字典用結(jié)果報(bào)錯(cuò)。必須先json.loads。模型返回的工具名要嚴(yán)格匹配連接器的name。所以注冊(cè)時(shí)名字不能亂起最好遵循動(dòng)詞_名詞的命名風(fēng)格描述也要寫(xiě)清楚“什么情景下用”。一次響應(yīng)里可能有多個(gè)tool_calls意味著模型想同時(shí)調(diào)多個(gè)工具。Agent-Reach 支持并行執(zhí)行但你要注意外部服務(wù)是否容忍并發(fā)調(diào)用。3.2 JSON Schema把模型的“腦洞”翻譯成嚴(yán)格的參數(shù)模型的輸出再智能本質(zhì)上也是概率采樣。它會(huì)老老實(shí)實(shí)按 schema 生成參數(shù)但偶爾會(huì)傳一些奇怪值。JSON Schema 在這里的作用就是把模型的自由發(fā)揮收斂到連接器能接受的范圍。我貼一個(gè)實(shí)際的 schema 例子pythoninput_schema { type: object, properties: { city: { type: string, description: 城市中文名稱(chēng)例如北京、上海、廣州 }, unit: { type: string, enum: [celsius, fahrenheit], description: 溫度單位默認(rèn)攝氏 } }, required: [city] }這里有幾個(gè)細(xì)節(jié)非常關(guān)鍵properties里每一項(xiàng)的description要寫(xiě)清楚格式我經(jīng)常寫(xiě)“例如北京”這種帶示例的說(shuō)明。模型對(duì)示例的遵循度遠(yuǎn)高于抽象描述。enum限制枚舉值能有效防止模型傳個(gè)“C”這種代碼里沒(méi)定義的縮寫(xiě)。required字段要克制。能默認(rèn)值的盡量給默認(rèn)值別什么都強(qiáng)制必填。強(qiáng)制項(xiàng)越多模型生成參數(shù)時(shí)犯錯(cuò)的概率越大。校驗(yàn)層我直接用的jsonschema庫(kù)。不通過(guò)校驗(yàn)的調(diào)用不會(huì)執(zhí)行器內(nèi)部而是返回一個(gè)標(biāo)準(zhǔn)錯(cuò)誤給模型讓它知道“參數(shù)有問(wèn)題請(qǐng)重新生成”這比讓連接器內(nèi)部報(bào)一個(gè)莫名其妙的異常友好得多。3.3 工具選擇的策略與開(kāi)銷(xiāo)當(dāng)注冊(cè)的工具越來(lái)越多比如上百個(gè)時(shí)把所有工具描述都塞進(jìn)每次請(qǐng)求是不現(xiàn)實(shí)的。OpenAI 的 token 是按數(shù)量收費(fèi)的而且工具描述會(huì)占用寶貴的上下文窗口。Agent-Reach 里我做了一個(gè)兩層選擇的策略第一層是啟發(fā)式預(yù)篩。連接器注冊(cè)時(shí)可以打標(biāo)簽比如“天氣類(lèi)”“數(shù)據(jù)庫(kù)類(lèi)”“辦公類(lèi)”。Agent 層在發(fā)起請(qǐng)求前可以根據(jù)當(dāng)前用戶(hù)問(wèn)題的關(guān)鍵詞先做一次粗篩。注意這里不是用另一個(gè) LLM 來(lái)做意圖路由那樣成本太貴而是用輕量的詞表匹配或 embedding 相似度。把候選工具控制在 5 個(gè)以?xún)?nèi)再連同用戶(hù)問(wèn)題一起發(fā)給模型。第二層是模型精選。模型在拿到經(jīng)過(guò)預(yù)篩的工具列表后決定到底調(diào)用哪個(gè)以及調(diào)用幾次。這套策略的投入產(chǎn)出比很不錯(cuò)。實(shí)測(cè)下來(lái)工具從 80 個(gè)降到預(yù)篩后的 5 個(gè)請(qǐng)求的 token 消耗下降了約 60%而模型的調(diào)用準(zhǔn)確率還提升了——因?yàn)楣ぞ呱倭四Ｐ瓦x錯(cuò)的風(fēng)險(xiǎn)也低了。代價(jià)是預(yù)篩偶爾會(huì)漏掉正確工具所以標(biāo)簽和關(guān)鍵詞定義要用心維護(hù)。3.4 錯(cuò)誤處理與降級(jí)現(xiàn)實(shí)世界的 API 永遠(yuǎn)會(huì)掛模型擅長(zhǎng)生成流暢的文本但它對(duì)網(wǎng)絡(luò)超時(shí)、HTTP 503、限流這些問(wèn)題一無(wú)所知。Agent-Reach 的調(diào)度器會(huì)接管這些執(zhí)行一段工具調(diào)用時(shí)內(nèi)部是有策略的超時(shí)控制每個(gè)連接器可以聲明自己的超時(shí)時(shí)間默認(rèn) 15 秒。超過(guò)就終止返回timeout錯(cuò)誤給模型。自動(dòng)重試對(duì)于 GET 類(lèi)查詢(xún)接口遇到 429、503 這類(lèi)可恢復(fù)錯(cuò)誤會(huì)自動(dòng)重試最多 3 次采用指數(shù)退避1 秒、2 秒、4 秒。降級(jí)響應(yīng)某些工具掛了不能讓整個(gè) Agent 對(duì)話(huà)崩掉。連接器可以提供一個(gè)fallback_result比如天氣服務(wù)掛了返回“當(dāng)前無(wú)法獲取實(shí)時(shí)天氣請(qǐng)稍后重試”Agent 拿到這個(gè)結(jié)果會(huì)體面地告知用戶(hù)而不是干瞪眼。錯(cuò)誤信息轉(zhuǎn)譯連接器拋出的底層異常需要被轉(zhuǎn)成對(duì)模型友好的文本。模型不是你團(tuán)隊(duì)的開(kāi)發(fā)它看不懂ValueError: invalid literal for int()你要給它一個(gè)“用戶(hù)輸入的日期格式不正確請(qǐng)按照 YYYY-MM-DD 重新生成”這樣清晰可操作的提示。這一步是整個(gè)框架里最容易被低估的部分。很多人把 Function Calling 跑通了就以為完事真正上線(xiàn)后才發(fā)現(xiàn)60% 的時(shí)間花在跟各種 API 異常搏斗上。Agent-Reach 把這些經(jīng)驗(yàn)固化進(jìn)框架你就不用每次都重寫(xiě)一遍了。4. 實(shí)操?gòu)牧愦钜粋€(gè)能查天氣會(huì)寫(xiě)日志的 Agent4.1 環(huán)境準(zhǔn)備與最小依賴(lài)我不會(huì)扯太多先把環(huán)境說(shuō)清楚。我的演示環(huán)境是 Python 3.10用openaiSDK 調(diào)用大模型。這里有一點(diǎn)要說(shuō)明Agent-Reach 本身不綁定任何廠(chǎng)商 SDK它只認(rèn)結(jié)構(gòu)化協(xié)議。你只要用一個(gè)支持 Function Calling 的模型接口把工具聲明按協(xié)議傳過(guò)去就行。國(guó)內(nèi)很多大模型也兼容 OpenAI 的請(qǐng)求格式換成它們只需改幾行配置。裝依賴(lài)就三個(gè)pip install openai jsonschema httpxopenai是調(diào)模型的 SDKjsonschema做參數(shù)校驗(yàn)httpx是連接器里發(fā) HTTP 請(qǐng)求用的?？蚣鼙旧聿恍枰硗庋b什么重量級(jí)的東西這也符合我“輕量可移植”的初衷。4.2 寫(xiě)第一個(gè)連接器本地天氣服務(wù)為了讓你能完整復(fù)現(xiàn)我先起一個(gè)本地天氣模擬服務(wù)。你可以把它理解成一個(gè)“假裝自己是第三方天氣 API”的小應(yīng)用。通過(guò) FastAPI 實(shí)現(xiàn)就一個(gè)接口python# weather_service.py from fastapi import FastAPI import uvicorn app FastAPI() FAKE_WEATHER { 北京: {temp: 21, humidity: 45, condition: 晴}, 上海: {temp: 24, humidity: 68, condition: 多云}, 廣州: {temp: 28, humidity: 80, condition: 小雨}, } app.get(/weather/{city}) def get_weather(city: str): if city not in FAKE_WEATHER: return {error: city not found} data FAKE_WEATHER[city] return {city: city, **data} if __name__ __main__: uvicorn.run(app, host127.0.0.1, port8000)然后寫(xiě) Agent-Reach 的天氣連接器python# connectors.py import httpx from reach import Connector class WeatherConnector(Connector): name get_weather description ( 獲取指定城市的當(dāng)前天氣情況。當(dāng)用戶(hù)詢(xún)問(wèn)某個(gè)城市的溫度、濕度、天氣狀況 或者詢(xún)問(wèn)適不適合出門(mén)、跑步、帶傘等問(wèn)題時(shí)使用。 ) input_schema { type: object, properties: { city: { type: string, description: 城市中文名稱(chēng)例如北京、上海、廣州 } }, required: [city] } async def execute(self, params: dict) - dict: city params[city] async with httpx.AsyncClient(timeout5) as client: resp await client.get(fhttp://127.0.0.1:8000/weather/{city}) if resp.status_code ! 200: return {error: f查詢(xún)城市{city}失敗可能城市名稱(chēng)不支持} data resp.json() return data注意到我把description寫(xiě)得很“啰嗦”特別加了“詢(xún)問(wèn)適不適合出門(mén)、跑步、帶傘”這些觸發(fā)場(chǎng)景。這是有講究的模型本質(zhì)上是一個(gè)文本補(bǔ)全系統(tǒng)描述里相關(guān)情境越多它越容易在正確的時(shí)機(jī)把工具召喚出來(lái)。再搞一個(gè)寫(xiě)本地日志的連接器讓 Agent 能動(dòng)手記錄點(diǎn)東西pythonimport datetime, os class NoteConnector(Connector): name append_note description ( 向本地筆記文件追加一條文本記錄。當(dāng)用戶(hù)要求記住某件事、寫(xiě)一條便簽、 或者把剛才的信息保存下來(lái)時(shí)使用。 ) input_schema { type: object, properties: { content: { type: string, description: 需要記錄的文本內(nèi)容 } }, required: [content] } async def execute(self, params: dict) - dict: content params[content] timestamp datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) with open(notes.txt, a, encodingutf-8) as f: f.write(f[{timestamp}] {content}\n) return {status: ok, saved_to: notes.txt}4.3 注冊(cè)工具與構(gòu)建聲明接下來(lái)是 Agent-Reach 的核心調(diào)度類(lèi)。我把它叫AgentReach維護(hù)一個(gè)字典來(lái)管理連接器pythonclass AgentReach: def __init__(self): self._connectors {} def register(self, connector: Connector): self._connectors[connector.name] connector def list_tools(self) - list[dict]: tools [] for conn in self._connectors.values(): tools.append({ type: function, function: { name: conn.name, description: conn.description, parameters: conn.input_schema } }) return tools async def invoke(self, name: str, arguments: dict) - dict: if name not in self._connectors: return {error: f不存在的工具: {name}} connector self._connectors[name] # 這里按 JSON Schema 校驗(yàn)參數(shù)可省略詳細(xì)代碼 return await connector.execute(arguments)注冊(cè)就是兩行的事pythonreach AgentReach() reach.register(WeatherConnector()) reach.register(NoteConnector())4.4 跑通一個(gè)端到端的對(duì)話(huà)循環(huán)現(xiàn)在把大模型接進(jìn)來(lái)。我用 openai 的 AsyncOpenAI 接口寫(xiě)一個(gè)帶循環(huán)的對(duì)話(huà)跑批pythonimport json from openai import AsyncOpenAI client AsyncOpenAI(api_keyyour-api-key, base_urlyour-compatible-endpoint) async def run_agent(user_input: str): messages [{role: user, content: user_input}] max_steps 5 for _ in range(max_steps): resp await client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsreach.list_tools(), tool_choiceauto ) choice resp.choices[0] message choice.message # 沒(méi)有工具調(diào)用直接回復(fù)用戶(hù) if not message.tool_calls: print(Agent 回復(fù):, message.content) return # 把模型的中間消息加入對(duì)話(huà) messages.append({ role: assistant, content: message.content, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments } } for tc in message.tool_calls ] }) # 執(zhí)行每個(gè)工具調(diào)用 for tc in message.tool_calls: fn_name tc.function.name try: args json.loads(tc.function.arguments) except json.JSONDecodeError: args {} result await reach.invoke(fn_name, args) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) print(達(dá)到了最大步數(shù)對(duì)話(huà)未完成) await run_agent(北京今天適合去跑步嗎跑完順便幫我在筆記本里記一下跑步計(jì)劃。)這個(gè)循環(huán)是 ReAct 模式的一種極簡(jiǎn)實(shí)現(xiàn)模型決定調(diào)工具 - 我們把結(jié)果返回給模型 - 模型看到結(jié)果再推理 - 直到它認(rèn)為自己有足夠信息回答用戶(hù)。軌道里有一個(gè)細(xì)節(jié)tool_choiceauto意思是讓模型自己決定要不要調(diào)工具、調(diào)哪個(gè)。如果我把它改成{type: function, function: {name: get_weather}}模型每次都會(huì)被強(qiáng)制調(diào)用指定工具這在某些強(qiáng)制工具場(chǎng)景下很有用。4.5 觀(guān)察與調(diào)試日志里到底發(fā)生了什么第一次跑通的時(shí)候我建議你打印每一步的消息內(nèi)容親眼看看模型是怎么規(guī)劃的。我跑了一次邏輯大致如下用戶(hù)提問(wèn)“北京今天適合跑步嗎順便記一下計(jì)劃”。模型返回兩個(gè)tool_calls先調(diào)get_weather再調(diào)append_note它會(huì)把待辦內(nèi)容也一起推理出來(lái)。天氣返回{city: 北京, temp: 21, humidity: 45, condition: 晴}。筆記寫(xiě)入本地文件。模型看到結(jié)果后生成最終回復(fù)“北京現(xiàn)在 21 度晴濕度 45%非常適合戶(hù)外跑。已經(jīng)把跑步計(jì)劃記下來(lái)了?！闭麄€(gè)流程里模型沒(méi)有直接寫(xiě)死任何數(shù)據(jù)它只是做了“決策”而真正的動(dòng)作都發(fā)生在連接器里。這就是 Agent-Reach 的價(jià)值模型負(fù)責(zé)智能框架負(fù)責(zé)可靠。我記得第一次真正跑通這個(gè)流程的時(shí)候最大的感觸是“原來(lái)對(duì)話(huà)里塞進(jìn) JSON 格式的工具結(jié)果這么關(guān)鍵”。如果你返回的結(jié)果是一段亂七八糟的非結(jié)構(gòu)化文本模型后續(xù)很容易糊涂。所以我強(qiáng)烈建議連接器的返回值一律是干凈的 JSON。格式越規(guī)范模型的推理越穩(wěn)。5. 踩坑實(shí)錄你大概率也會(huì)遇到的5個(gè)問(wèn)題5.1 模型就是不調(diào)用工具氣死人這是所有 Function Calling 新手第一個(gè)崩潰點(diǎn)。你的工具描述寫(xiě)得沒(méi)問(wèn)題但模型就是理都不理直接干答。排查方向有四個(gè)描述里缺少觸發(fā)條件。你可以像寫(xiě)觸發(fā)詞一樣把“當(dāng)用戶(hù)詢(xún)問(wèn)天氣時(shí)”這類(lèi)條件寫(xiě)進(jìn)描述模型會(huì)敏感很多。模型能力太弱。有些小模型對(duì)工具調(diào)用支持不完善建議至少用經(jīng)過(guò)工具調(diào)用微調(diào)的模型版本。上下文里沒(méi)有足夠信號(hào)。比如用戶(hù)說(shuō)“今天出門(mén)咋樣”模型可能沒(méi)意識(shí)到這是讓你查天氣。你可以先在提示詞系統(tǒng)層加一句“當(dāng)詢(xún)問(wèn)涉及時(shí)效性或外部數(shù)據(jù)時(shí)應(yīng)優(yōu)先調(diào)用工具?！惫ぞ呗暶鞲袷讲粚?duì)。很多兼容接口對(duì)parameters的 schema 要求很?chē)?yán)格type: object必須寫(xiě)properties必須存在少了某些字段會(huì)被靜默忽略。我的經(jīng)驗(yàn)是90% 的情況都是描述寫(xiě)得太籠統(tǒng)。你把示例場(chǎng)景寫(xiě)進(jìn)去之后調(diào)用率會(huì)肉眼可見(jiàn)地提升。5.2 參數(shù)校驗(yàn)失敗日期格式、枚舉、空值模型傳參有時(shí)會(huì)“作妖”。最常見(jiàn)的是日期你要求YYYY-MM-DD它給你傳個(gè)“明天”或者“2024年5月1日”。這種問(wèn)題靠 JSON Schema 的format字段也救不回來(lái)因?yàn)槟Ｐ蜕傻淖址L(fēng)格難以約束。我現(xiàn)在的做法分兩層在input_schema的description里明確寫(xiě)“必須使用 ISO 格式 YYYY-MM-DD例如 2024-05-01”。在校驗(yàn)失敗時(shí)不直接給模型拋 Python 異常而是返回一個(gè)友好的重試提示“日期參數(shù)格式不正確請(qǐng)使用 YYYY-MM-DD 格式重新提供。”還有一個(gè)隱藏坑有些模型在工具調(diào)用里會(huì)生成null值給非必填字段。JSON Schema 校驗(yàn)器默認(rèn)會(huì)拒絕但實(shí)際業(yè)務(wù)里null往往意味著“沒(méi)傳”可以讓連接器內(nèi)部做空值兜底。Agent-Reach 里我對(duì)可選字段做了寬松處理避免模型因?yàn)橐稽c(diǎn)小問(wèn)題反復(fù)重試白白燒 token。5.3 外部 API 超時(shí)Agent 直接“死機(jī)”之前我遇到過(guò)外部接口響應(yīng)慢了模型端等了很久整個(gè)對(duì)話(huà)超時(shí)用戶(hù)體驗(yàn)就是“轉(zhuǎn)圈圈五分鐘然后報(bào)錯(cuò)”。這個(gè)問(wèn)題要砸四錘子給 http 客戶(hù)端設(shè)置硬超時(shí)。我用httpx.Timeout(5.0)寧可失敗也別無(wú)限等。給工具調(diào)用加總超時(shí)。Agent-Reach 調(diào)度層默認(rèn) 15 秒一個(gè)工具執(zhí)行超過(guò)就 kill 掉并返回timeout。失敗時(shí)讓模型“軟著陸”。工具返回“服務(wù)超時(shí)請(qǐng)告知用戶(hù)稍后重試”模型會(huì)把這句話(huà)變成得體的回復(fù)而不是報(bào)一個(gè)難看的異常。對(duì)于外部服務(wù)偶爾不穩(wěn)定加上指數(shù)退避重試。我見(jiàn)過(guò)太多人只做超時(shí)設(shè)置不做降級(jí)返回結(jié)果超時(shí)后 Agent 直接拋異常整個(gè)對(duì)話(huà)崩掉。其實(shí)在 Agent 這個(gè)場(chǎng)景里“體面的失敗”比“努力的成功”更寶貴。5.4 token 爆炸工具返回內(nèi)容把上下文撐爆工具返回的結(jié)果要回傳給模型而模型是有上下文長(zhǎng)度上限的。很多人一開(kāi)始圖省事API 返回什么就往上下文里塞什么。某次一個(gè)查詢(xún)接口返回了 20KB 的數(shù)據(jù)模型直接“失憶”了把前面的對(duì)話(huà)內(nèi)容全沖掉。Agent-Reach 的解決辦法是“結(jié)果再加工”對(duì)返回內(nèi)容做字段裁剪。比如查詢(xún)天氣只保留溫度、濕度、天氣現(xiàn)象其他無(wú)關(guān)字段統(tǒng)統(tǒng)不要。對(duì)列表數(shù)據(jù)做摘要或截?cái)唷Ｈ绻祷?100 條記錄就截取前 5 條并注明“共有 100 條結(jié)果當(dāng)前展示前 5 條”。對(duì)超長(zhǎng)文本做抽取只回傳和用戶(hù)問(wèn)題最相關(guān)的句子。記住模型不是一個(gè)數(shù)據(jù)庫(kù)它不需要看到全量原始數(shù)據(jù)它只需要看到能回答問(wèn)題的最小充分信息。這個(gè)習(xí)慣越早養(yǎng)成你的 token 賬單越好看。5.5 安全越界模型被騙去調(diào)危險(xiǎn)工具這可能是最需要警惕的問(wèn)題。當(dāng)你的 Agent 能調(diào)刪除數(shù)據(jù)庫(kù)記錄、執(zhí)行 Shell 命令這類(lèi)敏感操作時(shí)提示詞注入攻擊就會(huì)成為真實(shí)風(fēng)險(xiǎn)。用戶(hù)不一定是有意的但他完全可能問(wèn)出“刪掉昨天那批測(cè)試數(shù)據(jù)”這種話(huà)模型不懂輕重可能直接就執(zhí)行了。我給 Agent-Reach 加了三層防護(hù)工具分層。把連接器分成只讀、普通寫(xiě)、高危寫(xiě)三個(gè)等級(jí)。高危工具默認(rèn)不開(kāi)放給模型自動(dòng)調(diào)用。人類(lèi)確認(rèn)。高危操作返回給前端要求用戶(hù)二次確認(rèn)后才真正執(zhí)行。模型只是組裝出“待確認(rèn)的指令”不落地。調(diào)用白名單。Agent-Reach 內(nèi)部可以配置每個(gè) Agent 實(shí)例允許訪(fǎng)問(wèn)的工具列表實(shí)現(xiàn) Agent 之間的權(quán)限隔離。這三層不是我在紙上談兵我確實(shí)因?yàn)橐粋€(gè) demo 里模型誤調(diào)了刪除接口而翻過(guò)車(chē)從那以后高危工具一律人審確認(rèn)。在 Agent 這塊可控性永遠(yuǎn)比炫技重要。6. 進(jìn)階方向與我的個(gè)人體會(huì)6.1 從單 Agent 到多 Agent 的觸達(dá)協(xié)作Agent-Reach 作為一個(gè)獨(dú)立觸達(dá)層天然適合多 Agent 場(chǎng)景。你可以讓一個(gè)客服 Agent 和一個(gè)數(shù)據(jù)分析 Agent 共享同一套連接器但各自靠權(quán)限白名單隔離。每個(gè) Agent 看到的是同一工具的不同子集誰(shuí)也不能越權(quán)。這種架構(gòu)的好處是工具接入一次多個(gè) Agent 復(fù)用不用各自實(shí)現(xiàn)一遍調(diào)用邏輯。下一步我打算在框架里加上工具使用的“頻率統(tǒng)計(jì)”和“成功率上報(bào)”用來(lái)反哺 Agent 的工具選擇策略。哪些工具容易失敗、哪些工具經(jīng)常被選中這些數(shù)據(jù)積累下來(lái)會(huì)很有價(jià)值。6.2 可觀(guān)測(cè)性與成本控制生產(chǎn)環(huán)境里你可以把每一次工具調(diào)用的 trace 日志接入現(xiàn)有的監(jiān)控體系。Agent-Reach 已經(jīng)內(nèi)置了簡(jiǎn)單的日志鉤子記錄調(diào)用 ID、連接器名、耗時(shí)、結(jié)果摘要。把這些數(shù)值拉出來(lái)你就知道哪個(gè)工具是瓶頸、哪個(gè) Agent 在燒錢(qián)。成本控制上有一個(gè)很實(shí)用的技巧設(shè)置“單輪對(duì)話(huà)最大工具調(diào)用次數(shù)”和“每日累計(jì)調(diào)用預(yù)算”。前者我用循環(huán)的max_steps控制后者可以在調(diào)度層做計(jì)數(shù)器超了就拒絕新的工具調(diào)用并提示用戶(hù)“今日額度已用完”。這些細(xì)節(jié)普通 Function Calling demo 不會(huì)考慮但生產(chǎn)環(huán)境必須有。6.3 我最有感觸的一件事最后多說(shuō)一句是純個(gè)人體驗(yàn)。我之前總想讓模型把工具選擇、參數(shù)生成、錯(cuò)誤修復(fù)“全包全攬”結(jié)果發(fā)現(xiàn)越是復(fù)雜的 Agent越需要框架替它擋住外部世界的混亂。模型的聰明才智應(yīng)該用在理解用戶(hù)意圖和規(guī)劃步驟上而不是一遍遍跟 JSON 解析異常死磕。Agent-Reach 走到現(xiàn)在最重要的不是它有多少行代碼而是它讓我重新理解了“連接”這個(gè)詞。所謂連接不是把 URL 拼進(jìn) HTTP 請(qǐng)求那么簡(jiǎn)單而是在模型的概率性輸出和世界的確定性調(diào)用之間建立起一套可期望、可追溯、可兜底的翻譯機(jī)制。這套機(jī)制我建議每個(gè)想在 Agent 上做正經(jīng)東西的人都認(rèn)真設(shè)計(jì)一遍。踩過(guò)坑之后你會(huì)明白那層看起來(lái)不起眼的膠水代碼恰恰是整個(gè)系統(tǒng)的承重墻。