一、簡介

想象一下你正在組裝一個超級智能的機器人管家（特工）。這個機器人需要各種工具來幫助你完成任務(wù)——就像哆啦A夢的4D口袋一樣。本文將教您如何創(chuàng)建這些強大的工具，讓您的AI管家更加得力和高效。

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

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

考慮使用自助咖啡機：

1. 插入硬幣并按“美式咖啡”按鈕
2. 稍等幾秒
3. 咖啡流出，可以喝了

這是典型的同步工具模式。代理調(diào)用該工具并等待立即結(jié)果 - 快速而簡單。

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

用例：

• 快速查詢：天氣、匯率、簡單計算
• 簡單的操作：發(fā)送消息、切換控件
• 實時反饋：驗證碼查詢、余額查詢

2.2 異步工具：任務(wù)跟蹤模式

想象一下通過外賣應(yīng)用程序訂購食物：

1. 下單后，APP會給你一個訂單號
2. 您可以隨時查看訂單狀態(tài)
3. 配送完成后APP會通知您

這就是異步工具的工作原理，非常適合需要較長時間處理的任務(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ù)據(jù)分析
• 多步驟任務(wù)：視頻渲染、報告生成
• 需要進(jìn)度跟蹤：模型訓(xùn)練、批處理

3. 工具接口標(biāo)準(zhǔn)化：建立通用規(guī)范

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

3.1 工具說明規(guī)格

想象一下寫一份產(chǎn)品手冊，你需要清楚地告訴用戶：

• 該工具的作用
• 需要什么參數(shù)
• 會返回什么結(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)一基類

就像所有電器都需要電源開關(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. 錯誤處理：讓工具更可靠

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

4.1 錯誤分類及處理

想象一下處理快遞：

• 地址錯誤→參數(shù)錯誤
• 系統(tǒng)維護(hù)→服務(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 重試機制

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

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 緩存機制

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

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)，控制同時服務(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. 測試和文檔：確保工具可靠性

6.1 單元測試

比如新產(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)

就像寫一份詳細(xì)清晰的產(chǎn)品手冊：

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

開發(fā)好的代理工具就像制作一個完美的工具箱：

1. 正確的工具分類 - 同步/異步各有其用途
2. 標(biāo)準(zhǔn)化接口-方便統(tǒng)一管理
3. 保護(hù)機制-處理各種異常
4. 追求效率——需要時緩存，需要時限速
5. 質(zhì)量焦點 - 徹底的測試，清晰的文檔

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

以上是Agent工具開發(fā)指南：從設(shè)計到優(yōu)化的詳細(xì)內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！