 Tool Calling，先搞懂 LLM 怎么變成程序真正能用的“接口”)
第一課我們講了一件看起來很簡單但其實(shí)決定了整個(gè) Agent 技術(shù)棧的事情LLM 只會(huì)產(chǎn)生輸出它不會(huì)直接改變外部世界。你讓一個(gè)裸模型刪除 report.txt它可以回答好的report.txt 已刪除。甚至可以生成os.remove(report.txt)但只要外面沒有程序真正執(zhí)行os.remove()你的文件就還好好地躺在硬盤里。所以第一課最后我們把 Model 和 Runtime 分開了Model決定應(yīng)該做什么 Runtime真正把事情做掉到這里其實(shí)已經(jīng)很接近 Agent 了。但如果你真的開始自己寫代碼會(huì)立刻撞上第二個(gè)問題。而且這個(gè)問題比“怎么調(diào)用 Tool”更早出現(xiàn)。假設(shè)用戶說幫我查一下上海今天的天氣 看看下午要不要帶傘。模型判斷完之后回答我覺得這個(gè)問題最好先查一下上海今天的天氣。作為人你當(dāng)然看得懂。但現(xiàn)在不要站在人類的角度看這句話。站在代碼的角度看。你的程序拿到的其實(shí)只是response 我覺得這個(gè)問題最好先查一下上海今天的天氣。 然后呢程序怎么知道模型到底想干什么這就是第二課真正要解決的問題。人能聽懂的話不一定是一個(gè)好的軟件接口假設(shè)我們的 Runtime 現(xiàn)在有三個(gè)能力查詢天氣 查詢訂單 直接回答用戶那么模型每一次做完判斷之后程序真正關(guān)心的其實(shí)只有一件事你到底選擇了哪一個(gè)但模型偏偏特別擅長“說人話”。它可能說我需要先看看上海天氣。下一次可能說為了回答這個(gè)問題我需要獲取上海當(dāng)前的氣象信息。還可能說最好先確認(rèn)一下上海今天有沒有雨。換個(gè)模型也許直接變成Let me check the weather in Shanghai first.對人來說這四句話表達(dá)的是同一個(gè)意思。對程序來說這是四個(gè)完全不同的字符串。于是很多人第一次自己寫這種程序時(shí)會(huì)很自然地干一件事if 天氣 in response: get_weather()看起來居然還能跑。然后有一天模型回答我需要看看上海今天會(huì)不會(huì)下雨。沒有“天氣”兩個(gè)字。代碼失效。于是你補(bǔ)if 天氣 in response or 下雨 in response: get_weather()過幾天模型又回答先獲取一下當(dāng)?shù)貧庀笄闆r吧。于是你繼續(xù)補(bǔ)if ( 天氣 in response or 下雨 in response or 氣象 in response ): get_weather()如果再復(fù)雜一點(diǎn)你很快就會(huì)開始寫正則表達(dá)式。然后再給正則表達(dá)式打補(bǔ)丁。再給補(bǔ)丁打補(bǔ)丁。做到這里應(yīng)該已經(jīng)能感覺到哪里不對了。問題并不在于模型“不夠聰明”。真正的問題是我們正在拿自然語言當(dāng)軟件協(xié)議用。而自然語言恰恰是一個(gè)極度不穩(wěn)定的軟件協(xié)議。人類喜歡自然語言是因?yàn)槲覀兎浅Ｉ瞄L容忍模糊。程序恰恰相反。程序最喜歡的是字段叫什么是確定的。 類型是什么是確定的。 允許出現(xiàn)哪些值是確定的。 缺少字段怎么辦也是確定的。于是 Agent 工程里第一個(gè)非常自然的問題出現(xiàn)了能不能不要讓 Runtime 猜模型是什么意思而是讓模型直接按照程序約定的格式表達(dá)自己的決定這就是 Structured Output 真正要解決的問題。第一次關(guān)鍵轉(zhuǎn)變從“說一句話”變成“返回一個(gè)數(shù)據(jù)結(jié)構(gòu)”還是剛才的問題。用戶幫我查一下上海今天的天氣。以前模型返回我認(rèn)為應(yīng)該先查詢上海天氣?，F(xiàn)在我們要求模型返回{ action: get_weather, arguments: { city: Shanghai } }看起來只是換成了 JSON。但從軟件工程角度看事情已經(jīng)發(fā)生了本質(zhì)變化。以前 Runtime 拿到我認(rèn)為應(yīng)該先查詢上海天氣。它必須先理解一句自然語言。現(xiàn)在 Runtime 拿到decision[action]得到get_weather再讀取decision[arguments][city]得到ShanghaiRuntime 不需要理解中文。不需要 NLP。不需要關(guān)鍵詞。也不需要猜。這時(shí)候LLM 第一次從一個(gè)自然語言生成器開始變成了一個(gè)可以被軟件消費(fèi)的決策接口這才是 Structured Output 真正重要的地方。它解決的從來不是“讓輸出看起來整齊一點(diǎn)”。它解決的是怎樣把一個(gè)概率模型的輸出接進(jìn)一個(gè)確定性的軟件系統(tǒng)。這一點(diǎn)非常重要。因?yàn)楹竺嬲麄€(gè) Agent 都建立在這條橋上。但這里有一個(gè)坑會(huì)輸出 JSON不等于真正有了 Structured Output很多人學(xué)到這里會(huì)覺得事情已經(jīng)解決了。Prompt 里面寫一句請嚴(yán)格返回 JSON不要輸出其他內(nèi)容。然后告訴模型格式 { action: ..., arguments: {} }看起來很合理。但你真正跑幾次就會(huì)發(fā)現(xiàn)問題來了。模型可能返回當(dāng)然可以下面是結(jié)果 { action: get_weather, arguments: { city: Shanghai } }這時(shí)候json.loads(response)直接失敗。你說沒關(guān)系我再強(qiáng)調(diào)一次“只能返回 JSON”。然后下一次模型很聽話{ action: weather, arguments: { city: Shanghai } }這是合法 JSON。但 Runtime 根本沒有一個(gè)叫weather的 Action。Runtime 只有g(shù)et_weather再下一次{ action: get_weather, arguments: { city: 100 } }還是合法 JSON。但city為什么變成數(shù)字了甚至可能{ action: get_weather, arguments: {} }JSON 依然完全合法。但最關(guān)鍵的city不見了。這時(shí)候有一個(gè)很值得記住的區(qū)別Valid JSON ≠ Valid Decision這句話最好記住。JSON 解決的只是語法。但一個(gè)軟件接口真正需要的是契約。Schema 才是這里真正重要的東西假設(shè)我們希望模型返回{ action: get_weather, arguments: { city: Shanghai } }真正需要定義的其實(shí)遠(yuǎn)遠(yuǎn)不只是“大括號怎么寫”。我們需要告訴模型和 Runtime最外層必須是 object。 必須存在 action。 action 必須是 string。 action 只能取幾個(gè)指定值。 必須存在 arguments。 arguments 必須是 object。 如果 action 是 get_weather 那么 arguments 里必須有 city。 city 必須是 string。這就是 Schema 在干的事情。例如我們可以表達(dá)成類似這樣的約束{ type: object, properties: { action: { type: string, enum: [ get_weather, query_order, final_answer ] }, arguments: { type: object } }, required: [ action, arguments ] }具體以后你用 JSON Schema、類型系統(tǒng)還是某個(gè)模型 SDK 提供的 Structured Output API并不是這一課最值得記住的事情。真正重要的是腦子里要建立一個(gè)概念Schema 是 Model 和 Runtime 之間的 Contract。Runtime 相當(dāng)于在告訴模型你可以負(fù)責(zé)判斷。 但如果你希望軟件理解你的判斷 請按照這個(gè)協(xié)議說。這就是一個(gè)非常標(biāo)準(zhǔn)的軟件工程思想。只不過協(xié)議的一端不再是另一個(gè)確定性的服務(wù)。而是一個(gè) LLM。第二個(gè)關(guān)鍵轉(zhuǎn)變我們實(shí)際上正在限制模型的“動(dòng)作空間”這里有一個(gè)我認(rèn)為比“學(xué)會(huì) JSON Schema”重要得多的理解。假設(shè)我們告訴模型action 只能是 get_weather query_order final_answer這意味著什么意味著模型不能突然自己發(fā)明一個(gè)search_weather_from_google也不能發(fā)明open_browser更不能突然來一個(gè)delete_database從 Runtime 的角度我們實(shí)際上定義了Action Space { get_weather, query_order, final_answer }這個(gè)概念特別重要。因?yàn)榈竭@里L(fēng)LM 已經(jīng)不再只是“根據(jù)上下文繼續(xù)生成一段文字”從 Agent Engineering 的視角我們可以開始換一種方式理解它給定當(dāng)前 Context ↓ 模型判斷當(dāng)前應(yīng)該做什么 ↓ 從允許的 Action Space 里選擇一個(gè) Action如果寫得更抽象一點(diǎn)Context / State ↓ LLM ↓ Choose Action這已經(jīng)開始非常像 Agent 了。而且你會(huì)發(fā)現(xiàn)Schema 不只是定義數(shù)據(jù)格式。它還在定義這個(gè) Agent 到底被允許做出哪些類型的決定。這是這一課非常重要的一個(gè)“恍然大悟”。Schema 設(shè)計(jì)本身就是 Agent 設(shè)計(jì)我們繼續(xù)往下推。最開始只有一個(gè)動(dòng)作get_weather所以很簡單{ action: get_weather, arguments: { city: Shanghai } }后來系統(tǒng)又增加一個(gè)能力query_order它需要的參數(shù)不是city而是order_id于是{ action: query_order, arguments: { order_id: PO-10086 } }再后來增加search_web它需要query于是{ action: search_web, arguments: { query: Agent Memory } }到這里你會(huì)慢慢看到一個(gè)結(jié)構(gòu)出現(xiàn)了Decision │ ├── action │ └── argumentsaction回答我準(zhǔn)備做什么arguments回答完成這個(gè)動(dòng)作需要什么參數(shù)這已經(jīng)和函數(shù)調(diào)用非常像了。例如 Pythonget_weather(cityShanghai)和結(jié)構(gòu)化 Decision{ action: get_weather, arguments: { city: Shanghai } }兩者之間幾乎已經(jīng)可以一一對應(yīng)。注意這個(gè)時(shí)候我們?nèi)匀粵]有執(zhí)行函數(shù)。但是 Model 和 Runtime 之間已經(jīng)建立好了“如何描述一個(gè)函數(shù)調(diào)用”的語言。這就是為什么 Structured Output 應(yīng)該放在 Tool Calling 前面講。否則你第一次看到 Tool Calling 的時(shí)候很容易誤以為模型里面有一個(gè)什么神秘的函數(shù)執(zhí)行系統(tǒng)。其實(shí)完全沒有必要這么理解。把前面的東西一步一步推出來以后你會(huì)發(fā)現(xiàn)Tool Calling 馬上就要變得非常樸素了。到這里先停一下模型還是沒有調(diào)用任何東西這個(gè)邊界必須再強(qiáng)調(diào)一次。模型返回{ action: get_weather, arguments: { city: Shanghai } }請問上海天氣查了嗎沒有。一點(diǎn)都沒有?，F(xiàn)在真實(shí)發(fā)生的事情仍然只有Context ↓ LLM ↓ Tokens ↓ Structured Data模型只是用一種程序容易理解的方式表達(dá)“我認(rèn)為下一步應(yīng)該查詢上海天氣?！币郧八弥形谋磉_(dá)。現(xiàn)在它用結(jié)構(gòu)化數(shù)據(jù)表達(dá)。本質(zhì)沒有變化這仍然只是 Decision。真正的天氣查詢必須等 Runtime 做get_weather(cityShanghai)才會(huì)發(fā)生。所以這里可以建立一個(gè)以后非常有用的邊界Structured Output 如何表達(dá) Decision Tool Execution 如何執(zhí)行 Action這兩件事情不要混。一旦混了你后面學(xué) Tool Calling、MCP、Agent Loop 時(shí)會(huì)越來越亂。我們現(xiàn)在真的寫一個(gè)02_structured_output.py這一課仍然不要 LangChain。不要 LangGraph。也不要任何 Agent Framework。我們的項(xiàng)目繼續(xù)保持agent-from-zero/ │ ├── 01_llm.py └── 02_structured_output.py第一課User ↓ LLM ↓ Text這一課只增加一件東西User ↓ LLM ↓ Structured Decision ↓ Validation我們的目標(biāo)非?？酥撇皇亲?Agent。只是讓模型學(xué)會(huì)輸出 Runtime 能可靠理解的 Decision。假設(shè)系統(tǒng)目前允許四種決定get_weather query_order ask_user final_answer為什么多了一個(gè)ask_user等一下就會(huì)知道。我們先約定一個(gè)統(tǒng)一格式{ action: ..., arguments: {} }例如{ action: get_weather, arguments: { city: Shanghai } }或者{ action: query_order, arguments: { order_id: PO-10086 } }程序拿到模型返回之后第一件事不是執(zhí)行。而是import json def parse_decision(raw): return json.loads(raw)這是 Parser。它只解決一個(gè)問題模型返回的東西 能不能被解析成 JSON例如{ action: get_weather, arguments: { city: Shanghai } }可以。而好的我建議查詢天氣。不可以。但只有 Parser 遠(yuǎn)遠(yuǎn)不夠。我們還需要 Validator。比如ALLOWED_ACTIONS { get_weather, query_order, ask_user, final_answer, } def validate_decision(decision): if action not in decision: raise ValueError(missing action) if arguments not in decision: raise ValueError(missing arguments) if decision[action] not in ALLOWED_ACTIONS: raise ValueError(unknown action) if not isinstance(decision[arguments], dict): raise ValueError(arguments must be an object) return decision現(xiàn)在raw llm(messages) decision parse_decision(raw) decision validate_decision(decision)先不用糾結(jié)llm()具體是哪一家 API。我們現(xiàn)在研究的是結(jié)構(gòu)。這幾行代碼其實(shí)已經(jīng)把一個(gè)非常重要的東西拆出來了Model Output ↓ Parse ↓ Validate ↓ Decision以后做大型 Agent 時(shí)你會(huì)發(fā)現(xiàn)這幾層依然存在。只不過實(shí)現(xiàn)得復(fù)雜得多。Parser 和 Validator千萬不要混成一件事這個(gè)區(qū)別值得專門講一下。假設(shè)模型輸出{ action: destroy_planet, arguments: {} }這是合法 JSON 嗎當(dāng)然是。所以ParserPASS但這是我們允許的 Decision 嗎不是。因?yàn)閐estroy_planet根本不屬于我們的 Action Space。所以ValidatorFAIL這就是為什么Valid JSON ≠ Valid Decision再比如{ action: get_weather, arguments: {} }JSON 完全正確。Action 也存在。但get_weather明明需要city。所以更嚴(yán)格的 Validator 還應(yīng)該檢查if decision[action] get_weather: if city not in decision[arguments]: raise ValueError(get_weather requires city)這時(shí)候你開始進(jìn)入真正的軟件接口設(shè)計(jì)了。你不是在問“模型有沒有大概理解我的意思”你是在問“這個(gè)輸出是否滿足系統(tǒng)契約”這兩個(gè)問題完全不是一個(gè)層次。一個(gè)特別值得做的實(shí)驗(yàn)故意不給模型足夠信息現(xiàn)在用戶說幫我查一下天氣。注意。沒有城市。如果你的 Schema 只有g(shù)et_weather final_answer模型會(huì)陷入一個(gè)很尷尬的狀態(tài)。它想調(diào)用get_weather。但參數(shù)不完整。怎么辦一個(gè)非常自然的解決辦法是增加ask_user于是 Action Space 變成get_weather query_order ask_user final_answer模型可以返回{ action: ask_user, arguments: { question: 你想查詢哪個(gè)城市的天氣 } }這個(gè)例子非常值得反復(fù)琢磨。因?yàn)檫@里第一次可以清楚地看到我們怎樣設(shè)計(jì) Schema會(huì)直接決定 Agent 能采取什么行為。如果沒有ask_user模型沒有一種正式方式表達(dá)“信息不夠我需要問用戶?！痹黾觓sk_user以后這種行為突然成為了系統(tǒng)允許的一等 Action。也就是說Schema 并不只是描述輸出長什么樣它實(shí)際上參與定義 Agent 的能力邊界。這件事到了復(fù)雜 Agent 里會(huì)越來越明顯。再看一個(gè)企業(yè)場景你會(huì)更容易理解為什么這件事重要假設(shè)以后我們做一個(gè)企業(yè)內(nèi)部 Agent。用戶說幫我查一下 PO-20260807-001 的狀態(tài)。一種設(shè)計(jì)是讓模型直接生成 SQL{ sql: SELECT * FROM orders WHERE id PO-20260807-001 }看起來很靈活。但是這種設(shè)計(jì)很快會(huì)帶來另外一個(gè)問題為什么模型一定會(huì)生成SELECT它也可能生成DELETE FROM orders ...甚至生成一段你完全沒有預(yù)料到的 SQL。于是更合理的設(shè)計(jì)通常不是讓 LLM 自由創(chuàng)造底層操作而是 Runtime 先定義安全的高層能力query_order模型只負(fù)責(zé){ action: query_order, arguments: { order_id: PO-20260807-001 } }真正的 SQLSELECT ...由 Runtime 內(nèi)部自己決定。這其實(shí)延續(xù)了第一課那個(gè)非常重要的思想Model 決定 What Runtime 控制 How模型可以判斷我要查詢這個(gè)訂單但數(shù)據(jù)庫應(yīng)該怎么連、SQL 怎么寫、權(quán)限怎么控制、哪些字段能返回不應(yīng)該默認(rèn)全部交給模型自由發(fā)揮。所以 Structured Output 表面是在講輸出格式。繼續(xù)往下看你會(huì)發(fā)現(xiàn)它已經(jīng)開始碰到權(quán)限邊界 API 設(shè)計(jì) 安全邊界 系統(tǒng)職責(zé)劃分這才是它真正有價(jià)值的地方。為什么我說 Structured Output 是 Model 和 Runtime 的“邊界協(xié)議”到這里我們終于可以把整個(gè)結(jié)構(gòu)畫完整。第一課只有Context ↓ LLM ↓ Output第二課變成Context ↓ LLM ↓ Structured Output ↓ Parser ↓ Validator ↓ Decision再往下未來才會(huì)是Decision ↓ Runtime ↓ Tool ↓ Environment所以 Structured Output 恰好站在一個(gè)非常特殊的位置概率世界 │ LLM │ ↓ Structured Output │ ───────────┼─────────── Model / Runtime Boundary ───────────┼─────────── │ ↓ Validator │ Runtime │ Tool │ Environment 確定性世界上面是概率模型。下面是傳統(tǒng)軟件系統(tǒng)。中間必須有一個(gè)雙方都能理解的 Contract。否則下面的軟件永遠(yuǎn)在猜模型剛才那句話到底什么意思所以如果一定要用一句話總結(jié)這一課我更喜歡這樣說Structured Output 的真正價(jià)值是把 LLM 的概率性輸出壓縮成軟件系統(tǒng)可以驗(yàn)證和消費(fèi)的確定性接口。這比“讓模型輸出 JSON”準(zhǔn)確得多。還有一個(gè)很重要的原則Schema 不是越復(fù)雜越好當(dāng)大家第一次意識到 Schema 可以控制模型輸出之后很容易開始設(shè)計(jì)這種東西{ thought: ..., reasoning: ..., analysis: ..., confidence: 0.87, intent: ..., action: ..., arguments: {}, explanation: ..., summary: ... }看上去信息特別豐富。但先問一個(gè)問題Runtime 真正需要什么如果 Runtime 最終只消費(fèi)action arguments那么其他字段為什么一定要存在接口設(shè)計(jì)有一個(gè)非常樸素的原則只暴露真正需要暴露的東西。Structured Output 同樣如此。你不是在試圖把模型所有“思考”全部結(jié)構(gòu)化而是在定義軟件下一步真正需要消費(fèi)什么數(shù)據(jù)這兩個(gè)目標(biāo)差別很大。好的 Schema 往往不是最大的 Schema。而是足夠表達(dá)決策 足夠驗(yàn)證 沒有多余耦合這也會(huì)成為后面設(shè)計(jì) Tool Schema 時(shí)非常重要的原則。到這里你其實(shí)已經(jīng)摸到 Tool Calling 的本質(zhì)了現(xiàn)在再看{ action: get_weather, arguments: { city: Shanghai } }有沒有一種非常熟悉的感覺它其實(shí)已經(jīng)長得很像get_weather(cityShanghai)差的只剩下一步到底誰把前面的數(shù)據(jù)結(jié)構(gòu)變成后面的真實(shí)函數(shù)執(zhí)行答案當(dāng)然不是模型。而是 Runtime。也就是說下一課我們只需要繼續(xù)增加一層Structured Decision ↓ Runtime ↓ 根據(jù) action 找到函數(shù) ↓ 傳入 arguments ↓ 真正執(zhí)行例如概念上tools { get_weather: get_weather, query_order: query_order, }然后tool tools[decision[action]] result tool( **decision[arguments] )這時(shí)候才發(fā)生真正的Action而今天整整一課我們只解決Decision 應(yīng)該怎樣被可靠地表達(dá)這個(gè)順序非常重要。因?yàn)橐坏┻@層理解了下一課所謂的 Tool Calling 會(huì)突然祛魅。你會(huì)發(fā)現(xiàn)它并不是LLM 神奇地?fù)碛辛苏{(diào)用函數(shù)的能力而是Model 產(chǎn)生一個(gè)符合協(xié)議的 Tool Decision ↓ Runtime 解釋這個(gè) Decision ↓ 真正執(zhí)行函數(shù)而已。第二課學(xué)到這里應(yīng)該形成一個(gè)新的腦內(nèi)模型第一課結(jié)束時(shí)我們腦子里的 LLM 是LLM 根據(jù) Context 生成 Output第二課結(jié)束之后應(yīng)該再多一層理解LLM 可以根據(jù) Context 生成符合特定 Contract 的 Decision于是 Agent 的結(jié)構(gòu)開始慢慢長出來User ↓ Context ↓ LLM ↓ Structured Decision ↓ Parser / Validator注意。目前還不是 Agent。因?yàn)槲覀兩踔吝€沒有真正執(zhí)行任何 Tool。但一個(gè)非常重要的地基已經(jīng)完成了Model 和 Runtime 終于有辦法可靠通信了。下一課我們只需要把 Runtime 接上去。第二課結(jié)束前我建議你真的想明白這幾個(gè)問題不用背定義。如果下面這些問題能夠不看文章自己解釋出來這一課基本就過了。模型回答我覺得應(yīng)該先查詢上海天氣。為什么人類很容易理解但不適合作為 Runtime 的接口模型返回{ action: get_weather }為什么這并不意味著天氣已經(jīng)被查詢?yōu)槭裁匆粋€(gè)輸出可以是Valid JSON卻依然不是Valid DecisionParser 和 Validator 分別解決了什么問題當(dāng)我們規(guī)定action ∈ { get_weather, query_order, ask_user, final_answer }實(shí)際上是在給 Agent 定義什么為什么讓模型返回query_order(order_id)通常比直接讓模型自由生成 SQL 更容易控制如果用戶只說幫我查天氣為什么ask_user本身也值得成為一個(gè) Action最后也是最重要的一個(gè)Structured Output 和 Tool Calling 到底差在哪一步如果最后這個(gè)問題真正想清楚了第三課基本已經(jīng)學(xué)會(huì)一半。最后把第二課壓縮成四句話第一句自然語言適合人與人交流但不是可靠的軟件協(xié)議。第二句Structured Output 不是“讓模型輸出 JSON”而是在 Model 和 Runtime 之間建立可驗(yàn)證的 Contract。第三句Schema 不只是定義數(shù)據(jù)格式它還在定義模型允許選擇的 Action Space。第四句Structured Output 只負(fù)責(zé)表達(dá) Decision真正把 Decision 變成 Action 的是 Runtime?，F(xiàn)在再回頭看我們整個(gè)系列的進(jìn)度第一課LLM ↓ Output第二課LLM ↓ Structured Decision下一課終于輪到LLM ↓ Structured Decision ↓ Runtime ↓ Tool ↓ Environment也就是下一課《Agent 原理三Tool Calling——模型根本沒有調(diào)用函數(shù)真正動(dòng)手的是 Runtime》到了第三課我們第一次真正執(zhí)行一個(gè) Tool。然后把 Tool 的返回結(jié)果重新交給模型。再下一步一個(gè)真正的 Agent Loop 就會(huì)自然長出來。你會(huì)發(fā)現(xiàn)我們從頭到尾都沒有“發(fā)明”Agent。只是每遇到一個(gè)解決不了的工程問題就不得不增加一個(gè)組件。最后回過頭時(shí)一個(gè) Agent 自己出現(xiàn)了。這也是這個(gè)系列真正想講清楚的東西。 Agent 原理（二）：別急著學(xué) Tool Calling，先搞懂 LLM 怎么變成程序真正能用的“接口”
第一課我們講了一件看起來很簡單但其實(shí)決定了整個(gè) Agent 技術(shù)棧的事情LLM 只會(huì)產(chǎn)生輸出它不會(huì)直接改變外部世界。你讓一個(gè)裸模型刪除 report.txt它可以回答好的report.txt 已刪除。甚至可以生成os.remove(report.txt)但只要外面沒有程序真正執(zhí)行os.remove()你的文件就還好好地躺在硬盤里。所以第一課最后我們把 Model 和 Runtime 分開了Model決定應(yīng)該做什么 Runtime真正把事情做掉到這里其實(shí)已經(jīng)很接近 Agent 了。但如果你真的開始自己寫代碼會(huì)立刻撞上第二個(gè)問題。而且這個(gè)問題比“怎么調(diào)用 Tool”更早出現(xiàn)。假設(shè)用戶說幫我查一下上海今天的天氣 看看下午要不要帶傘。模型判斷完之后回答我覺得這個(gè)問題最好先查一下上海今天的天氣。作為人你當(dāng)然看得懂。但現(xiàn)在不要站在人類的角度看這句話。站在代碼的角度看。你的程序拿到的其實(shí)只是response 我覺得這個(gè)問題最好先查一下上海今天的天氣。 然后呢程序怎么知道模型到底想干什么這就是第二課真正要解決的問題。人能聽懂的話不一定是一個(gè)好的軟件接口假設(shè)我們的 Runtime 現(xiàn)在有三個(gè)能力查詢天氣 查詢訂單 直接回答用戶那么模型每一次做完判斷之后程序真正關(guān)心的其實(shí)只有一件事你到底選擇了哪一個(gè)但模型偏偏特別擅長“說人話”。它可能說我需要先看看上海天氣。下一次可能說為了回答這個(gè)問題我需要獲取上海當(dāng)前的氣象信息。還可能說最好先確認(rèn)一下上海今天有沒有雨。換個(gè)模型也許直接變成Let me check the weather in Shanghai first.對人來說這四句話表達(dá)的是同一個(gè)意思。對程序來說這是四個(gè)完全不同的字符串。于是很多人第一次自己寫這種程序時(shí)會(huì)很自然地干一件事if 天氣 in response: get_weather()看起來居然還能跑。然后有一天模型回答我需要看看上海今天會(huì)不會(huì)下雨。沒有“天氣”兩個(gè)字。代碼失效。于是你補(bǔ)if 天氣 in response or 下雨 in response: get_weather()過幾天模型又回答先獲取一下當(dāng)?shù)貧庀笄闆r吧。于是你繼續(xù)補(bǔ)if ( 天氣 in response or 下雨 in response or 氣象 in response ): get_weather()如果再復(fù)雜一點(diǎn)你很快就會(huì)開始寫正則表達(dá)式。然后再給正則表達(dá)式打補(bǔ)丁。再給補(bǔ)丁打補(bǔ)丁。做到這里應(yīng)該已經(jīng)能感覺到哪里不對了。問題并不在于模型“不夠聰明”。真正的問題是我們正在拿自然語言當(dāng)軟件協(xié)議用。而自然語言恰恰是一個(gè)極度不穩(wěn)定的軟件協(xié)議。人類喜歡自然語言是因?yàn)槲覀兎浅Ｉ瞄L容忍模糊。程序恰恰相反。程序最喜歡的是字段叫什么是確定的。 類型是什么是確定的。 允許出現(xiàn)哪些值是確定的。 缺少字段怎么辦也是確定的。于是 Agent 工程里第一個(gè)非常自然的問題出現(xiàn)了能不能不要讓 Runtime 猜模型是什么意思而是讓模型直接按照程序約定的格式表達(dá)自己的決定這就是 Structured Output 真正要解決的問題。第一次關(guān)鍵轉(zhuǎn)變從“說一句話”變成“返回一個(gè)數(shù)據(jù)結(jié)構(gòu)”還是剛才的問題。用戶幫我查一下上海今天的天氣。以前模型返回我認(rèn)為應(yīng)該先查詢上海天氣?，F(xiàn)在我們要求模型返回{ action: get_weather, arguments: { city: Shanghai } }看起來只是換成了 JSON。但從軟件工程角度看事情已經(jīng)發(fā)生了本質(zhì)變化。以前 Runtime 拿到我認(rèn)為應(yīng)該先查詢上海天氣。它必須先理解一句自然語言。現(xiàn)在 Runtime 拿到decision[action]得到get_weather再讀取decision[arguments][city]得到ShanghaiRuntime 不需要理解中文。不需要 NLP。不需要關(guān)鍵詞。也不需要猜。這時(shí)候LLM 第一次從一個(gè)自然語言生成器開始變成了一個(gè)可以被軟件消費(fèi)的決策接口這才是 Structured Output 真正重要的地方。它解決的從來不是“讓輸出看起來整齊一點(diǎn)”。它解決的是怎樣把一個(gè)概率模型的輸出接進(jìn)一個(gè)確定性的軟件系統(tǒng)。這一點(diǎn)非常重要。因?yàn)楹竺嬲麄€(gè) Agent 都建立在這條橋上。但這里有一個(gè)坑會(huì)輸出 JSON不等于真正有了 Structured Output很多人學(xué)到這里會(huì)覺得事情已經(jīng)解決了。Prompt 里面寫一句請嚴(yán)格返回 JSON不要輸出其他內(nèi)容。然后告訴模型格式 { action: ..., arguments: {} }看起來很合理。但你真正跑幾次就會(huì)發(fā)現(xiàn)問題來了。模型可能返回當(dāng)然可以下面是結(jié)果 { action: get_weather, arguments: { city: Shanghai } }這時(shí)候json.loads(response)直接失敗。你說沒關(guān)系我再強(qiáng)調(diào)一次“只能返回 JSON”。然后下一次模型很聽話{ action: weather, arguments: { city: Shanghai } }這是合法 JSON。但 Runtime 根本沒有一個(gè)叫weather的 Action。Runtime 只有g(shù)et_weather再下一次{ action: get_weather, arguments: { city: 100 } }還是合法 JSON。但city為什么變成數(shù)字了甚至可能{ action: get_weather, arguments: {} }JSON 依然完全合法。但最關(guān)鍵的city不見了。這時(shí)候有一個(gè)很值得記住的區(qū)別Valid JSON ≠ Valid Decision這句話最好記住。JSON 解決的只是語法。但一個(gè)軟件接口真正需要的是契約。Schema 才是這里真正重要的東西假設(shè)我們希望模型返回{ action: get_weather, arguments: { city: Shanghai } }真正需要定義的其實(shí)遠(yuǎn)遠(yuǎn)不只是“大括號怎么寫”。我們需要告訴模型和 Runtime最外層必須是 object。 必須存在 action。 action 必須是 string。 action 只能取幾個(gè)指定值。 必須存在 arguments。 arguments 必須是 object。 如果 action 是 get_weather 那么 arguments 里必須有 city。 city 必須是 string。這就是 Schema 在干的事情。例如我們可以表達(dá)成類似這樣的約束{ type: object, properties: { action: { type: string, enum: [ get_weather, query_order, final_answer ] }, arguments: { type: object } }, required: [ action, arguments ] }具體以后你用 JSON Schema、類型系統(tǒng)還是某個(gè)模型 SDK 提供的 Structured Output API并不是這一課最值得記住的事情。真正重要的是腦子里要建立一個(gè)概念Schema 是 Model 和 Runtime 之間的 Contract。Runtime 相當(dāng)于在告訴模型你可以負(fù)責(zé)判斷。 但如果你希望軟件理解你的判斷 請按照這個(gè)協(xié)議說。這就是一個(gè)非常標(biāo)準(zhǔn)的軟件工程思想。只不過協(xié)議的一端不再是另一個(gè)確定性的服務(wù)。而是一個(gè) LLM。第二個(gè)關(guān)鍵轉(zhuǎn)變我們實(shí)際上正在限制模型的“動(dòng)作空間”這里有一個(gè)我認(rèn)為比“學(xué)會(huì) JSON Schema”重要得多的理解。假設(shè)我們告訴模型action 只能是 get_weather query_order final_answer這意味著什么意味著模型不能突然自己發(fā)明一個(gè)search_weather_from_google也不能發(fā)明open_browser更不能突然來一個(gè)delete_database從 Runtime 的角度我們實(shí)際上定義了Action Space { get_weather, query_order, final_answer }這個(gè)概念特別重要。因?yàn)榈竭@里L(fēng)LM 已經(jīng)不再只是“根據(jù)上下文繼續(xù)生成一段文字”從 Agent Engineering 的視角我們可以開始換一種方式理解它給定當(dāng)前 Context ↓ 模型判斷當(dāng)前應(yīng)該做什么 ↓ 從允許的 Action Space 里選擇一個(gè) Action如果寫得更抽象一點(diǎn)Context / State ↓ LLM ↓ Choose Action這已經(jīng)開始非常像 Agent 了。而且你會(huì)發(fā)現(xiàn)Schema 不只是定義數(shù)據(jù)格式。它還在定義這個(gè) Agent 到底被允許做出哪些類型的決定。這是這一課非常重要的一個(gè)“恍然大悟”。Schema 設(shè)計(jì)本身就是 Agent 設(shè)計(jì)我們繼續(xù)往下推。最開始只有一個(gè)動(dòng)作get_weather所以很簡單{ action: get_weather, arguments: { city: Shanghai } }后來系統(tǒng)又增加一個(gè)能力query_order它需要的參數(shù)不是city而是order_id于是{ action: query_order, arguments: { order_id: PO-10086 } }再后來增加search_web它需要query于是{ action: search_web, arguments: { query: Agent Memory } }到這里你會(huì)慢慢看到一個(gè)結(jié)構(gòu)出現(xiàn)了Decision │ ├── action │ └── argumentsaction回答我準(zhǔn)備做什么arguments回答完成這個(gè)動(dòng)作需要什么參數(shù)這已經(jīng)和函數(shù)調(diào)用非常像了。例如 Pythonget_weather(cityShanghai)和結(jié)構(gòu)化 Decision{ action: get_weather, arguments: { city: Shanghai } }兩者之間幾乎已經(jīng)可以一一對應(yīng)。注意這個(gè)時(shí)候我們?nèi)匀粵]有執(zhí)行函數(shù)。但是 Model 和 Runtime 之間已經(jīng)建立好了“如何描述一個(gè)函數(shù)調(diào)用”的語言。這就是為什么 Structured Output 應(yīng)該放在 Tool Calling 前面講。否則你第一次看到 Tool Calling 的時(shí)候很容易誤以為模型里面有一個(gè)什么神秘的函數(shù)執(zhí)行系統(tǒng)。其實(shí)完全沒有必要這么理解。把前面的東西一步一步推出來以后你會(huì)發(fā)現(xiàn)Tool Calling 馬上就要變得非常樸素了。到這里先停一下模型還是沒有調(diào)用任何東西這個(gè)邊界必須再強(qiáng)調(diào)一次。模型返回{ action: get_weather, arguments: { city: Shanghai } }請問上海天氣查了嗎沒有。一點(diǎn)都沒有?，F(xiàn)在真實(shí)發(fā)生的事情仍然只有Context ↓ LLM ↓ Tokens ↓ Structured Data模型只是用一種程序容易理解的方式表達(dá)“我認(rèn)為下一步應(yīng)該查詢上海天氣?！币郧八弥形谋磉_(dá)。現(xiàn)在它用結(jié)構(gòu)化數(shù)據(jù)表達(dá)。本質(zhì)沒有變化這仍然只是 Decision。真正的天氣查詢必須等 Runtime 做get_weather(cityShanghai)才會(huì)發(fā)生。所以這里可以建立一個(gè)以后非常有用的邊界Structured Output 如何表達(dá) Decision Tool Execution 如何執(zhí)行 Action這兩件事情不要混。一旦混了你后面學(xué) Tool Calling、MCP、Agent Loop 時(shí)會(huì)越來越亂。我們現(xiàn)在真的寫一個(gè)02_structured_output.py這一課仍然不要 LangChain。不要 LangGraph。也不要任何 Agent Framework。我們的項(xiàng)目繼續(xù)保持agent-from-zero/ │ ├── 01_llm.py └── 02_structured_output.py第一課User ↓ LLM ↓ Text這一課只增加一件東西User ↓ LLM ↓ Structured Decision ↓ Validation我們的目標(biāo)非?？酥撇皇亲?Agent。只是讓模型學(xué)會(huì)輸出 Runtime 能可靠理解的 Decision。假設(shè)系統(tǒng)目前允許四種決定get_weather query_order ask_user final_answer為什么多了一個(gè)ask_user等一下就會(huì)知道。我們先約定一個(gè)統(tǒng)一格式{ action: ..., arguments: {} }例如{ action: get_weather, arguments: { city: Shanghai } }或者{ action: query_order, arguments: { order_id: PO-10086 } }程序拿到模型返回之后第一件事不是執(zhí)行。而是import json def parse_decision(raw): return json.loads(raw)這是 Parser。它只解決一個(gè)問題模型返回的東西 能不能被解析成 JSON例如{ action: get_weather, arguments: { city: Shanghai } }可以。而好的我建議查詢天氣。不可以。但只有 Parser 遠(yuǎn)遠(yuǎn)不夠。我們還需要 Validator。比如ALLOWED_ACTIONS { get_weather, query_order, ask_user, final_answer, } def validate_decision(decision): if action not in decision: raise ValueError(missing action) if arguments not in decision: raise ValueError(missing arguments) if decision[action] not in ALLOWED_ACTIONS: raise ValueError(unknown action) if not isinstance(decision[arguments], dict): raise ValueError(arguments must be an object) return decision現(xiàn)在raw llm(messages) decision parse_decision(raw) decision validate_decision(decision)先不用糾結(jié)llm()具體是哪一家 API。我們現(xiàn)在研究的是結(jié)構(gòu)。這幾行代碼其實(shí)已經(jīng)把一個(gè)非常重要的東西拆出來了Model Output ↓ Parse ↓ Validate ↓ Decision以后做大型 Agent 時(shí)你會(huì)發(fā)現(xiàn)這幾層依然存在。只不過實(shí)現(xiàn)得復(fù)雜得多。Parser 和 Validator千萬不要混成一件事這個(gè)區(qū)別值得專門講一下。假設(shè)模型輸出{ action: destroy_planet, arguments: {} }這是合法 JSON 嗎當(dāng)然是。所以ParserPASS但這是我們允許的 Decision 嗎不是。因?yàn)閐estroy_planet根本不屬于我們的 Action Space。所以ValidatorFAIL這就是為什么Valid JSON ≠ Valid Decision再比如{ action: get_weather, arguments: {} }JSON 完全正確。Action 也存在。但get_weather明明需要city。所以更嚴(yán)格的 Validator 還應(yīng)該檢查if decision[action] get_weather: if city not in decision[arguments]: raise ValueError(get_weather requires city)這時(shí)候你開始進(jìn)入真正的軟件接口設(shè)計(jì)了。你不是在問“模型有沒有大概理解我的意思”你是在問“這個(gè)輸出是否滿足系統(tǒng)契約”這兩個(gè)問題完全不是一個(gè)層次。一個(gè)特別值得做的實(shí)驗(yàn)故意不給模型足夠信息現(xiàn)在用戶說幫我查一下天氣。注意。沒有城市。如果你的 Schema 只有g(shù)et_weather final_answer模型會(huì)陷入一個(gè)很尷尬的狀態(tài)。它想調(diào)用get_weather。但參數(shù)不完整。怎么辦一個(gè)非常自然的解決辦法是增加ask_user于是 Action Space 變成get_weather query_order ask_user final_answer模型可以返回{ action: ask_user, arguments: { question: 你想查詢哪個(gè)城市的天氣 } }這個(gè)例子非常值得反復(fù)琢磨。因?yàn)檫@里第一次可以清楚地看到我們怎樣設(shè)計(jì) Schema會(huì)直接決定 Agent 能采取什么行為。如果沒有ask_user模型沒有一種正式方式表達(dá)“信息不夠我需要問用戶?！痹黾觓sk_user以后這種行為突然成為了系統(tǒng)允許的一等 Action。也就是說Schema 并不只是描述輸出長什么樣它實(shí)際上參與定義 Agent 的能力邊界。這件事到了復(fù)雜 Agent 里會(huì)越來越明顯。再看一個(gè)企業(yè)場景你會(huì)更容易理解為什么這件事重要假設(shè)以后我們做一個(gè)企業(yè)內(nèi)部 Agent。用戶說幫我查一下 PO-20260807-001 的狀態(tài)。一種設(shè)計(jì)是讓模型直接生成 SQL{ sql: SELECT * FROM orders WHERE id PO-20260807-001 }看起來很靈活。但是這種設(shè)計(jì)很快會(huì)帶來另外一個(gè)問題為什么模型一定會(huì)生成SELECT它也可能生成DELETE FROM orders ...甚至生成一段你完全沒有預(yù)料到的 SQL。于是更合理的設(shè)計(jì)通常不是讓 LLM 自由創(chuàng)造底層操作而是 Runtime 先定義安全的高層能力query_order模型只負(fù)責(zé){ action: query_order, arguments: { order_id: PO-20260807-001 } }真正的 SQLSELECT ...由 Runtime 內(nèi)部自己決定。這其實(shí)延續(xù)了第一課那個(gè)非常重要的思想Model 決定 What Runtime 控制 How模型可以判斷我要查詢這個(gè)訂單但數(shù)據(jù)庫應(yīng)該怎么連、SQL 怎么寫、權(quán)限怎么控制、哪些字段能返回不應(yīng)該默認(rèn)全部交給模型自由發(fā)揮。所以 Structured Output 表面是在講輸出格式。繼續(xù)往下看你會(huì)發(fā)現(xiàn)它已經(jīng)開始碰到權(quán)限邊界 API 設(shè)計(jì) 安全邊界 系統(tǒng)職責(zé)劃分這才是它真正有價(jià)值的地方。為什么我說 Structured Output 是 Model 和 Runtime 的“邊界協(xié)議”到這里我們終于可以把整個(gè)結(jié)構(gòu)畫完整。第一課只有Context ↓ LLM ↓ Output第二課變成Context ↓ LLM ↓ Structured Output ↓ Parser ↓ Validator ↓ Decision再往下未來才會(huì)是Decision ↓ Runtime ↓ Tool ↓ Environment所以 Structured Output 恰好站在一個(gè)非常特殊的位置概率世界 │ LLM │ ↓ Structured Output │ ───────────┼─────────── Model / Runtime Boundary ───────────┼─────────── │ ↓ Validator │ Runtime │ Tool │ Environment 確定性世界上面是概率模型。下面是傳統(tǒng)軟件系統(tǒng)。中間必須有一個(gè)雙方都能理解的 Contract。否則下面的軟件永遠(yuǎn)在猜模型剛才那句話到底什么意思所以如果一定要用一句話總結(jié)這一課我更喜歡這樣說Structured Output 的真正價(jià)值是把 LLM 的概率性輸出壓縮成軟件系統(tǒng)可以驗(yàn)證和消費(fèi)的確定性接口。這比“讓模型輸出 JSON”準(zhǔn)確得多。還有一個(gè)很重要的原則Schema 不是越復(fù)雜越好當(dāng)大家第一次意識到 Schema 可以控制模型輸出之后很容易開始設(shè)計(jì)這種東西{ thought: ..., reasoning: ..., analysis: ..., confidence: 0.87, intent: ..., action: ..., arguments: {}, explanation: ..., summary: ... }看上去信息特別豐富。但先問一個(gè)問題Runtime 真正需要什么如果 Runtime 最終只消費(fèi)action arguments那么其他字段為什么一定要存在接口設(shè)計(jì)有一個(gè)非常樸素的原則只暴露真正需要暴露的東西。Structured Output 同樣如此。你不是在試圖把模型所有“思考”全部結(jié)構(gòu)化而是在定義軟件下一步真正需要消費(fèi)什么數(shù)據(jù)這兩個(gè)目標(biāo)差別很大。好的 Schema 往往不是最大的 Schema。而是足夠表達(dá)決策 足夠驗(yàn)證 沒有多余耦合這也會(huì)成為后面設(shè)計(jì) Tool Schema 時(shí)非常重要的原則。到這里你其實(shí)已經(jīng)摸到 Tool Calling 的本質(zhì)了現(xiàn)在再看{ action: get_weather, arguments: { city: Shanghai } }有沒有一種非常熟悉的感覺它其實(shí)已經(jīng)長得很像get_weather(cityShanghai)差的只剩下一步到底誰把前面的數(shù)據(jù)結(jié)構(gòu)變成后面的真實(shí)函數(shù)執(zhí)行答案當(dāng)然不是模型。而是 Runtime。也就是說下一課我們只需要繼續(xù)增加一層Structured Decision ↓ Runtime ↓ 根據(jù) action 找到函數(shù) ↓ 傳入 arguments ↓ 真正執(zhí)行例如概念上tools { get_weather: get_weather, query_order: query_order, }然后tool tools[decision[action]] result tool( **decision[arguments] )這時(shí)候才發(fā)生真正的Action而今天整整一課我們只解決Decision 應(yīng)該怎樣被可靠地表達(dá)這個(gè)順序非常重要。因?yàn)橐坏┻@層理解了下一課所謂的 Tool Calling 會(huì)突然祛魅。你會(huì)發(fā)現(xiàn)它并不是LLM 神奇地?fù)碛辛苏{(diào)用函數(shù)的能力而是Model 產(chǎn)生一個(gè)符合協(xié)議的 Tool Decision ↓ Runtime 解釋這個(gè) Decision ↓ 真正執(zhí)行函數(shù)而已。第二課學(xué)到這里應(yīng)該形成一個(gè)新的腦內(nèi)模型第一課結(jié)束時(shí)我們腦子里的 LLM 是LLM 根據(jù) Context 生成 Output第二課結(jié)束之后應(yīng)該再多一層理解LLM 可以根據(jù) Context 生成符合特定 Contract 的 Decision于是 Agent 的結(jié)構(gòu)開始慢慢長出來User ↓ Context ↓ LLM ↓ Structured Decision ↓ Parser / Validator注意。目前還不是 Agent。因?yàn)槲覀兩踔吝€沒有真正執(zhí)行任何 Tool。但一個(gè)非常重要的地基已經(jīng)完成了Model 和 Runtime 終于有辦法可靠通信了。下一課我們只需要把 Runtime 接上去。第二課結(jié)束前我建議你真的想明白這幾個(gè)問題不用背定義。如果下面這些問題能夠不看文章自己解釋出來這一課基本就過了。模型回答我覺得應(yīng)該先查詢上海天氣。為什么人類很容易理解但不適合作為 Runtime 的接口模型返回{ action: get_weather }為什么這并不意味著天氣已經(jīng)被查詢?yōu)槭裁匆粋€(gè)輸出可以是Valid JSON卻依然不是Valid DecisionParser 和 Validator 分別解決了什么問題當(dāng)我們規(guī)定action ∈ { get_weather, query_order, ask_user, final_answer }實(shí)際上是在給 Agent 定義什么為什么讓模型返回query_order(order_id)通常比直接讓模型自由生成 SQL 更容易控制如果用戶只說幫我查天氣為什么ask_user本身也值得成為一個(gè) Action最后也是最重要的一個(gè)Structured Output 和 Tool Calling 到底差在哪一步如果最后這個(gè)問題真正想清楚了第三課基本已經(jīng)學(xué)會(huì)一半。最后把第二課壓縮成四句話第一句自然語言適合人與人交流但不是可靠的軟件協(xié)議。第二句Structured Output 不是“讓模型輸出 JSON”而是在 Model 和 Runtime 之間建立可驗(yàn)證的 Contract。第三句Schema 不只是定義數(shù)據(jù)格式它還在定義模型允許選擇的 Action Space。第四句Structured Output 只負(fù)責(zé)表達(dá) Decision真正把 Decision 變成 Action 的是 Runtime?，F(xiàn)在再回頭看我們整個(gè)系列的進(jìn)度第一課LLM ↓ Output第二課LLM ↓ Structured Decision下一課終于輪到LLM ↓ Structured Decision ↓ Runtime ↓ Tool ↓ Environment也就是下一課《Agent 原理三Tool Calling——模型根本沒有調(diào)用函數(shù)真正動(dòng)手的是 Runtime》到了第三課我們第一次真正執(zhí)行一個(gè) Tool。然后把 Tool 的返回結(jié)果重新交給模型。再下一步一個(gè)真正的 Agent Loop 就會(huì)自然長出來。你會(huì)發(fā)現(xiàn)我們從頭到尾都沒有“發(fā)明”Agent。只是每遇到一個(gè)解決不了的工程問題就不得不增加一個(gè)組件。最后回過頭時(shí)一個(gè) Agent 自己出現(xiàn)了。這也是這個(gè)系列真正想講清楚的東西。