Agent工具開髮指南：從設計到最佳化

一、簡介

想像一下你正在組裝一個超級智慧的機器人管家（特務）。這個機器人需要各種工具來幫助你完成任務──就像哆啦A夢的4D口袋一樣。本文將教您如何創造這些強大的工具，讓您的AI管家更加得力和有效率。

2. 兩個核心工具設計模式

2.1 同步工具：即時回應模式

考慮使用自助咖啡機：

1. 插入硬幣並按下「美式咖啡」按鈕
2. 稍等幾秒
3. 咖啡流出，可以喝了

這是典型的同步工具模式。代理呼叫該工具並等待立即結果 - 快速而簡單。

class WeatherTool(BaseTool):
    """Weather Query Tool - Synchronous Mode"""
    async def execute(self, city: str) -> dict:
        # Simple and direct like pressing a coffee machine button
        weather_data = await self.weather_api.get_current(city)
        return {
            "status": "success",
            "data": {
                "temperature": weather_data.temp,
                "humidity": weather_data.humidity,
                "description": weather_data.desc
            }
        }

用例：

• 快速查詢：天氣、匯率、簡單計算
• 簡單的操作：傳送訊息、切換控制
• 即時回饋：驗證碼查詢、餘額查詢

2.2 非同步工具：任務追蹤模式

想像一下透過外帶應用程式訂購食物：

1. 下單後，APP會給你一個訂單號碼
2. 您可以隨時查看訂單狀態
3. 配送完成後APP會通知您

這就是非同步工具的工作原理，非常適合需要較長時間處理的任務。

class DocumentAnalysisTool(BaseTool):
    """Document Analysis Tool - Asynchronous Mode"""

    async def start_task(self, file_path: str) -> str:
        # Like placing a food delivery order, returns a task ID
        task_id = str(uuid.uuid4())
        await self.task_queue.put({
            "task_id": task_id,
            "file_path": file_path,
            "status": "processing"
        })
        return task_id

    async def get_status(self, task_id: str) -> dict:
        # Like checking food delivery status
        task = await self.task_store.get(task_id)
        return {
            "task_id": task_id,
            "status": task["status"],
            "progress": task.get("progress", 0),
            "result": task.get("result", None)
        }

用例：

• 耗時操作：大檔案處理、資料分析
• 多步驟任務：影片渲染、報表產生
• 需要進度追蹤：模型訓練、批次

3. 工具介面標準化：建立通用規範

就像所有電器都遵循統一的插座標準一樣，我們的工具介面也需要標準化。這可確保所有工具與代理商完美搭配。

3.1 工具說明規格

想像一下寫一份產品手冊，你需要清楚告訴使用者：

• 該工具的作用
• 需要什麼參數
• 會回傳什麼結果

from pydantic import BaseModel, Field

class ToolSchema(BaseModel):
    """Tool Manual Template"""
    name: str = Field(..., description="Tool name")
    description: str = Field(..., description="Tool purpose description")
    parameters: dict = Field(..., description="Required parameters")
    required: List[str] = Field(default_factory=list, description="Required parameters")

    class Config:
        schema_extra = {
            "example": {
                "name": "Weather Query",
                "description": "Query weather information for specified city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {
                            "type": "string",
                            "description": "City name"
                        }
                    }
                },
                "required": ["city"]
            }
        }

3.2 統一基類

就像所有電器都需要電源開關和電源介面一樣，所有工具都需要遵循基本規格：

class BaseTool(ABC):
    """Base template for all tools"""

    @abstractmethod
    def get_schema(self) -> ToolSchema:
        """Tool manual"""
        pass

    def validate_input(self, params: Dict) -> Dict:
        """Parameter check, like a fuse in electrical appliances"""
        return ToolSchema(**params).dict()

    @abstractmethod
    async def execute(self, **kwargs) -> Dict:
        """Actual functionality execution"""
        pass

4. 錯誤處理：讓工具更可靠

就像家用電器需要防水、防震、過載保護一樣，工具也需要完善的保護機制。

4.1 錯誤分類及處理

想像一下處理快遞：

• 位址錯誤→參數錯誤
• 系統維護→服務暫時無法使用
• 快遞太忙→需要限制速率並重試

class WeatherTool(BaseTool):
    """Weather Query Tool - Synchronous Mode"""
    async def execute(self, city: str) -> dict:
        # Simple and direct like pressing a coffee machine button
        weather_data = await self.weather_api.get_current(city)
        return {
            "status": "success",
            "data": {
                "temperature": weather_data.temp,
                "humidity": weather_data.humidity,
                "description": weather_data.desc
            }
        }

4.2 重試機制

就像第一次嘗試失敗時自動安排第二次送貨：

class DocumentAnalysisTool(BaseTool):
    """Document Analysis Tool - Asynchronous Mode"""

    async def start_task(self, file_path: str) -> str:
        # Like placing a food delivery order, returns a task ID
        task_id = str(uuid.uuid4())
        await self.task_queue.put({
            "task_id": task_id,
            "file_path": file_path,
            "status": "processing"
        })
        return task_id

    async def get_status(self, task_id: str) -> dict:
        # Like checking food delivery status
        task = await self.task_store.get(task_id)
        return {
            "task_id": task_id,
            "status": task["status"],
            "progress": task.get("progress", 0),
            "result": task.get("result", None)
        }

5.性能優化：讓工具更有效率

5.1 快取機制

就像便利商店一樣，將熱門商品放在顯眼的位置：

from pydantic import BaseModel, Field

class ToolSchema(BaseModel):
    """Tool Manual Template"""
    name: str = Field(..., description="Tool name")
    description: str = Field(..., description="Tool purpose description")
    parameters: dict = Field(..., description="Required parameters")
    required: List[str] = Field(default_factory=list, description="Required parameters")

    class Config:
        schema_extra = {
            "example": {
                "name": "Weather Query",
                "description": "Query weather information for specified city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {
                            "type": "string",
                            "description": "City name"
                        }
                    }
                },
                "required": ["city"]
            }
        }

5.2 並發控制

像醫院的預約系統，控制同時服務的數量：

class BaseTool(ABC):
    """Base template for all tools"""

    @abstractmethod
    def get_schema(self) -> ToolSchema:
        """Tool manual"""
        pass

    def validate_input(self, params: Dict) -> Dict:
        """Parameter check, like a fuse in electrical appliances"""
        return ToolSchema(**params).dict()

    @abstractmethod
    async def execute(self, **kwargs) -> Dict:
        """Actual functionality execution"""
        pass

6. 測試和文件：確保工具可靠性

6.1 單元測試

例如新產品上市前的品質檢查：

class ToolError(Exception):
    """Tool error base class"""
    def __init__(self, message: str, error_code: str, retry_after: Optional[int] = None):
        self.message = message
        self.error_code = error_code
        self.retry_after = retry_after

@error_handler
async def execute(self, **kwargs):
    try:
        # Execute specific operation
        result = await self._do_work(**kwargs)
        return {"status": "success", "data": result}
    except ValidationError:
        # Parameter error, like wrong address
        return {"status": "error", "code": "INVALID_PARAMS"}
    except RateLimitError as e:
        # Need rate limiting, like courier too busy
        return {
            "status": "error", 
            "code": "RATE_LIMIT",
            "retry_after": e.retry_after
        }

6.2 文檔標準

就像寫一份詳細且清楚的產品手冊：

class RetryableTool(BaseTool):
    @retry(
        stop=stop_after_attempt(3),  # Maximum 3 retries
        wait=wait_exponential(multiplier=1, min=4, max=10)  # Increasing wait time
    )
    async def execute_with_retry(self, **kwargs):
        return await self.execute(**kwargs)

七、總結

開發好的代理工具就像製作一個完美的工具箱：

1. 正確的工具分類 - 同步/非同步各有其用途
2. 標準化介面-方便統一管理
3. 保護機制-處理各種異常
4. 追求效率－需要時緩存，需要時限速
5. 品質焦點 - 徹底的測試，清晰的文件

記住：好的工具可以讓 Agent 的效率加倍，而差的工具則會處處限制 Agent。

以上是Agent工具開髮指南：從設計到最佳化的詳細內容。更多資訊請關注PHP中文網其他相關文章！