工具設計:agent 好壞的第一決定因素

第一版:直覺設計(有問題)

假設任務:「掃描 ./data 目錄,找出所有 .log 檔,把超過 7 天的刪掉,把最新的彙整成摘要。」

import anthropic
import os
import json
from datetime import datetime, timedelta

client = anthropic.Anthropic()

# 第一版工具定義(有問題)
tools_v1 = [
    {
        "name": "list_files",
        "description": "列出目錄內的檔案",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"}
            },
            "required": ["path"]
        }
    },
    {
        "name": "delete_file",
        "description": "刪除檔案",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"}
            },
            "required": ["path"]
        }
    },
    {
        "name": "read_file",
        "description": "讀取檔案",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string"}
            },
            "required": ["path"]
        }
    }
]

這個版本有三個問題:

1. list_files 沒說回傳格式,沒說會不會含子目錄
2. delete_file 是危險操作,沒有 dry_run,沒有確認機制
3. read_file 沒說超大檔案怎麼處理,沒說過濾條件

跑起來會怎樣?agent 可能直接開始刪檔案,不先確認;也可能把 1 GB 的 log 塞進 context,token 爆掉。

第二版:加上完整 description 和錯誤處理

import os
import glob
from pathlib import Path
from datetime import datetime
import json

# 工具定義 v2
tools_v2 = [
    {
        "name": "list_directory",
        "description": (
            "列出指定目錄中的檔案與子目錄。"
            "可選擇依副檔名過濾(例如 '*.log')。"
            "回傳每個項目的名稱、大小(bytes)、最後修改時間(ISO 8601)、是否為目錄。"
            "不遞迴進入子目錄,只列出直屬項目。"
            "如需遞迴搜尋請用 find_files 工具。"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "目標目錄路徑,例如 './data' 或 '/tmp/logs'"
                },
                "pattern": {
                    "type": "string",
                    "description": "glob 過濾樣式,例如 '*.log'、'*.txt'。省略則列出全部"
                }
            },
            "required": ["path"]
        }
    },
    {
        "name": "read_file",
        "description": (
            "讀取文字檔內容,以 UTF-8 字串回傳。"
            "適用於 .txt/.log/.json/.md/.py 等文字格式。"
            "大於 100KB 的檔案只回傳前 50,000 字元並標記 truncated=true。"
            "需要讀取特定行範圍請傳入 start_line 和 end_line。"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "檔案路徑"
                },
                "start_line": {
                    "type": "integer",
                    "description": "從第幾行開始讀(1-indexed),省略則從頭"
                },
                "end_line": {
                    "type": "integer",
                    "description": "讀到第幾行結束,省略則到尾"
                }
            },
            "required": ["path"]
        }
    },
    {
        "name": "delete_files",
        "description": (
            "刪除一或多個檔案。此操作不可逆。"
            "強烈建議先以 dry_run=true 確認影響範圍再設為 false 執行。"
            "dry_run=true 時只回傳「會被刪除的清單」,不執行刪除。"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "paths": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "要刪除的檔案路徑清單"
                },
                "dry_run": {
                    "type": "boolean",
                    "description": "true=預覽模式(不刪除),false=真實刪除。預設 true",
                    "default": True
                }
            },
            "required": ["paths"]
        }
    },
    {
        "name": "write_file",
        "description": (
            "將文字內容寫入檔案。若檔案已存在會覆蓋。"
            "若路徑的父目錄不存在會自動建立。"
            "回傳寫入的 byte 數。"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "目標檔案路徑"
                },
                "content": {
                    "type": "string",
                    "description": "要寫入的文字內容"
                }
            },
            "required": ["path", "content"]
        }
    }
]

實作工具執行函式

def execute_tool(tool_name: str, tool_input: dict) -> dict:
    """統一的工具執行入口,含錯誤處理"""
    
    if tool_name == "list_directory":
        path = tool_input["path"]
        pattern = tool_input.get("pattern", "*")
        
        if not os.path.exists(path):
            return {
                "success": False,
                "error": "PATH_NOT_FOUND",
                "message": f"目錄不存在:{path}",
                "hint": "請確認路徑是否正確,或用 write_file 先建立所需結構"
            }
        
        if not os.path.isdir(path):
            return {
                "success": False,
                "error": "NOT_A_DIRECTORY",
                "message": f"{path} 是檔案而非目錄",
                "hint": "若要列出父目錄,請傳入父目錄路徑"
            }
        
        items = []
        for entry in Path(path).glob(pattern):
            stat = entry.stat()
            items.append({
                "name": entry.name,
                "path": str(entry),
                "is_dir": entry.is_dir(),
                "size_bytes": stat.st_size,
                "modified_at": datetime.fromtimestamp(stat.st_mtime).isoformat()
            })
        
        return {"success": True, "items": items, "count": len(items)}
    
    elif tool_name == "read_file":
        path = tool_input["path"]
        start_line = tool_input.get("start_line")
        end_line = tool_input.get("end_line")
        
        if not os.path.exists(path):
            parent = os.path.dirname(path)
            nearby = []
            if os.path.exists(parent):
                nearby = [f.name for f in Path(parent).iterdir()][:5]
            return {
                "success": False,
                "error": "FILE_NOT_FOUND",
                "message": f"找不到檔案:{path}",
                "hint": f"父目錄 {parent} 中有:{nearby}" if nearby else f"父目錄 {parent} 不存在"
            }
        
        try:
            with open(path, 'r', encoding='utf-8') as f:
                lines = f.readlines()
            
            # 行範圍篩選
            if start_line or end_line:
                s = (start_line or 1) - 1
                e = end_line or len(lines)
                lines = lines[s:e]
            
            content = "".join(lines)
            truncated = False
            
            if len(content.encode('utf-8')) > 100_000:
                content = content[:50_000]
                truncated = True
            
            return {
                "success": True,
                "content": content,
                "total_lines": len(lines),
                "truncated": truncated
            }
        except UnicodeDecodeError:
            return {
                "success": False,
                "error": "ENCODING_ERROR",
                "message": f"無法以 UTF-8 解讀:{path}",
                "hint": "此可能是二進位檔案,不適合 read_file"
            }
    
    elif tool_name == "delete_files":
        paths = tool_input["paths"]
        dry_run = tool_input.get("dry_run", True)  # 預設安全模式
        
        results = []
        for p in paths:
            if os.path.exists(p):
                results.append({
                    "path": p,
                    "size_bytes": os.path.getsize(p),
                    "would_delete" if dry_run else "deleted": True
                })
                if not dry_run:
                    os.remove(p)
            else:
                results.append({"path": p, "error": "不存在"})
        
        return {
            "success": True,
            "dry_run": dry_run,
            "results": results,
            "message": (
                f"預覽:將刪除 {len(results)} 個檔案。確認後請以 dry_run=false 執行。"
                if dry_run else
                f"已刪除 {len(results)} 個檔案。"
            )
        }
    
    elif tool_name == "write_file":
        path = tool_input["path"]
        content = tool_input["content"]
        
        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
        with open(path, 'w', encoding='utf-8') as f:
            bytes_written = f.write(content)
        
        return {
            "success": True,
            "path": path,
            "bytes_written": len(content.encode('utf-8'))
        }
    
    return {"success": False, "error": "UNKNOWN_TOOL", "message": f"未知工具:{tool_name}"}

組裝 agent loop 並跑任務

def run_file_agent(task: str, tools: list) -> str:
    """簡單的 agent loop,含工具執行與安全攔截"""
    
    messages = [{"role": "user", "content": task}]
    
    system = """你是一個檔案管理 agent。
規則:
1. 刪除操作必須先用 dry_run=true 確認清單,輸出給使用者看
2. 確認影響超過 5 個檔案的操作前,先列出清單
3. 遇到錯誤時,根據 hint 修正後重試,最多重試 2 次
"""
    
    while True:
        response = client.messages.create(
            model="claude-opus-4-5",
            max_tokens=4096,
            system=system,
            tools=tools,
            messages=messages
        )
        
        # 沒有更多工具呼叫,任務完成
        if response.stop_reason == "end_turn":
            return response.content[0].text
        
        # 處理工具呼叫
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                print(f"  → 呼叫工具:{block.name}({json.dumps(block.input, ensure_ascii=False)})")
                result = execute_tool(block.name, block.input)
                print(f"    回傳:{json.dumps(result, ensure_ascii=False)[:200]}...")
                
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result, ensure_ascii=False)
                })
        
        # 把工具結果加回對話
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_results})

# 執行
task = """
掃描 ./data 目錄,找出所有 .log 檔:
1. 列出所有 .log 檔的名稱與修改時間
2. 找出超過 7 天沒有修改的 log,dry_run 給我看清單
3. 把最新的 3 個 log 的前 100 行讀出來,彙整摘要,寫到 ./output/log_summary.md
"""

result = run_file_agent(task, tools_v2)
print(result)