一、簡(jiǎn)介

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

2. 兩個(gè)核心工具設(shè)計(jì)模式

2.1 同步工具：即時(shí)回應(yīng)模式

考慮使用自助咖啡機(jī)：

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

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

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
            }
        }

用例：

• 快速查詢(xún)：天氣、匯率、簡(jiǎn)單計(jì)算
• 簡(jiǎn)單的操作：傳送訊息、切換控制
• 即時(shí)回饋：驗(yàn)證碼查詢(xún)、餘額查詢(xún)

2.2 非同步工具：任務(wù)追蹤模式

想像一下透過(guò)外帶應(yīng)用程式訂購(gòu)食物：

1. 下單後，APP會(huì)給你一個(gè)訂單號(hào)碼
2. 您可以隨時(shí)查看訂單狀態(tài)
3. 配送完成後APP會(huì)通知您

這就是非同步工具的工作原理，非常適合需要較長(zhǎng)時(shí)間處理的任務(wù)。

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)
        }

用例：

• 耗時(shí)操作：大檔案處理、資料分析
• 多步驟任務(wù)：影片渲染、報(bào)表產(chǎn)生
• 需要進(jìn)度追蹤：模型訓(xùn)練、批次

3. 工具介面標(biāo)準(zhǔn)化：建立通用規(guī)範(fàn)

就像所有電器都遵循統(tǒng)一的插座標(biāo)準(zhǔn)一樣，我們的工具介面也需要標(biāo)準(zhǔn)化。這可確保所有工具與代理商完美搭配。

3.1 工具說(shuō)明規(guī)格

想像一下寫(xiě)一份產(chǎn)品手冊(cè)，你需要清楚告訴使用者：

• 該工具的作用
• 需要什麼參數(shù)
• 會(huì)回傳什麼結(jié)果

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 統(tǒng)一基類(lèi)

就像所有電器都需要電源開(kāi)關(guān)和電源介面一樣，所有工具都需要遵循基本規(guī)格：

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. 錯(cuò)誤處理：讓工具更可靠

就像家用電器需要防水、防震、過(guò)載保護(hù)一樣，工具也需要完善的保護(hù)機(jī)制。

4.1 錯(cuò)誤分類(lèi)及處理

想像一下處理快遞：

• 位址錯(cuò)誤→參數(shù)錯(cuò)誤
• 系統(tǒng)維護(hù)→服務(wù)暫時(shí)無(wú)法使用
• 快遞太忙→需要限制速率並重試

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 重試機(jī)制

就像第一次嘗試失敗時(shí)自動(dòng)安排第二次送貨：

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.性能優(yōu)化：讓工具更有效率

5.1 快取機(jī)制

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

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 並發(fā)控制

像醫(yī)院的預(yù)約系統(tǒng)，控制同時(shí)服務(wù)的數(shù)量：

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. 測(cè)試和文件：確保工具可靠性

6.1 單元測(cè)試

例如新產(chǎn)品上市前的品質(zhì)檢查：

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 文檔標(biāo)準(zhǔn)

就像寫(xiě)一份詳細(xì)且清楚的產(chǎn)品手冊(cè)：

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)

七、總結(jié)

開(kāi)發(fā)好的代理工具就像製作一個(gè)完美的工具箱：

1. 正確的工具分類(lèi) - 同步/非同步各有其用途
2. 標(biāo)準(zhǔn)化介面-方便統(tǒng)一管理
3. 保護(hù)機(jī)制-處理各種異常
4. 追求效率－需要時(shí)緩存，需要時(shí)限速
5. 品質(zhì)焦點(diǎn) - 徹底的測(cè)試，清晰的文件

記?。汉玫墓ぞ呖梢宰?Agent 的效率加倍，而差的工具則會(huì)處處限制 Agent。

以上是Agent工具開(kāi)髮指南：從設(shè)計(jì)到最佳化的詳細(xì)內(nèi)容。更多資訊請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！