الدرس 2 من 10

تشريح الـ Tool

الموديل مبيشوفش الكود بتاعك. بيشوف الوصف بس.

الـ tool من وجهة نظر الموديل

لما تدي الموديل أداة، هو مبيشوفش الدالة ولا بيعرف بتعمل إيه من جوه. بيشوف ٣ حاجات بس، ومنهم بيقرر إمتى يستخدمها وإزاي:

name اسم قصير وواضح، زي get_order_status.

description بتعمل إيه، وإمتى تستخدمها، وإمتى لأ، وبترجع إيه. **أهم حتة.**

input_schema شكل المدخلات بصيغة JSON Schema: أنواعها، والإجباري منها، والقيم المسموحة.

الوصف هو كل حاجة

✓ وصف كويس«بتجيب حالة أوردر وميعاد وصوله المتوقع برقم الأوردر. استخدمها لما العميل يسأل عن أوردر معين. رقم الأوردر ٤ أرقام. مبترجعش بيانات الدفع.»

✗ وصف ضعيف«get order»

اكتب الوصف كأنك بتشرح الأداة لموظف جديد أول يوم: بتعمل إيه، ومحتاجة إيه، ومش بتعمل إيه، ولما تفشل بترجع إيه. الوصف الضعيف أشهر سبب إن الـ agent يستخدم الأداة الغلط أو بمدخلات غلط.

الـ JSON Schema

بتوصف المدخلات بطريقة قياسية اسمها JSON Schema. ممكن تكتبها بإيدك، بس الأسهل والأضمن إنك توصفها بـ Pydantic (زي ما عملنا في FastAPI) وهي تطلعها لك:

schema.py

import json
from typing import Literal
from pydantic import BaseModel, Field

class ReturnRequest(BaseModel):
    """Input for creating a product return request."""
    order_id: str = Field(pattern=r"^\d{4}$", description="4-digit order number")
    reason: Literal["damaged", "wrong_item", "size", "changed_mind"]
    notes: str | None = Field(default=None, max_length=300,
                              description="Optional extra details from the customer")

tool = {
    "name": "create_return_request",
    "description": (
        "Create a return request for a delivered order. Use only after confirming "
        "the order exists and the customer explicitly asked to return it. "
        "Returns a request ID. Requires human approval before it takes effect."
    ),
    "input_schema": ReturnRequest.model_json_schema(),
}
print(json.dumps(tool["input_schema"], indent=2, ensure_ascii=False))

لاحظ enum في الـ reason: الموديل مش هيقدر يخترع سبب من عنده، لازم يختار من الأربعة. وأي Literal أو Field بتضيفه بيبقى قيد واضح للموديل ولكودك.

نصايح تصميم

أداة = مهمة واحدة واضحة. get_order_status و cancel_order أحسن من manage_order(action=...).
أسماء فيها مصدرها لما الأدوات تكتر: orders_get و crm_search_customer.
قلّل المدخلات: كل parameter فرصة للغلط. لو الكود يقدر يعرف حاجة لوحده (زي العميل الحالي)، متخليش الموديل يبعتها.
رجّع اللي الموديل محتاجه بس: مش كل عمود في قاعدة البيانات.

⚠ الـ schema مش أمانالـ schema بيوجّه الموديل، بس متعتمدش عليه للحماية. كودك لازم يتحقق من المدخلات تاني قبل التنفيذ، زي ما Pydantic بيعمل في الـ API. الموديل ممكن يبعت حاجة غريبة، والنص اللي الموديل قراه ممكن يكون فيه تلاعب.

→ الدرس اللي فات