استدعاء الدوال: كيف تربط نماذج اللغة بأدوات تطبيقك؟

كيف يعمل استدعاء الدوال؟

النموذج يُنشئ الطلب، والتطبيق ينفّذ العملية. إذا كنت مطوّرًا تربط نموذج لغة بواجهة API أو بقاعدة بيانات، فهذا الفصل بين المسؤوليتين هو أهم ما ينبغي فهمه قبل كتابة الكود.

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

تزوّد النموذج بمخطط للأداة، أي وصف للعملية المتاحة وحقول الإدخال التي تقبلها. عندئذ يستطيع النموذج الرد باسم الدالة ووسائط الاستدعاء، أي القيم التي ستوضع في تلك الحقول. يتحقق التطبيق من الطلب، ويستدعي الدالة، ثم يعيد مخرجاتها كي يتمكن النموذج من الإجابة أو طلب عملية أخرى. وينصّ دليل Google لاستدعاء الدوال صراحةً على أن مسؤولية التنفيذ تقع على تطبيقك.

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

ما الفرق بين استدعاء الدوال واستدعاء الأدوات؟

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

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

مثال مبسّط لاستدعاء الدوال من البداية إلى النهاية

أتِح أداة للاستعلام عن حالة الطلب، ثم أعد الحالة التي وفّرتها قاعدة البيانات فقط. يستخدم المثال التالي طلبًا وهميًا أُنشئ لهذا الغرض، هو ORD-1042، داخل قاعدة بيانات SQLite محلية. إنه بيانات تجريبية للتعلّم، وليس سجل عميل أو استجابة فعلية رُصدت من نموذج.

استدعاء الدوال في OpenAI: تنفيذ دورة الطلب والنتيجة

تشرح OpenAI في وثائق استدعاء الدوال دورة العمل في Responses API: تعرّف الدالة، وتتلقى function_call، وتنفّذ الكود، ثم تعيد function_call_output يحمل قيمة call_id نفسها.

ثبّت حزمة SDK الخاصة بـ Python باستخدام python -m pip install openai، واضبط متغيّر البيئة OPENAI_API_KEY، ثم احفظ الكود التالي في ملف order_tool.py. يستخدم المثال gpt-6-astra، وهو النموذج الوارد في مثال Responses في الوثائق الحالية؛ وهذا لا يعني أنه النموذج الوحيد المناسب. تشغيل البرنامج يرسل طلبات فعلية إلى API، بينما تبقى قاعدة البيانات في الذاكرة.

import json
import re
import sqlite3

from openai import OpenAI

client = OpenAI()
model = "gpt-6-astra"

# Demo identity. In a web app, obtain this from your authenticated session.
tenant_id = "tenant_demo"
db = sqlite3.connect(":memory:")
db.execute("CREATE TABLE orders (tenant_id TEXT, order_id TEXT, status TEXT)")
db.execute(
    "INSERT INTO orders VALUES (?, ?, ?)",
    (tenant_id, "ORD-1042", "shipped"),
)

# The tool schema: a name, a purpose, and an input contract.
tool = {
    "type": "function",
    "name": "get_order_status",
    "description": (
        "Look up the current status of an existing order by order ID. "
        "Use for status questions, not refunds or address changes. "
        "Returns the order ID and status, or an error."
    ),
    "strict": True,
    "parameters": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string",
                "description": "The order ID supplied by the user, such as ORD-1042.",
            }
        },
        "required": ["order_id"],
        "additionalProperties": False,
    },
}


def execute(name, raw_arguments):
    if name != "get_order_status":
        return {"error": "unknown_tool"}
    try:
        args = json.loads(raw_arguments)
    except (json.JSONDecodeError, TypeError):
        return {"error": "invalid_arguments"}
    if not isinstance(args, dict) or set(args) != {"order_id"}:
        return {"error": "invalid_arguments"}
    order_id = args["order_id"]
    if not isinstance(order_id, str) or not re.fullmatch(r"ORD-[0-9]+", order_id):
        return {"error": "invalid_order_id"}
    row = db.execute(
        "SELECT status FROM orders WHERE tenant_id = ? AND order_id = ?",
        (tenant_id, order_id),
    ).fetchone()
    if row is None:
        return {"error": "order_not_found"}
    return {"order_id": order_id, "status": row[0]}


history = [{"role": "user", "content": "What is the status of order ORD-1042?"}]
response = client.responses.create(
    model=model,
    input=history,
    tools=[tool],
    tool_choice={"type": "function", "name": "get_order_status"},
    parallel_tool_calls=False,
)

# Keep every output item, including any reasoning items.
history.extend(response.output)
calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1:
    raise RuntimeError("Expected one tool call; inspect the response before continuing.")
call = calls[0]
result = execute(call.name, call.arguments)
history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps(result),
})

answer = client.responses.create(
    model=model,
    input=history,
    tools=[tool],
    tool_choice="none",
    instructions="Answer from the tool result. If it contains an error, report the failure.",
)
print(answer.output_text)
db.close()

في مسار التنفيذ الناجح لهذا المثال المحدود عمدًا، يبلغ عدد الطلبات إلى النموذج 2 وعدد استعلامات قاعدة البيانات 1. يفرض المثال الاستعلام المحدد في الطلب الأول، ويعطّل أي استدعاءات إضافية للأدوات في الطلب الثاني. بهذه الطريقة تتضح آلية العمل؛ أما المساعد العام فيحتاج أيضًا إلى التعامل مع الطلبات التي لا تناسبها أي أداة، أو تنقصها معلومات، أو تتطلب استعلامًا آخر.

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

استدعاء النموذج والنتيجة التي تعيدها إليه

الطلب والنتيجة رسالتان منفصلتان يربط بينهما معرّف الاستدعاء. يوضح المثال التالي شكلًا نموذجيًا للاستدعاء. المعرّفات والقيم للتوضيح فقط؛ وليست هذه استجابة API مسجّلة.

{
  "type": "function_call",
  "id": "fc_demo",
  "call_id": "call_demo",
  "name": "get_order_status",
  "arguments": "{\"order_id\":\"ORD-1042\"}"
}

بعد أن يعيد معالج الطلب حالة السجل التجريبي، يضيف التطبيق النتيجة التالية. وعند التعامل مع استجابة فعلية، انسخ قيمة call.call_id الحقيقية؛ ولا تنشئ معرّفًا جديدًا.

{
  "type": "function_call_output",
  "call_id": "call_demo",
  "output": "{\"order_id\":\"ORD-1042\",\"status\":\"shipped\"}"
}

أصبح لدى النموذج الآن ما يستند إليه في إجابة مثل «تم شحن الطلب ORD-1042». الحالة جاءت من قاعدة البيانات. أما دور النموذج فكان تحويل طلب المستخدم إلى وسائط استدعاء، ثم تحويل البيانات المُعادة إلى إجابة.

الفكرة نفسها في وثائق المزوّدين الثلاثة

نمط التنفيذ مشترك بين المزوّدين، لكن تنسيق الرسائل ليس كذلك. جرى التحقق من المقارنة التالية بالرجوع إلى وثائق المزوّدين المنشورة على الإنترنت في 17 أكتوبر 2026. وهي تميّز بين أمثلتهم الحالية، بدل افتراض أن الحقول المتشابهة في الاسم قابلة للتبادل.

استخدام الأدوات في Anthropic

تعرّف وثائق استخدام الأدوات لدى Anthropic مدخلات الدالة باستخدام input_schema. وبالنسبة إلى أداة تعمل لدى العميل، يتولى الكود معالجة كتلة tool_use التي يرسلها المساعد، ثم يرسل tool_result داخل رسالة المستخدم التالية، مع الاحتفاظ برسالة المساعد في المحادثة.

توضح الوثائق هذا الفصل صراحةً: أدوات العميل تعمل داخل تطبيقك، بينما تعمل أدوات الخادم على البنية التحتية لدى Anthropic. لذلك، فإن وجود أداة بحث مستضافة لا يثبت قدرة Claude على تنفيذ دالة قاعدة بياناتك الخاصة مباشرةً. يظل تنفيذ تلك الدالة من مسؤوليتك.

استدعاء الدوال في Gemini

تفصل وثائق Google لاستدعاء الدوال في Gemini أيضًا بين طلب النموذج وتنفيذ التطبيق. ويستخدم الدليل الحالي Interactions API، مع خطوتَي function_call وfunction_result، وprevious_interaction_id لمواصلة التفاعل.

اتبع المثال الخاص بواجهة API التي تستخدمها. نسخ تعريف أداة من واجهة ورسالة نتيجة من واجهة أخرى لا يجعل التنفيذ قابلًا للنقل بينهما. حافظ على العملية المشتركة، مثل get_order_status، وكيّف تعريفها وتنسيق رسالة نتيجتها معًا.

كيف تشكّل استدعاءات الأدوات دورة عمل الوكيل؟

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

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

تميّز إرشادات Anthropic لبناء الوكلاء بين مسارات العمل الثابتة والوكلاء الذين يوجّهون استخدامهم للأدوات بأنفسهم. وتشرح أيضًا دور النتائج التي تعيدها الأدوات وشروط التوقف ضمن هذه الدورة.

وصف هذه الآلية بأنها «أساس كل وكيل» اختصار مفيد إلى حدّ معين فقط. فالوثائق لا تثبت أن كل نظام يُسمّى وكيلًا يستخدم واجهة بعينها لاستدعاء الدوال. الفكرة الأهم هي الدورة التي تربط النموذج بالفعل المنفّذ. ويمكن أن يظل الاستعلام الواحد جزءًا من مسار عمل ثابت؛ ولا يحتاج إلى مخطّط مستقل.

ثلاث مشكلات تظهر في بيئة الإنتاج

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

مخطط ضعيف: تعريف المدخلات يحتمل معنى خاطئًا

الحقل المسمّى id لا يوضح للنموذج إن كنت تريد رقم طلب، أو معرّف عميل، أو مرجع شحنة. وسلسلة نصية بلا قيود تحمل اسم action تفتح الباب لقيم قد لا يتعرف عليها معالج الطلب. حسّن تعريف المدخلات قبل إضافة مزيد من التعليمات حوله.

اختر أسماء دقيقة للمعاملات، واشرح معناها، واستخدم تعدادًا للقيم المسموح بها عندما لا تُقبل إلا مجموعة ثابتة منها. واجعل أداتك الأولى محدودة بما يكفي لوصف غرضها في جملة واضحة. في المثال، اسم order_id صريح، والوصف يستبعد عمليات استرداد الأموال وتغيير العناوين.

يتطلب الوضع الصارم لدى OpenAI ضبط additionalProperties: false للكائنات وإدراج جميع الخصائص ضمن required؛ ويمكن السماح بالقيمة null للقيمة التي قد تكون غائبة. ويوثق الدليل متطلبات الوضع الصارم هذه. كما توثق Google قيودًا على المخططات، لذا فإن قبول أداة التحقق المحلية لمخطط ما لا يعني تلقائيًا أن كل واجهات النماذج ستقبله.

حدود المخطط: يمكنه تقييد طريقة تمثيل البيانات، لكن معرّف الطلب الصحيح من حيث الصيغة قد يشير إلى الطلب الخطأ. والتحقق من ذلك مسؤولية التطبيق.

اختيار الأداة الخطأ: وسائط سليمة لعملية غير مناسبة

العميل الذي يسأل «أين وصل ردّ المبلغ؟» يحتاج إلى الاستعلام عن الحالة، لا إلى بدء عملية استرداد جديدة. وإذا كان وصف كلتا الأداتين هو «تتعامل مع عمليات استرداد الأموال»، فقد جعلت الاختيار بينهما ملتبسًا.

اشرح متى ينبغي استخدام كل أداة ومتى لا ينبغي، وأتِح فقط العمليات المناسبة للمهمة الحالية وللمستخدم. وتوصي إرشادات Anthropic لتعريف الأدوات تحديدًا بتوضيح الغرض، ومعنى المعاملات، ونطاق الاستخدام، والقيود.

عندما يعرف التطبيق مسبقًا العملية التي يجب تنفيذها، استخدم آلية مدعومة للتحكم في اختيار الأداة، أو استدعِ العملية مباشرةً. يفرض المثال استعلامًا محددًا لأغراض الشرح؛ فلا تحوّل ذلك إلى قاعدة تقول إن «كل رسالة من المستخدم يجب أن تشغّل أداة». فالتحية أو السؤال الناقص عن طلب قد يحتاجان إلى ردّ حواري فحسب.

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

وسائط بلا تحقق: الصيغة صحيحة لكن الطلب يتجاوز صلاحياته

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

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

تشير النظرة العامة لدى Anthropic إلى أن نقص المعلومات قد يدفع النموذج إلى استنتاج قيم الوسائط. لا تفترض أن وجود حقل مطلوب يثبت أن المستخدم هو من قدّم قيمته. وعند تنفيذ إجراء له تبعات، قارن العملية المطلوبة ومدخلاتها بما أذن به المستخدم فعلًا.

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

متى تكفي المخرجات المنظّمة بدل استدعاء أداة؟

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

يميّز دليل Structured Outputs لدى OpenAI بين ربط وظائف التطبيق بالنموذج وتنسيق استجابة النموذج. ويوضح أيضًا أن مخططات الدوال الصارمة تعتمد داخليًا على Structured Outputs. إنهما إمكانيتان متكاملتان، وليستا منتجين يقتضي استخدام أحدهما استبعاد الآخر.

لنفترض أنك زوّدت النموذج بالفعل بسجل طلب، ولا تحتاج لواجهتك إلا إلى {order_id, status, explanation}. تكفي هنا إجابة منظّمة. أما إذا كان السجل غير متاح أو يحتاج إلى تحديث، فنفّذ الاستعلام أولًا. ويمكنك بعد ذلك تنظيم الإجابة النهائية أيضًا.

كائن JSON يقول إن رسالة بريد إلكتروني أُرسلت يظل مجرد كائن مخرجات. إرسال الرسالة يتطلب تنفيذ عملية والحصول على نتيجة يمكنك التحقق منها.

ما الفرق بين استدعاء الدوال وMCP؟

يعالج استدعاء الدوال طلب النموذج تنفيذ عملية. أما Model Context Protocol (MCP) فيوفّر واجهة مشتركة لإتاحة الأدوات وغيرها من عناصر السياق للتطبيقات المتوافقة. يمكنك ربط دالة مباشرةً بتطبيق واحد قبل إضافة خادم مستقل للأدوات.

MCP واستدعاء الأدوات: متى تصبح المشاركة مفيدة؟

إذا احتاجت عدة تطبيقات إلى الاستعلام نفسه عن الطلبات، فيمكن لخادم MCP إتاحة الأداة لاكتشافها واستدعائها. وتشرح وثائق بنية MCP استخدام tools/list للاكتشاف وtools/call لطلبات التنفيذ. ويظل الخادم بحاجة إلى تنفيذ فعلي للعملية وفحوص لصلاحيات الوصول.

للمضي إلى هذه الخطوة، اقرأ ما هو MCP وكيف يعمل المضيف والعميل والخادم معًا. وبعد نجاح الاستعلام المباشر، يشرح دليل بناء خادم MCP كيف تجمع هذه الإمكانات في صيغة قابلة لإعادة الاستخدام. إضافة MCP لا تلغي ضرورة التحقق من العملية المطلوبة.

أين تكمن المبالغة؟

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

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

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

من أين تبدأ قبل الإطلاق؟

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

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

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

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

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

الأسئلة الشائعة

للحصول على أدلة عملية للبناء باستخدام الذكاء الاصطناعي، اشترك في النشرة البريدية.