Phase 13: Tools & Protocols

واجهة الأدوات لماذا يحتاج الوكلاء إلى إدخال / إدخال منظم

نموذج اللغة ينتج رموز. يقوم برنامج بعملات. الفجوة بين هذين الاثنين هي واجهة الأدوات: عقد يسمح للنموذج بطلب عمل والضيف بتنفيذه. كل كومة 2026 وظيفة تدعو إلى OpenAI ، Anthropic ، و Gemini ؛ MCP tools/call: أجزاء المهمة A2A هي تشفير مختلف لنفس حلقة أربعة خطوات. هذه الدروس تسمى الحلقة وتظهر الحد الأدنى من الآلات لتشغيلها.

Type: Learn

Languages: Python (stdlib, no LLM)

Prerequisites: Phase 11 (LLM completion APIs)

Time: ~45 minutes

أهداف التعلم

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

المشكلة

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

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

تم إرسال الإصدار الأول من هذا العقد في يونيو 2023 كبرامر "العملات" لـ OpenAI.tool_useكتلة في كلود 2.1. إضافة التوأم functionDeclarationsبعد بضعة أشهر. كل مزود يعرض الآن نفس الشكل: قائمة أداة JSON-Schema-typed tool list ، و JSON-payload tool call out. بروتوكول النموذج السياق (نوفمبر 2024) قام بتعميم العقد بحيث يخدم سجل أداة واحد كل نموذج. A2A (أبريل 2026, v1.0) وضع نفس الطبقة البدائية للتفويض من وكيل إلى وكيل.

الحلقة من أربع خطوات هي الخيار الخارجي تحت كل هذه. كل شيء آخر في المرحلة 13 هو إختراعات.

المفهوم

الخطوة الأولى: وصف

يعلن المضيف كل أداة بثلاث حقول.

Name.هو معرف مستقر وقراءة الآلةget_weatherليس "أمر الطقس"
Description.قصة لغة طبيعية واحدة من الفقرة. "استعمل عندما يسأل المستخدم عن الظروف الحالية لمدينة معينة. لا تستخدم للبيانات التاريخية".
Input schema.كائن من مخطط JSON (مسودة 2020-12) يصف حجج الأداة.

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

الخطوة الثانية: تقرر

بالنظر إلى رسالة المستخدم والأدوات المتاحة، يختار النموذج واحدة من ثلاثة سلوكيات.

Answer directlyلا يوجد مكالمة أداة
Call one or more tools.إصدار كائنات الدعوة المهيكلة. تحت parallel_tool_calls: true(الوضع الافتراضي على OpenAI و Gemini، اختيار على Anthropic) يمكن أن ينشر النموذج مكالمات متعددة في جولة واحدة.
Refuse.النتائج المُقسمة في الوضع الصارمة يمكن أن تنتجrefusalحظر بدلاً من مكالمة

تحميل المكالمة الاستثنائية له ثلاثة حقل مستقرة: مكالمةid، أداةname، و JSON argumentsالهوية موجودة حتى يمكن للمضيف أن يرتبط النتيجة اللاحقة مع الدعوة المحددة، والتي هي مهمة عندما تكون الدعوات المتوازية خارج النظام.

الخطوة الثالثة: تنفيذ

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

إن المنفذ نفسه هو رمز عادي. Python، TypeScript، أمر القبو، استفسار قاعدة البيانات. فإنه ينتج نتيجة، التي عادة ما تكون سلسلة ولكن يمكن أن تكون أي قيمة JSON أو كتلة محتوى مهيكلة (نص، الصورة، أو إشارة الموارد في MCP). يجب أن تكون النتيجة سلسلة.

الخطوة الرابعة: مراقبة

المضيف يضيف نتيجة الأداة إلى المحادثة (كـ toolرسالة الدور مع المقابلة idويتم إعادة استدعاء النموذج. يحتوي النموذج الآن على إصدار الأداة في السياق ويمكن أن ينتج إجابة نهائية أو يطلب مزيدا من المكالمات. يستمر هذا حتى يتوقف النموذج عن إصدار المكالمات أو يصل المضيف إلى حد السلامة في عدد التكرار.

ثقة انفصلت

الأدوات تأتي في طعمين مهمين للسلامة.

Pure.القراءة فقط، تحديدية، لا آثار جانبية. get_weather،search_docs،get_current_time-من الآمن أن تتصل بالتحديد
Consequential.يتحول الحالة، ينفق المال، يلمس بيانات المستخدم. send_email،delete_file،execute_tradeيجب أن تكون مغلقة

تقول "قاعدة اثنين" لـ 2026 لعملاء الأمن في متا أن دور واحد يمكن أن يجمع بين ما لا يزيد عن اثنين من: المدخلات غير الموثوق بها ، البيانات الحساسة ، والإجراءات التالية. واجهة الأداة هي المكان الذي تطبق فيه هذه القاعدة عن طريق رفض المكالمات ، وتطلب تأكيد المستخدم ، أو تصعيد النطاقات. انظر المرحلة 13 · 15 للفصل الأمني الكامل ومرحلة 14 · 09 لسياسات الإذن على مستوى العميل.

حيث يعيش الحلقة

Context	Who describes	Who decides	Who executes
Single-turn function calling (OpenAI/Anthropic/Gemini)	App developer	LLM	App developer
MCP	MCP server	LLM via MCP client	MCP server
A2A	Agent Card publisher	Calling agent	Called agent
Web browser (function-calling agent)	Browser extension / WebMCP	LLM	Browser runtime

في كل مكان نفس الخطوات الأربعة أسماء العمود تتغير، الهيكل لا.

لماذا لا تطلب فقط من النموذج إصدار JSON؟

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

الدعوة الوظيفية الأصلية أفضل لثلاث أسباب أولاً، يقوم المزود بتدريب النموذج من نهاية إلى نهاية على شكل المكالمة الدقيقة، لذا يرتفع معدل JSON المفعول إلى 98 إلى 99 في المائة في وضع صارم. ثانياً، فإن حمولة المكالمة المفيدة تقع في فتحة بروتوكولها الخاصة، وليس داخل النص الحر بحيث لا تسرب مكالمة أداة إلى الإجابة المرئية للمستخدم. ثالثا، يفرض مقدمو الخطة الامتثال لترخيص القيود المحدود (الوضع الصارم لـ OpenAI، وطبق الأنثروبيك tool_use، التوأمresponseSchema) يتم ضمان تأكيد الناتج.

المرحلة 13 · 02 تمشي على جانب واحد بين ثلاثة مرفقات إتاحة الإتاحة. المرحلة 13 · 04 تذهب بعمق إلى الخروج المهيكلة.

قطع الدوائر

ينتهي الحلقة عندما يتوقف النموذج عن إصدار المكالمات أو يصل المضيف إلى الحد الأقصى لعدد المفاتيح. يضع مضيف الإنتاج هذا إلى ما بين 5 و 20 جولة. وبالإضافة إلى ذلك، أنت على الأرجح تقريبا في حلقة لا يمكن أن يخرج النموذج منها. كود كود افتراضي إلى 20; مساعدات OpenAI إلى 10; وضع وكيل Cursor إلى 25.

يظهر الخيار البديل حلقات غير محدودة كل ستة أشهر ك "مُصرف عميل 400 دولار في مكالمات API خلال الليل" بعد الوفيات. لا ترسل دون حدود.

المرحلة 14 · 12 تغطي تعويض الأخطاء والشفاء الذاتي في المدى العميق، والمرحلة 17 تغطي حدود معدل الإنتاج.

حيث المرحلة 13 تذهب من هنا

الدروس 02 إلى 05 تلمس سطح المكالمة على مستوى المقدم.
الدروس 06 إلى 14 تعميم الحلقة في MCP.
الدروس 15 إلى 18 تحمي الحلقة ضد الخوادم العدائية، المستخدمين المتعارضين، والسطحات المُطولة غير المصادقة.
الدروس 19 إلى 22 تمتد النمط إلى التعاون بين العملاء، واللاحظة، والتوجه، والإغلاظ.
الدرس 23 يُرسل نظامًا بيئيًا كاملًا يستخدم كل شيء بدائي.

كل درس متبقي هو تعزيز لهذه الحلقة من أربع خطوات.

استخدمها

code/main.pyتعمل حلقة أربع خطوات دون LLM. يقوم وظيفة "قرار" مزيفة بتحاكي النموذج عن طريق مطابقة النمط على رسالة المستخدم. إن المنفذ والمؤكد للخطوة والتحديد من النظام المخطط حقيقي. قم بتشغيله لرؤية التشريع الكامل لطلب / رد مع حالة متوسطة قابلة للطباعة ، ثم استبدل القرار المزيف بأي مزود حقيقي في درس لاحقا.

ما الذي يجب أن ننظر إليه:

يحتوي سجل الأدوات على ثلاث حقل لكل أداة: الاسم والوصف والخططية ومراجعة المنفذ.
المحقق هو مجموعة فرعية من مخططات JSON الحد الأدنى (أنواع، مطلوبة، enum، min/max) مكتوبة في stdlib فقط. مرحلة 13 · 04 يرسل واحدة أكثر اكتمالا.
الحلقة تُحدد عدد التكرار إلى خمسة، وكلاء الإنتاج يحتاجون إلى هذا النوع بالضبط من مفصل الدوائر.

أرسله

هذا الدرس يُنتجoutputs/skill-tool-interface-reviewer.md. بالنظر إلى مسودة تعريف الأداة (اسم + وصف + مخطط + مخطط تنفيذ) ، تقوم المهارة بمراجعة ذلك من أجل تناسب الحلقة: هل الاسم مستقر بالجهاز ، هل هو وصف قصير كامل للاستخدام ، هل تستخدم مخطط JSON Schema 2020-12 بشكل صحيح ، ويعتبر التصنيف النقي مقابل التاتير صريحًا.

التمارين

إضافة أداة رابعة إلى code/main.pyاتصلget_stock_price(ticker). اكتب وصفه على أنه "استخدم عندما يطلب المستخدم سعر الأسهم الحالي عن طريق التكري. لا تستخدم لسعر تاريخي أو ملخصات السوق". قم بتشغيل القائمة وتأكيد استفسارات المسارات القرارية المزيفة التي تذكر التكريات إلى الأداة الجديدة.

كسر مؤكد النظام، اجري مكالمة منargumentsالملف المطلوب يفتقد، وتأكيد استبعاد المضيف قبل تنفيذ. ثم إجراء مكالمة مع حقل غير معروف إضافي. تقرر: هل يجب على المضيف رفض أو تجاهل؟ توجيه اختيارك مع حجة السلامة.

تصنيف كل أداة في الحزام كطاهرة أو نتيجة.consequential: trueعلامة على إدخالات السجل التي تحتاجها، وتغيير الحلقة لتطبيق خط "يؤكد مع المستخدم" كلما تم اختيار أداة نتيجة. هذا هو شكل بوابة التأكيد التي يحتاجها كل مضيف إنتاج.

رسم الحلقة الأربعة خطوات على الورق مع جدول عمود المقدم أعلاه ملأ لعميلك المفضل (كلود مكتب، كورسور، ChatGPT، أو كومة مخصصة). إرجاع مع التغيرات المحددة ل MCP في المرحلة 13 · 06.

اقرأ دليل OpenAI للدعوة إلى الوظائف من أعلى إلى أسفل. حدد الحقل الواحد الذي يقع في الطلب ولكن ليس في حلقة الأربعة خطوات كما هو موضح هنا. شرح ما يضيفه ولماذا هو مريح بدلاً من أساسي.

الشروط الرئيسية

Term	What people say	What it actually means
Tool	"A thing the model can call"	A triple of name + JSON-Schema-typed input + executor function
Function calling	"Native tool use"	Provider-level API support for emitting structured tool calls instead of prose
Tool call	"The model's request to act"	A JSON payload with `id`, `name`, `arguments` emitted by the model
Tool result	"What the tool returned"	The executor's output, wrapped in a `tool` role message with matching id
Parallel tool calls	"Many calls at once"	Multiple call objects in one model turn, independent and orderable by id
Strict mode	"Guaranteed JSON"	Constrained decoding that forces the model's output to validate against the declared schema
Pure tool	"Read-only tool"	No side effects; safe to re-run
Consequential tool	"Action tool"	Mutates external state; requires gate, audit, or user confirmation
Four-step loop	"The tool-call cycle"	describe → decide → execute → observe
Host	"Agent runtime"	The program that holds the tool registry, calls the model, and runs the executor