工具使用:AI 的手是怎麼長出來的

第 1 課結束時,你已經知道 Agent 是「會自己動手的 AI」——它不只回答問題,還能執行動作。但這個「動手」是怎麼發生的?純語言模型(LLM)本質上是一台文字預測機:你輸入問題,它輸出一段文字。就這樣。它不能開網頁、不能讀你電腦上的檔案、不能打電話給客服、也不能查今天的匯率。

那麼,為什麼你在用 Claude Code 時,它能直接讀你的程式碼、執行終端機指令、把結果寫回檔案?答案就在這一堂課的主題:工具使用(Tool Use),又叫 Function Calling。

這堂學什麼

• Tool Use 是什麼:語言模型本身不能動手,工具讓它真的能操作外部世界
• 一次 Agent 任務的幕後:決策 → 調工具 → 收結果 → 再決策,這個迴圈怎麼跑
• 為什麼 Agent 會用錯工具:工具說明寫得爛,AI 在產生第一個字之前就已做出錯誤決定
• 失敗重試機制:從死迴圈到自我反省(Reflexion),怎麼讓 Agent 不陷入無限迴圈
• 觀察實戰:用 Claude Code 執行一個多步驟任務,親眼看完整的工具呼叫 trace

觀念一:AI 只是嘴,工具才是手

想像語言模型是一個超強的顧問:他懂幾十種語言,能分析複雜合約、寫漂亮的行銷文案。但他只能說話和寫字——沒辦法直接打開你桌上那份文件,沒辦法幫你查銀行帳戶餘額,更沒辦法按鍵盤操作你的電腦。

工具(Tools) 就是替語言模型長出「手」的機制。開發者(或者 Claude Code 這類現成 Agent)事先定義好一批工具:每個工具有名字、一段說明「這個工具能做什麼」、以及它接受哪些參數(輸入)和回傳什麼(輸出)。

模型在收到你的任務後,會看著這份工具清單決定要不要呼叫某個工具、帶什麼參數進去。呼叫的動作不是模型自己執行的——模型只是輸出一段結構化的「工具呼叫請求」,實際的執行由外部系統(例如 Claude Code 的 runtime)完成,結果再回傳給模型。

舉個具體的例子。Claude Code 預設就帶著下面這批工具:

你每次叫 Claude Code「幫我讀一下這個檔案」,它不是憑空知道——它呼叫了 Read 工具,把回傳的檔案內容「讀進去」,才能繼續回答你。沒有工具,它只能說「我不知道你的檔案裡有什麼」。

這就是 Tool Use 最核心的白話版:模型負責決策,工具負責行動,結果再回饋給模型做下一輪決策。

觀念二:一次 Agent 任務的幕後拆解

現在你知道工具是什麼了。來看它在真實任務裡怎麼運作。以「幫我看這個 Python 檔有沒有語法錯誤,有的話修掉」為例,幕後發生的是一個決策迴圈:

第 1 輪:決策 → 呼叫 Read

Agent 收到任務後,先想:「我要修語法錯誤,得先知道檔案裡有什麼。」第一步呼叫 Read,帶上你指定的檔名作為參數。

第 2 輪:收結果 → 決策 → 呼叫 Bash

Read 把檔案內容回給 Agent。Agent 看了一眼,想:「縮排好像有問題,我再用 python -m py_compile 驗證一下。」於是呼叫 Bash。

第 3 輪:收結果 → 決策 → 呼叫 Edit

Bash 回傳了錯誤訊息:IndentationError 在第 12 行。Agent 知道要修哪裡了:呼叫 Edit,把正確的縮排寫進去。

第 4 輪:收結果 → 決策 → 呼叫 Bash → 結束

修完後 Agent 再跑一次 Bash 確認沒有錯誤,然後輸出:「已修復第 12 行的縮排問題,現在可以正常執行。」

整個流程跑了 4 輪,呼叫了 4 次工具。你只說了一句話,Agent 自己決定了工具的順序和參數。這就是「自主」的本質——它不是等你一步步下指令,而是自己規劃了一條路。

這個「思考 → 行動 → 觀察 → 再思考」的迴圈,學術上叫 ReAct 框架(Reason + Act)。幾乎所有現代 Agent 框架都是這個底層邏輯的延伸,包括你用到的 Claude Code、ChatGPT agent 模式、還有各種自動化 Agent 平台背後都跑這套機制。

觀念三:為什麼 Agent 會用錯工具

Agent 既然能自己決策,當然也能決策錯。而且在多步驟任務裡,選錯工具往往是最終答案出錯的頭號原因——一步走歪,後面每一步都跟著錯,錯誤還會層層放大。

常見的「用錯工具」有三種情境:

情境 A:工具說明語意模糊

你給 Agent 兩個工具:search_document(搜尋本機文件)和 search_web(搜尋網路)。如果兩個工具的說明都只寫「搜尋」兩個字,沒有說明各自的使用場合,Agent 在面對「搜尋最新的 Python 3.14 文件」這個任務時,很可能選錯。工具的 description(說明欄)是一份給模型看的「使用手冊」,寫得不清楚等於手冊殘缺。

情境 B:工具用對但參數填錯

Agent 決定要呼叫 Bash,但把指令組錯了——例如本來要跑 npm run test,組成了 npm run tests(多了一個 s)。工具呼叫本身成功,但參數錯誤。這種錯最難發現,因為 Agent 不一定會報錯,只是悄悄跑了一個不存在的指令。

情境 C:幻覺出一個不存在的工具

有些模型在工具清單裡沒有某個功能時,會自己「發明」一個工具名稱並嘗試呼叫。比如 Agent 想寄電子郵件,但你沒給它 email 工具,它卻呼叫了一個叫 send_email 的工具——這個工具根本不存在,必然失敗。

還有一個觀察特別有趣:模型往往在輸出第一個文字 token 之前,內部就已傾向要呼叫哪個工具。工具選擇不是「說著說著才決定」,而是推理很前期就大致定案。這告訴我們一件重要的事:工具的說明(description)若寫得清楚,錯誤率大幅降低;寫得模糊,Agent 從一開始就走歪了。

這個知識對不寫程式的你也有用:以後在任何 Agent 平台設定工具或自動化流程時,工具的描述欄位要認真填,不能只寫一兩個字交差。

觀念四:失敗重試——從死迴圈到自我反省

工具呼叫出錯了,Agent 怎麼辦?最直覺的做法是「重試」。但最原始的重試有一個災難性的 bug:

Tool execution failed: Error 429 - Rate limit exceeded
Retrying...
Tool execution failed: Error 429 - Rate limit exceeded
Retrying...
Tool execution failed: Error 429 - Rate limit exceeded
Retrying...
(無限迴圈,費用持續累積)

Agent 卡在一個重複失敗的迴圈裡,什麼問題都沒解決,但 API 費用一直在跑。這不是誇張——真實案例中有開發者的 Agent 在幾分鐘內把整月的 API 額度燒光,就是因為沒有設重試上限。

成熟的 Agent 系統對此有兩個保護機制:

機制 A:硬性迭代上限

不管發生什麼事,超過 N 次就停下來、報告失敗,讓人類接手。Claude Code 內建這個機制,你不需要自己設定,但當它說「已達到最大嘗試次數」時,你要知道它為什麼停。

機制 B:Reflexion(反省式重試)

每次失敗後,不是直接重試,而是先讓模型寫一段「自我反省」——「我上次失敗的原因是什麼?這次應該換什麼方式?」——把這段反省帶進下一輪的 context,再重試。這個方法效果遠好於盲目重試,因為它避免了「做一樣的事情,期待不同的結果」這個邏輯謬誤。

Reflexion 你不需要自己實作——Claude Code 等成熟工具已有內建版本。但你要知道它存在,這樣當 Agent 卡住一直重試時,你懂得判斷:是遇到真的環境問題要人工介入,還是只是需要給它更明確的提示來打破迴圈。

手把手實戰:親眼看 Agent 的工具呼叫 Trace

理論講完了。現在實際跑一個任務,把每一步的工具呼叫都看清楚。

def greet(name):
    message = "Hello, " + name
  print(message)   # 縮排故意弄錯:2 格而非 4 格

greet("Agent")

幫我看看 broken.py 這個檔案有沒有語法錯誤,有的話修掉,
修完再確認一次能正常執行。
過程中每一步你在做什麼、為什麼這樣做,都用繁體中文跟我說清楚。

我先讀取 broken.py 的內容,確認目前有什麼程式碼。
[Read: broken.py]

讀完了。第 3 行的 print 縮排只有 2 格,在 def 區塊內應該是 4 格。
我先用 python -m py_compile 正式確認錯誤位置。
[Bash: python -m py_compile broken.py]

確認了,輸出:
  File "broken.py", line 3
    print(message)
IndentationError: unindent does not match any outer indentation level

現在把第 3 行縮排從 2 格改成 4 格。
[Edit: broken.py]

改完了。再驗證一次程式能正常執行。
[Bash: python broken.py]

輸出:Hello, Agent
語法正確,執行成功。

查一下 Python 目前最新的穩定版本是哪個、發布日期是什麼時候,
然後在這個資料夾建立一個叫 python-notes.md 的檔案,把這個資訊記錄進去。
做每一步之前先告訴我你打算用哪個工具、為什麼。

我需要查詢 Python 最新版本,先用網路搜尋。
[WebSearch: Python latest stable version 2026]

搜尋到了:Python 3.14.x 是目前的穩定版本...
現在建立 python-notes.md 把資訊寫進去。
[Write: python-notes.md]

完成。

常見坑

坑 1:Agent 一直轉圈圈,什麼都沒輸出(或輸出一直在重複)

症狀:你給了任務,Claude Code 跑了好幾分鐘,工具一直被呼叫、結果一直回來,就是不給最終回答;或者你看到類似這樣的輸出:

讓我再確認一次...
[Bash: python broken.py]
讓我再確認一次...
[Bash: python broken.py]
讓我再確認一次...

三個常見原因:

• 任務沒有明確的終止條件:你說「整理這個資料夾的所有 Python 檔」,但沒說到什麼程度算整理好。Agent 不確定什麼時候停。解法:加上具體的完成標準,例如「幫我把所有 .py 的函式名稱列出來,整理成 functions.md,做完後直接輸出整份內容給我看」。
• 工具一直回傳錯誤,Agent 一直重試:參見坑 2。
• Context 被塞滿了:工具回傳的內容太多(例如讀了一個超大的 log 檔),塞滿了 context window,Agent 開始無法正常推理。解法:叫它「只讀最後 50 行」或「只列出函式名稱,不要讀整個檔案內容」。

坑 2:看到 Tool execution failed 或持續出現 Error 429

Tool execution failed: command not found: python

這是環境問題:你的電腦上沒安裝 Python,或者 PATH 設定不對。Agent 無法執行工具,不是它的錯——是工作環境需要先設定好。常見解法:確認你的電腦已安裝對應工具,或者在任務裡改叫 python3 而非 python。

Error 429: Too many requests. Please retry after 60 seconds.

速率限制:API 呼叫太頻繁,被暫時擋下來。在 Claude Code 裡遇到通常等幾秒就自動恢復;如果一直出現,代表 Agent 陷入了無限重試迴圈,要手動中斷(按 Ctrl+C),然後重新給一個更明確的任務。

坑 3:Agent 動了你沒叫它碰的檔案

你叫它「修這個 broken.py 的縮排」,它順手把整個資料夾的 Python 檔都格式化了一遍。打開 git diff 一看,六個檔案都被改過了。

這是工具使用最讓人不安的坑。原因是任務描述的範圍不夠清楚,Agent 「自行推斷」任務意圖時過度延伸。

解法分兩層:

• 短期:下任務時明確說「只動 broken.py 這一個檔案,不要動任何其他檔案」。
• 長期:理解 Agent 的授權邊界——給 Agent 的權限越精確越好,不要給「隨便用就好」的空白授權。這個主題是第 6 課「授權與安全」的核心。今天先記住一個原則:你不說清楚邊界,Agent 就自己畫邊界——而它畫的邊界不一定跟你想的一樣。

坑 4:Agent 說「執行成功」但結果根本是錯的

[Bash: python broken.py]
執行完成,輸出如預期。

但你自己跑一下,發現輸出跟期待的完全不同——或者壓根沒輸出任何東西。

這是「工具沒報錯,但答案錯了」的情境。Agent 只看工具有沒有噴 exit code 1 或 error 關鍵字;它不一定真的「讀懂」輸出的內容。

解法很簡單:告訴它「把工具的完整原始輸出直接貼給我看,不要自己詮釋成功或失敗」。加上這句之後,你就能自己對照輸出是不是符合預期,不用完全信任 Agent 的判斷。

作業

1. 觀察自己的第一條 trace:在 Claude Code 裡給它一個三步驟以上的任務(例如:建一個 Python 檔、在裡面寫一個計算 BMI 的函式、用 Bash 執行並驗證輸出正確)。任務最後加上「每一步做什麼、為什麼,都用繁體中文跟我說」。把你看到的工具呼叫順序記下來,對照這堂課的決策迴圈圖,確認自己能說出每一輪發生了什麼。

2. 刻意製造模糊任務,觀察差異:同一個任務,分別用模糊版和精確版各試一次。模糊版:「修這個檔」。精確版:「修 broken.py 的第 3 行縮排問題,只動這一行,不要動其他地方,修完把原始輸出貼給我看」。比較 Agent 的行為有什麼不同。

3. 觀察一次失敗:故意叫 Agent 執行一個不存在的指令:

幫我跑一下 `npm run nonexistent`,看看輸出什麼

觀察錯誤訊息長什麼樣、Agent 怎麼嘗試處理這個失敗、它最後停在哪裡。這個練習幫你建立「Agent 出錯時長什麼樣」的直覺,以後看到類似的 trace 就不會慌。

下一課預告

你現在搞懂了 Tool Use 的完整機制:工具是什麼、迴圈怎麼跑、為什麼會用錯、怎麼重試。但你一直在用的「Claude Code」到底是個什麼樣的 Agent?它的工具清單有哪些、怎麼設定它的行為邊界、如何讓它記住你的工作習慣?

第 3 課「現成 Agent 體驗:Claude Code 當你的代理」會帶你從零到一把 Claude Code 設定成真正的個人工作代理——從讀你的筆記、更新你的文件,到處理真實的多步驟業務任務。不寫程式,但你會完全看懂每一步在發生什麼。