الأدوات كواجهة

طريقان إلى نفس الفكرة

قبل أن تبدأ

الفكرة الجوهرية

النموذج لا يرى كود أداتك، بل يرى اسمها ووصفها ومخطّط معاملاتها. في هذا الدرس تبني الثلاثة جيدًا، ثم تكتب رسائل خطأ يفهمها النموذج.

1الوصف هو الواجهة

النموذج يختار الأداة من كلماتها فقط. اسم مثل tool1 ووصف مثل «يجلب بيانات» لا يقولان له شيئًا، فيختار شبه عشوائيًّا.

في المثال، «نموذج» بسيط يختار الأداة التي تشترك مع الطلب في أكثر الكلمات. هذا تبسيط، لكن النماذج الحقيقية تعتمد على الوصف بنفس الطريقة.

def pick_tool(request, tools):
    """Stand-in for the model: picks the tool whose name and description share most words with the request."""
    words = set(request.lower().replace("?", "").split())
    def overlap(t):
        return len(words & set((t["name"].replace("_", " ") + " " + t["description"]).lower().split()))
    return max(tools, key=overlap)["name"]

vague = [
    {"name": "tool1", "description": "Gets data."},
    {"name": "tool2", "description": "Handles records from the system."},
]
clear = [
    {"name": "get_order_status", "description": "Look up the shipping status and delivery date of a customer order by its order number."},
    {"name": "search_help_articles", "description": "Search help centre articles for how-to questions, like resetting a password or changing an address."},
]
requests = ["what is the delivery date of my order?", "how do I reset my password?"]
for r in requests:
    print(f"{r}\n   vague tools -> {pick_tool(r, vague)}    clear tools -> {pick_tool(r, clear)}")

مع الأدوات الغامضة، الاختيار عشوائي عمليًّا: tool2 اختيرت لسؤال التوصيل فقط لأن وصفها يحتوي «the». مع الأسماء والأوصاف الواضحة، كل طلب ذهب لأداته. الوصف الجيد يقول ماذا تفعل الأداة، ومتى تُستخدم، وبمثال على الطلب الذي يناسبها.

2المخطّط والقيم الافتراضية

تعريف الأداة ثلاثة أجزاء: اسم بفعل ومفعول، ووصف يقول ماذا ومتى ومتى لا، ومخطّط JSON لمعاملاتها. النموذج يملأ المخطّط، وكودك يتحقّق منه قبل التنفيذ.

get_order_status = {
    "name": "get_order_status",
    "description": (
        "Look up the shipping status and expected delivery date of one customer order. "
        "Use it when the user asks where an order is or when it will arrive. "
        "Do not use it for refunds; use get_refund_policy for that. "
        "Example: 'where is my order 48213?' -> order_id='48213'."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {"type": "string", "description": "The 5-digit number on the receipt, digits only."},
            "include_history": {"type": "boolean", "default": False,
                                "description": "Also return every tracking event. Rarely needed."},
        },
        "required": ["order_id"],
    },
}

الوصف يقول ماذا ومتى ومتى لا، ويحيل إلى الأداة البديلة، ويعطي مثالًا. ومعامل واحد مطلوب، والثاني اختياري بقيمة افتراضية ووصف يقول إنه نادرًا ما يلزم. أسماء الحقول تختلف قليلًا بين المزوّدين (input_schema أو parameters)، والمحتوى نفسه.

انظر إلى الرسم: الوصف أوسع جزء، لأنه أهم سطر تكتبه لوكيل. وكل معامل اختياري بقيمة افتراضية معقولة يقلّل ما يجب أن يقرّره النموذج، ويقلّل أخطاءه.

3رسائل خطأ يفهمها النموذج

النموذج يقرأ نتيجة الأداة، بما فيها الخطأ. الاستثناء الخام يتركه يتخبّط، والخطأ الذي يقول ما حدث وما الخطوة التالية يجعله يصحّح نفسه.

انظر إلى الرسم: الأداة تعيد خطأً واضحًا، فيسأل النموذج المستخدم عن الرقم الصحيح، ثم يستدعي الأداة من جديد.

نسختان من نفس الأداة. الأولى تنهار عند أي مدخل غير متوقّع، والثانية تنظّف المدخل وتشرح الخطأ.

import json

ORDERS = {"48213": "shipped"}

def get_order_status_bad(order_id):
    return ORDERS[order_id]                       # raises KeyError: the model sees a stack trace

def get_order_status(order_id, include_history=False):
    order_id = str(order_id).strip().lstrip("#")
    if not order_id.isdigit() or len(order_id) != 5:
        return {"error": f"order_id must be 5 digits, got {order_id!r}. Ask the user for the number on their receipt."}
    if order_id not in ORDERS:
        return {"error": f"No order {order_id}. Check the number with the user; do not guess another one."}
    return {"order_id": order_id, "status": ORDERS[order_id]}

for arg in ["#48213", "4821", "99999"]:
    try:
        print("bad: ", get_order_status_bad(arg))
    except Exception as e:
        print("bad:  crashed with", type(e).__name__, e)
    print("good:", json.dumps(get_order_status(arg)))

النسخة السيئة انهارت حتى مع #48213، وهو رقم صحيح بعلامة # يكتبها الناس كثيرًا. النسخة الجيدة نظّفته ونجحت، وحين كان الرقم قصيرًا قالت للنموذج ماذا يطلب من المستخدم، وحين لم يوجد قالت «لا تخمّن رقمًا آخر». هذه الجملة الأخيرة تمنع سلوكًا حقيقيًّا: نماذج تجرّب أرقامًا قريبة حتى تجد شيئًا.

كيف يعمل، خطوة بخطوة: كيف يستدعي النموذج أداتك

أعمق قليلًا

وأعد من الأداة ما يحتاجه النموذج فقط. رد بخمسين حقلًا من قاعدة البيانات يملأ السياق بأرقام داخلية ومعرّفات لا معنى لها، ويكرّر في كل خطوة لاحقة. اختر الحقول التي تحضر، وأضف معامل detail اختياري لمن يحتاج أكثر.

مثال محلول

لنرَ ذلك مباشرة. «النموذج» هنا يختار الأداة التي تشترك كلماتها مع الطلب أكثر، وهذا تبسيط، لكن النماذج الحقيقية تعتمد على الوصف بنفس الطريقة في جوهرها.

جرّب بلا كود

خرافة مقابل حقيقة

جرّب بنفسك

بطاقات مراجعة سريعة

تحقق من فهمك