LangChain 教學：Tools（工具系統）—— PythonREPL、Requests、File Tools 等常用工具

簡介

在 LangChain 的生態系中，Tools（工具）扮演著讓大型語言模型（LLM）與外部世界互動的關鍵角色。沒有工具，LLM 只能在「封閉」的文字空間裡產生回應；有了工具，模型可以即時 執行程式碼、呼叫 API、讀寫檔案，從而完成更複雜、真實世界的任務。

本單元將聚焦於 PythonREPL、Requests、File Tools 三大常用工具，說明它們的設計理念、使用方式以及在實務專案中的應用。即使你是剛接觸 LangChain 的新手，也能在閱讀完本篇後，快速將這些工具整合到自己的聊天機器人或自動化流程中。

核心概念

1. LangChain 的 Tools 抽象

LangChain 把「工具」抽象為 BaseTool 類別的子類，主要有三個屬性：

屬性	說明
`name`	工具在 Prompt 中的辨識名稱，LLM 會根據此名稱呼叫工具。
`description`	給 LLM 的說明文字，告訴模型這個工具能做什麼、需要什麼參數。
`run(input: str) -> str`	真正執行工具的函式，接收文字輸入並回傳文字結果。

LLM 在產生回應時會先 思考（think）：需要什麼工具？接著 呼叫（call） 相對應的 run，最後把工具回傳的文字結果整合回對話中。

小技巧：在 Prompt 中加入工具的 description，可以大幅提升模型正確選擇工具的機率。

2. PythonREPL：即時執行 Python 程式碼

PythonREPL（Read‑Eval‑Print Loop）讓 LLM 在對話中直接寫、執行 Python 程式碼，並取得結果。它非常適合：

資料分析與快速原型（例如 Pandas、NumPy）
演算法驗證
產生動態文字（如 JSON、SQL）

2.1 基本使用

from langchain.tools import PythonREPLTool
from langchain.agents import initialize_agent, AgentType

# 建立 REPL 工具
python_tool = PythonREPLTool()

# 建立簡易 Agent（使用 OpenAI 的 gpt-3.5-turbo）
agent = initialize_agent(
    tools=[python_tool],
    llm=ChatOpenAI(model_name="gpt-3.5-turbo"),
    agent_type=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True,
)

# 測試詢問
response = agent.run("請計算 1~10 的平方和，並回傳結果")
print(response)

說明：initialize_agent 會自動把工具的 description 注入 Prompt，LLM 只要在思考階段說「我要使用 PythonREPL」就會觸發 run。

2.2 安全性考量

執行環境隔離：建議使用 Docker 或 sandboxed 的 Python 環境，防止惡意程式碼破壞主機。
資源限制：透過 timeout、memory_limit 參數限制執行時間與記憶體使用。

python_tool = PythonREPLTool(
    timeout=5,               # 最長 5 秒
    memory_limit="200MiB",   # 記憶體上限
    sandboxed=True           # 使用安全沙箱
)

3. RequestsTool：呼叫 HTTP API

RequestsTool 包裝了 Python 的 requests 套件，讓 LLM 能以自然語言描述要呼叫的 API，工具會自行組裝請求、處理回傳結果。

3.1 建立自訂 API 工具

from langchain.tools import BaseTool
import requests
import json

class WeatherAPI(BaseTool):
    name = "WeatherAPI"
    description = (
        "取得指定城市的即時天氣資訊。"
        "輸入必須是 JSON 格式，包含 `city` 欄位，例如 "
        "`{\"city\": \"Taipei\"}`。"
    )

    def _run(self, query: str) -> str:
        # 解析使用者輸入的 JSON
        payload = json.loads(query)
        city = payload["city"]
        # 呼叫公開天氣 API（此處僅示範）
        resp = requests.get(
            f"https://api.open-meteo.com/v1/forecast",
            params={"latitude": 25.033, "longitude": 121.565, "hourly": "temperature_2m"}
        )
        data = resp.json()
        # 只回傳當前溫度
        current_temp = data["hourly"]["temperature_2m"][0]
        return f"{city} 現在的氣溫是 {current_temp}°C"

# 把自訂工具放入 Agent
weather_tool = WeatherAPI()
agent = initialize_agent(
    tools=[weather_tool],
    llm=ChatOpenAI(model_name="gpt-4"),
    agent_type=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True,
)

print(agent.run("請告訴我台北現在的天氣"))

3.2 常見需求

需求	實作方式
GET 帶參數	使用 `params` 參數字典
POST JSON	`requests.post(url, json=data)`
授權 Header	加入 `headers={"Authorization": "Bearer xxx"}`
錯誤處理	捕捉 `requests.exceptions.RequestException`，回傳友善訊息

4. File Tools：讀寫本機或雲端檔案

LangChain 內建的 FileReadTool、FileWriteTool、FileSearchTool，讓 LLM 可以直接 讀取、寫入、搜尋 檔案內容。這對於：

知識庫建構（把文字檔匯入向量資料庫）
日誌分析（即時檢索錯誤訊息）
自動化報表產生（寫入 CSV、JSON）

4.1 讀取文字檔

from langchain.tools import FileReadTool

read_tool = FileReadTool()
content = read_tool.run("data/meeting_notes.txt")
print(content[:200])   # 只印出前 200 個字

4.2 寫入 JSON 檔

from langchain.tools import FileWriteTool
import json

write_tool = FileWriteTool()
data = {"name": "LangChain", "version": "0.1.0"}
json_str = json.dumps(data, ensure_ascii=False, indent=2)
write_tool.run({"file_path": "output/info.json", "content": json_str})

注意：FileWriteTool.run 接受字典型參數，必須包含 file_path 與 content（文字或二進位）。若要寫入二進位檔案（如圖片），請使用 base64 編碼後再寫入。

4.3 搜尋檔案（FileSearchTool）

from langchain.tools import FileSearchTool

search_tool = FileSearchTool()
# 在 data/ 目錄下搜尋包含關鍵字 "budget" 的檔案
result = search_tool.run({"directory": "data", "keyword": "budget"})
print(result)   # 回傳符合條件的檔案路徑清單

常見陷阱與最佳實踐

陷阱	說明	解決方案
工具名稱與描述不一致	LLM 依賴 `description` 判斷何時使用工具，若描述不清會導致錯誤呼叫。	確保 `name` 與 `description` 完全對應，並在 Prompt 中重申。
執行環境未隔離	直接在主機上執行 PythonREPL 可能會被惡意程式碼利用。	使用 Docker、`execnet` 或 `sandboxed=True`，限制資源。
API 金鑰外洩	把敏感金鑰硬寫在程式碼裡，LLM 產生的回應可能會回傳金鑰。	把金鑰放在環境變數或安全祕密管理服務，工具內部自行讀取。
檔案路徑注入	使用者輸入的檔案路徑若未檢查，可能讀取系統敏感檔案。	實作白名單或根目錄限制，只允許特定資料夾。
回傳結果過長	LLM 只能處理有限長度的文字，過大的檔案內容會被截斷。	只回傳摘要或前 N 行，必要時使用分段傳遞。

最佳實踐

明確的工具描述

"FileWriteTool: 用於寫入文字檔。參數 `file_path` 必須是相對路徑，`content` 為 UTF-8 編碼的文字。"

限制執行時間

python_tool = PythonREPLTool(timeout=3)   # 3 秒內完成

錯誤訊息友善化
在 run 方法裡捕捉例外，回傳「抱歉，我無法完成此操作，原因：...」的訊息，避免讓使用者看到堆疊追蹤。
日誌紀錄
每次工具被呼叫時，寫入 logs/tool_usage.log，方便事後除錯與安全稽核。
測試覆蓋
為每個自訂工具撰寫單元測試，確保在不同輸入下仍能正確回傳。

實際應用場景

場景	使用工具	為何適合
自動化財務報表	`FileReadTool` + `PythonREPL` + `FileWriteTool`	讀取 CSV、用 Pandas 計算、寫回新的報表。
即時天氣問答機器人	`RequestsTool`（自訂 WeatherAPI）	讓 LLM 直接取得外部天氣資料，回覆自然語言。
程式碼輔助 IDE	`PythonREPL` + `FileReadTool`	使用者在聊天框中寫程式碼，模型即時執行、回傳結果，並可讀取檔案作為範例。
文件搜尋與摘要	`FileSearchTool` + `PythonREPL`（使用 LangChain 的 LLM）	搜尋本地文件、把內容傳給 LLM 產生摘要，回傳給使用者。
資料清洗管線	`RequestsTool`（下載資料） + `PythonREPL`（清洗） + `FileWriteTool`（存檔）	完整的 ETL 流程全自動化。

總結

Tools 是 LangChain 讓 LLM 從「文字模型」升級為「可執行的智慧代理」的核心機制。透過 PythonREPL、RequestsTool、File Tools，開發者可以：

即時執行程式碼：快速驗證演算法、產生動態資料。
呼叫外部 API：把最新的網路資訊（天氣、股價、搜尋結果）帶入對話。
讀寫檔案：構建知識庫、產生報表、搜尋文件。

在實作時，務必注意 安全性（沙箱、資源限制）、清晰的描述（讓 LLM 正確選擇工具）以及 錯誤處理（提供友善回饋）。只要遵循上述最佳實踐，你就能把 LangChain 的工具系統活用於各種業務需求，打造出既智能又可靠的 AI 應用。

祝你玩得開心，開發出更多令人驚豔的 LangChain 作品！ 🚀