الوحدة 3 · الدرس 2 · 15 دقيقة قراءة
استدعاء الوظائف خطوة بخطوة
Function Calling
المقدمة
استدعاء الوظائف هو الآلية التي تجعل النموذج يعبّر عن رغبته في استخدام أداة بصيغة منظمة يفهمها البرنامج. في هذا الدرس نتتبع الدورة كاملة من تعريف الأداة إلى الإجابة النهائية، ونبني حلقة استدعاء بسيطة ببايثون، ونرى الشكل نفسه في مكتبة حقيقية.
أهداف التعلم
- شرح مراحل دورة استدعاء الوظائف (Function Calling) بالترتيب
- التمييز بين رسالة النموذج النصية وطلب استدعاء الأداة المنظم
- بناء حلقة تنفيذ بسيطة تعيد نتيجة الأداة إلى النموذج
- التعرف على شكل الأدوات الوظيفية في OpenAI Agents SDK
الفكرة الأساسية
في الأيام الأولى لبناء الوكلاء كان المطورون يطلبون من النموذج أن يكتب شيئًا مثل «ACTION: search(...)» ثم يحللون النص بتعابير نمطية هشة. استدعاء الوظائف (Function Calling) حلّ هذه المشكلة: نرسل إلى النموذج قائمة أدوات موصوفة بصيغة منظمة، فيعيد النموذج عند الحاجة طلب استدعاء فيه اسم الأداة ومعاملاتها بصيغة JSON بدل نص حر. البرنامج يقرأ هذا الطلب مباشرة دون تخمين.
المهم أن نتذكر: النموذج لا ينفّذ شيئًا. هو يولّد بيانات منظمة تقول «أريد تشغيل الأداة X بهذه القيم»، والقرار النهائي بالتنفيذ بيد التطبيق.
الدورة الكاملة في ست خطوات
- التعريف: يرسل التطبيق إلى النموذج رسالة المستخدم مع قائمة الأدوات المتاحة (الاسم، الوصف، مخطط المدخلات).
- القرار: يقرر النموذج إن كان يحتاج أداة. إن لم يحتج يجيب نصًا مباشرة.
- الطلب: إن احتاج، يعيد طلب استدعاء منظمًا، وقد يحمل معرّفًا فريدًا للاستدعاء.
- التحقق والتنفيذ: يتحقق التطبيق من اسم الأداة وصحة المعاملات ثم ينفّذ الدالة.
- الإرجاع: يضيف التطبيق نتيجة الأداة إلى المحادثة مربوطة بمعرّف الاستدعاء نفسه.
- الصياغة: يقرأ النموذج النتيجة ويقرر: استدعاء أداة أخرى أو كتابة الإجابة النهائية.
تتكرر الخطوات من 2 إلى 6 حتى تظهر إجابة نهائية أو يبلغ الوكيل حدًا أقصى من الدورات.
شكل الطلب والنتيجة
تختلف التفاصيل بين المزودين، لكن الفكرة واحدة. هذا شكل توضيحي عام لطلب استدعاء ونتيجته:
{
"tool_call": {
"id": "call_01",
"name": "get_exchange_rate",
"arguments": {"base": "USD", "target": "EGP"}
},
"tool_result": {
"call_id": "call_01",
"content": {"rate": 48.5, "source": "demo_data"}
}
}القيم هنا بيانات تجريبية للشرح فقط. لاحظ أن call_id في النتيجة يطابق id في الطلب؛ هذا الربط ضروري عندما يطلب النموذج أكثر من أداة في دورة واحدة.
مثال عملي: حلقة استدعاء مبسطة
لنحاكِ الدورة كاملة ببايثون عادي. سنستبدل النموذج بدالة قواعد بسيطة fake_model حتى يعمل المثال دون أي مفتاح API، تمامًا كما يفعل محاكي الأكاديمية:
import json
def get_exchange_rate(base: str, target: str) -> dict:
demo = {("USD", "EGP"): 48.5, ("USD", "SAR"): 3.75}
return {"rate": demo.get((base, target)), "source": "demo_data"}
TOOLS = {"get_exchange_rate": get_exchange_rate}
def fake_model(messages):
# نموذج وهمي قائم على قواعد: يطلب الأداة أولًا ثم يجيب
last = messages[-1]
if last["role"] == "user":
return {"tool_call": {"id": "call_01", "name": "get_exchange_rate",
"arguments": {"base": "USD", "target": "SAR"}}}
rate = last["content"]["rate"]
return {"text": f"سعر الدولار بالريال في البيانات التجريبية: {rate}"}
messages = [{"role": "user", "content": "كم سعر الدولار بالريال؟"}]
for turn in range(5): # حد أقصى للدورات
reply = fake_model(messages)
if "text" in reply:
print(reply["text"])
break
call = reply["tool_call"]
fn = TOOLS.get(call["name"])
if fn is None:
result = {"error": "unknown tool"}
else:
result = fn(**call["arguments"])
messages.append({"role": "tool", "call_id": call["id"], "content": result})
print("استدعاء:", json.dumps(call, ensure_ascii=False))حين تستبدل fake_model باستدعاء نموذج حقيقي يبقى هيكل الحلقة كما هو: إرسال، فحص الرد، تنفيذ، إرجاع، تكرار.
الشكل نفسه في مكتبة حقيقية
في OpenAI Agents SDK (بحسب التوثيق الرسمي، مراجعة 18 نوفمبر 2026، الإصدار 0.25.0) تحوّل المكتبة دالة بايثون إلى أداة عبر المزخرف @function_tool، وتستنتج المخطط من تلميحات الأنواع، ثم يدير Runner الحلقة بنفسه. هذا المثال يتطلب تثبيت openai-agents ومتغير البيئة OPENAI_API_KEY:
# يتطلب: pip install openai-agents ومفتاح OPENAI_API_KEY
from agents import Agent, Runner, function_tool
@function_tool
def get_exchange_rate(base: str, target: str) -> str:
return "3.75 (بيانات تجريبية)"
agent = Agent(name="Assistant",
instructions="أجب عن أسئلة العملات مستخدمًا الأداة.",
tools=[get_exchange_rate])
result = Runner.run_sync(agent, "كم سعر الدولار بالريال؟")
print(result.final_output)إذا تجاوزت الحلقة الحد max_turns ترفع المكتبة الاستثناء MaxTurnsExceeded، وهو المكافئ الرسمي للحد الأقصى في مثالنا اليدوي.
الملخص
استدعاء الوظائف يجعل النموذج يعبّر عن حاجته إلى أداة بطلب منظم بصيغة JSON بدل نص حر. تمر الدورة بالتعريف والقرار والطلب والتحقق والتنفيذ والإرجاع والصياغة، وتتكرر حتى الإجابة النهائية أو الحد الأقصى. ربط النتيجة بمعرّف الاستدعاء ضروري عند تعدد الاستدعاءات. المكتبات مثل OpenAI Agents SDK تدير هذه الحلقة نيابة عنك لكن المنطق نفسه.
المصطلحات
| المصطلح | English | التعريف |
|---|---|---|
| استدعاء الوظائف | Function Calling | قدرة النموذج على إرجاع طلب منظم لتشغيل دالة معرّفة |
| طلب استدعاء | Tool Call | كائن يحمل اسم الأداة ومعاملاتها ومعرّفًا فريدًا |
| المعاملات | Arguments | القيم التي يمررها النموذج إلى الأداة |
| معرّف الاستدعاء | Call ID | رمز يربط نتيجة الأداة بالطلب الذي أنتجها |
| الحد الأقصى للدورات | Max Turns | سقف لعدد دورات الحلقة يمنع الدوران بلا نهاية |
أسئلة المراجعة
- رتّب مراحل دورة استدعاء الوظائف واشرح دور التطبيق في كل منها.
- لماذا يُعد معرّف الاستدعاء مهمًا عند طلب أداتين في دورة واحدة؟
- ما خطر استخدام eval لتنفيذ اسم أداة يقترحه النموذج؟
- كيف يقابل max_turns في OpenAI Agents SDK الحد الأقصى في الحلقة اليدوية؟
المراجع
- OpenAI Agents SDK documentation openai.github.io روجع في 2026-11-18
- OpenAI Agents SDK: Running agents openai.github.io روجع في 2026-11-18
- Toolformer: Language Models Can Teach Themselves to Use Tools arxiv.org روجع في 2026-11-18
