Panduan Pembangunan Alat Agen: Daripada Reka Bentuk kepada Pengoptimuman

1. Pengenalan

Bayangkan anda sedang memasang butler robot yang sangat pintar (Ejen). Robot ini memerlukan pelbagai alatan untuk membantu anda menyelesaikan tugasan - sama seperti poket 4D Doraemon. Artikel ini akan mengajar anda cara mencipta alatan berkuasa ini untuk menjadikan butler AI anda lebih berkebolehan dan cekap.

2. Dua Corak Reka Bentuk Alat Teras

2.1 Alat Segerak: Mod Respons Segera

Fikirkan untuk menggunakan mesin kopi layan diri:

1. Masukkan syiling dan tekan butang "Americano"
2. Tunggu selama beberapa saat
3. Kopi mengalir keluar, sedia untuk diminum

Ini ialah corak alat segerak biasa. Ejen memanggil alat dan menunggu keputusan segera - cepat dan mudah.

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

Kes penggunaan:

• Pertanyaan pantas: cuaca, kadar pertukaran, pengiraan mudah
• Operasi mudah: menghantar mesej, suis kawalan
• Maklum balas masa nyata: semakan kod pengesahan, pertanyaan baki

2.2 Alat Asynchronous: Mod Penjejakan Tugas

Bayangkan memesan makanan melalui APP penghantaran:

1. Selepas membuat pesanan, APP memberi anda nombor pesanan
2. Anda boleh menyemak status pesanan pada bila-bila masa
3. APP memberitahu anda apabila penghantaran selesai

Beginilah cara alat tak segerak berfungsi, sesuai untuk tugasan yang mengambil masa lebih lama untuk diproses.

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

Kes penggunaan:

• Operasi yang memakan masa: pemprosesan fail besar, analisis data
• Tugas berbilang langkah: pemaparan video, penjanaan laporan
• Penjejakan kemajuan diperlukan: latihan model, pemprosesan kelompok

3. Penyeragaman Antara Muka Alat: Mewujudkan Spesifikasi Universal

Sama seperti semua peralatan elektrik mengikut piawaian soket bersatu, antara muka alat kami memerlukan penyeragaman. Ini memastikan semua alatan berfungsi dengan sempurna dengan Ejen.

3.1 Spesifikasi Penerangan Alat

Bayangkan menulis manual produk, anda perlu memberitahu pengguna dengan jelas:

• Apa yang dilakukan oleh alat itu
• Apakah parameter yang diperlukan
• Apakah keputusan yang akan dikembalikan

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 Kelas Asas Bersatu

Sama seperti semua peralatan elektrik memerlukan suis kuasa dan antara muka kuasa, semua alatan perlu mengikut spesifikasi asas:

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. Pengendalian Ralat: Menjadikan Alat Lebih Boleh Dipercayai

Sama seperti perkakas rumah memerlukan perlindungan terhadap air, kejutan dan beban berlebihan, alatan memerlukan mekanisme perlindungan yang komprehensif.

4.1 Pengelasan dan Pengendalian Ralat

Bayangkan mengendalikan penghantaran ekspres:

• Alamat salah → Ralat parameter
• Penyelenggaraan sistem → Perkhidmatan tidak tersedia buat sementara waktu
• Kurier terlalu sibuk → Perlu mengehadkan kadar dan cuba semula

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 Mekanisme Cuba Semula

Seperti mengatur penghantaran kedua secara automatik apabila percubaan pertama gagal:

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. Pengoptimuman Prestasi: Menjadikan Alat Lebih Cekap

5.1 Mekanisme Caching

Seperti kedai serbaneka yang meletakkan barangan popular pada kedudukan yang menonjol:

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 Kawalan Konkurensi

Seperti sistem temu janji hospital, mengawal bilangan perkhidmatan serentak:

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. Pengujian dan Dokumentasi: Memastikan Kebolehpercayaan Alat

6.1 Pengujian Unit

Seperti pemeriksaan kualiti sebelum pelancaran produk baharu:

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 Standard Dokumentasi

Seperti menulis manual produk yang terperinci dan jelas:

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)

7. Rumusan

Membangunkan alat Ejen yang baik adalah seperti mencipta kotak alat yang sempurna:

1. Klasifikasi alat yang betul - Sync/Async masing-masing mempunyai kegunaannya
2. Antara muka standard - Mudah untuk pengurusan bersatu
3. Mekanisme perlindungan - Kendalikan pelbagai pengecualian
4. Mengejar kecekapan - Cache apabila diperlukan, had kadar apabila perlu
5. Fokus kualiti - Ujian menyeluruh, dokumentasi yang jelas

Ingat: Alat yang baik boleh menjadikan Ejen dua kali lebih berkesan, manakala alatan yang lemah akan mengehadkan Ejen pada setiap masa.

Atas ialah kandungan terperinci Panduan Pembangunan Alat Agen: Daripada Reka Bentuk kepada Pengoptimuman. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!