المستوى: مبتدئ

لو سألت الـ AI "كم سعر سهم Apple دلوقتي" فبيخترعلك رقم، المشكلة مش غباء. المشكلة إن النموذج معندوش طريقة يوصل لبيانات حقيقية. Function Calling هو اللي بيحل ده. النموذج بيتعلم متى يستدعي أداة من عندك، وأنت بتنفذها وترجع النتيجة.

Function Calling: ليه أصلاً موجود؟

نموذج اللغة عنده حدود واضحة. مش عارف الوقت دلوقتي، مش شايف الداتابيز بتاعتك، مش بيقدر يبعت إيميل. لكن لو وفّرتله "أدوات" — كل أداة لها اسم ووصف ومدخلات — يقدر يقرر "في السؤال ده محتاج أنفّذ check_stock_price"، يولّد JSON بالمدخلات، وأنت تنفذ وتديله النتيجة. ده الفرق بين نموذج بيخمن، ونموذج بيشتغل بداتا حقيقية.

مثال بسيط من حياتنا قبل ما ندخل في التعريف

تخيّل صديقك مسافر بره مصر بيكلمك على الواتساب وعاوز يعرف سعر الدولار النهارده. هو ميقدرش يفتح موقع البنك المركزي بنفسه من بلده. بيقولّك: "ابعتلي السعر دلوقتي". أنت بتفتح الموقع، تشوف الرقم، وترجعّله بالقيمة الفعلية. Function Calling بنفس الفكرة بالظبط: النموذج هو "الصديق" اللي بيطلب، أنت "المتصفح والموقع" اللي بيجيب الرقم الحقيقي. النموذج بيقول "محتاج النتيجة دي"، ما بيجيبهاش بنفسه.

التعريف العلمي بدقة

Function Calling هي قدرة النموذج على إخراج استدعاء منظم بصيغة JSON يحدّد فيه اسم دالة ومعطياتها، طبقًا لـ schema تعرّفه أنت في الطلب. النموذج لا ينفّذ الدالة بنفسه. يخرج فقط نية الاستدعاء (intent)، ثم يأخذ نتيجتك ويبني الرد النهائي للمستخدم. الدورة الكاملة: user message → tool_call JSON → tool execution by you → tool_result → final response. الـ schema بيستخدم JSON Schema القياسي، ده مش اختراع Anthropic أو OpenAI.

كود Python شغّال على Anthropic SDK

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "ارجع الطقس الحالي لمدينة محددة بالدرجة المئوية",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "اسم المدينة بالإنجليزية"}
            },
            "required": ["city"]
        }
    }
]

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    tools=tools,
    messages=[{"role": "user", "content": "إيه الطقس في القاهرة دلوقتي؟"}]
)

# الرد بيرجع فيه content block من نوع tool_use:
# { "type": "tool_use", "name": "get_weather", "input": {"city": "Cairo"} }
# نفّذ HTTP حقيقي على API الطقس، ثم ابعت النتيجة في رسالة tool_result

الترتيب الصحيح للتنفيذ

1. عرّف schema لكل أداة (اسم واضح، وصف يشرح متى تُستخدم، مدخلات مع types).
2. ابعت رسالة المستخدم + قائمة tools للنموذج في نفس الطلب.
3. افحص الرد. لو فيه content block بـ type: tool_use، خد الاسم والمدخلات.
4. نفّذ الدالة الحقيقية بنفسك (HTTP request, DB query, file read).
5. ابعت النتيجة في رسالة جديدة كـ tool_result مرتبطة بنفس tool_use_id.
6. النموذج يرد للمستخدم بإجابة طبيعية بناء على النتيجة الحقيقية.

Trade-offs لازم تعرفها قبل ما تستخدمها

المكسب: النموذج يقدر يوصل لبيانات حقيقية ويعمل actions فعلية بدل التخمين. الخسارة: كل استدعاء أداة بيضيف round-trip كامل (latency حوالي 500ms إلى 2s إضافي حسب سرعة أداتك)، والـ tokens بتاعت تعريف الأدوات بتُحسب في كل طلب لأنها بترجع للنموذج. لو عندك 20 أداة، ممكن تأكل 1500 توكن قبل ما السؤال يبدأ. الحل: ما تبعتش كل الأدوات في كل طلب. صنّفها حسب السياق وابعت اللي يخص السؤال الحالي فقط، أو استخدم router بسيط على مستوى التطبيق.

افتراض مهم: هذا الشرح مبني على Anthropic Python SDK ≥ 0.40 ونماذج Claude Sonnet 4.6 وما بعدها. الـ schema تقريبًا نفس الشكل في OpenAI، لكن المسميات مختلفة (tools ثم tool_calls بدل tool_use).

متى لا تستخدم Function Calling

لو سؤال المستخدم بيتجاوب من معرفة عامة فقط (زي "اشرحلي closures في JavaScript" أو "اكتبلي ملخص للنص ده")، ما تستعملش tools. هتدفع زيادة في latency و tokens بدون فائدة. كذلك لو الأداة بتاخد أكتر من 30 ثانية للتنفيذ (تقارير ضخمة، ML inference طويل، تصدير ملفات كبيرة)، ابني queue + webhook ولا تخلي المستخدم مستني الـ HTTP request open.

الخطوة التالية

افتح SDK المشروع بتاعك دلوقتي وعرّف أداة واحدة فقط، أبسط حاجة عندك (get_user_count مثلاً اللي بترجع رقم من DB). نفّذ الدورة الكاملة من tool_use لـ tool_result. لما تتأكد إن الـ flow بيشتغل صح على أداة واحدة، ضيف باقي الأدوات تدريجيًا. لا تبدأ بـ 10 أدوات وتحاول تظبطهم كلهم في نفس الوقت.

المصادر

• Anthropic Tool Use Documentation: docs.anthropic.com/en/docs/build-with-claude/tool-use
• OpenAI Function Calling Guide: platform.openai.com/docs/guides/function-calling
• JSON Schema Specification: json-schema.org
• Anthropic Python SDK GitHub: github.com/anthropics/anthropic-sdk-python