دليل تعليمي: بناء وكيل ذكاء اصطناعي يفوض مهام العالم الحقيقي للبشر

واحدة من أقوى القدرات الناشئة في عام ٢٠٢٦ هي قدرة وكلاء الذكاء الاصطناعي على تفويض مهام العالم المادي لمشغلين بشريين موثقين. بدلاً من الاقتصار على ما يمكنهم إنجازه عبر واجهات برمجة التطبيقات الرقمية (APIs)، يمكن لوكلاء الذكاء الاصطناعي الآن طلب إجراءات في العالم الحقيقي مثل تصوير موقع، أو التحقق من تسليم، أو فحص معدات، أو جمع مستندات. يأخذك هذا الدليل التعليمي عبر بناء وكيل ذكاء اصطناعي كامل يقوم بذلك تماماً، بدءاً من الإعداد وحتى النشر في بيئة الإنتاج.

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

يغطي الدليل التعليمي طريقتين للتكامل: HumanOps REST API لتحقيق أقصى قدر من المرونة والتكامل المستقل عن اللغة، و HumanOps MCP server للتكامل الأصلي مع Claude و Cursor ووكلاء الذكاء الاصطناعي الآخرين المتوافقين مع MCP. توفر كلتا الطريقتين نفس القدرات الأساسية، ويعتمد الاختيار بينهما على بنية الوكيل الخاص بك. جميع الأمثلة البرمجية بلغة TypeScript، ولكن مفاهيم REST API تنطبق على أي لغة برمجة.

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

المتطلبات الأساسية والإعداد

قبل البدء، تحتاج إلى حساب HumanOps مع مفتاح API. قم بالتسجيل في humanops.io، وأكمل عملية الإعداد، وانتقل إلى صفحة إعدادات API لإنشاء مفتاحك الأول. سيتم عرض المفتاح مرة واحدة، لذا قم بتخزينه بشكل آمن في متغير بيئة. لهذا الدليل التعليمي، سنستخدم متغير البيئة HUMANOPS_API_KEY.

تحتاج أيضاً إلى تثبيت Node.js الإصدار ١٨ أو أحدث على جهاز التطوير الخاص بك. سنستخدم TypeScript لضمان سلامة الأنواع وتوفير تجربة تطوير أفضل، ولكن يمكن تكييف أمثلة REST API مع أي لغة يمكنها إجراء طلبات HTTP. أنشئ دليلاً جديداً للمشروع وقم بتهيئته باستخدام npm init ثم قم بتثبيت التبعيات التي سنحتاجها: typescript، و tsx لتشغيل TypeScript مباشرة، و node-fetch إذا كنت تستخدم Node 18 بدون دعم fetch الأصلي.

بالنسبة لتكامل MCP server، ستحتاج إلى مضيف متوافق مع MCP مثل Claude Desktop أو Cursor أو أي تطبيق يدعم Model Context Protocol. يتوفر HumanOps MCP server كحزمة npm تعمل محلياً على جهازك وتتصل بـ HumanOps API باستخدام مفتاح API الخاص بك. سنغطي تكوين MCP في قسم مخصص لاحقاً في هذا الدليل التعليمي.

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

أساسيات REST API

تتم استضافة HumanOps REST API على api.humanops.io وتقبل أجسام طلبات JSON مع استجابات بتنسيق JSON. يتم التعامل مع المصادقة من خلال رأس X-API-Key، والذي يجب تضمينه في كل طلب. تتبع API اتفاقيات REST: POST لإنشاء الموارد، GET لقراءتها، PUT للتحديثات، وأكواد حالة HTTP القياسية لاستجابات النجاح والخطأ.

لنبدأ بالعملية الأكثر أهمية: إنشاء مهمة. تتطلب المهمة وصفاً يخبر المشغل بما يجب فعله، وموقعاً يحدد مكان إكمال المهمة، ومبلغ مكافأة بـ USDC، وموعداً نهائياً يجب إكمال المهمة بحلوله. إليك دالة TypeScript تقوم بإنشاء مهمة من خلال REST API. تأخذ الدالة معلمات المهمة، وترسل طلب POST إلى نقطة نهاية المهام، وتعيد كائن المهمة الذي تم إنشاؤه بما في ذلك معرفه الفريد وحالته ومرجع معاملة الضمان (escrow).

تتضمن استجابة إنشاء المهمة عدة حقول مهمة. يُستخدم معرف المهمة (task ID) للإشارة إلى هذه المهمة المحددة في جميع استدعاءات API اللاحقة. يشير حقل الحالة (status) إلى الحالة الحالية للمهمة، والتي تبدأ كـ POSTED عندما تكون المهمة متاحة للمشغلين لتصفحها. يشير escrow_tx_id إلى معاملة دفتر الحسابات التي نقلت الأموال من حساب إيداع وكيلك إلى حساب الضمان، مما يؤكد أن المهمة ممولة بالكامل. يسجل الطابع الزمني created_at وقت إنشاء المهمة بالضبط.

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

بناء وكيل مراقبة المطاعم

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

يتم تنظيم الوكيل حول فئة HumanOpsClient التي تغلف جميع تفاعلات API. تقوم طريقة createVerificationTask بنشر مهمة جديدة بوصف مخصص للتحقق من المطعم، بما في ذلك تعليمات محددة حول الصور التي يجب التقاطها وما يجب البحث عنه. الوصف أمر بالغ الأهمية لأنه يخبر كلاً من المشغل و AI Guardian بما يشكل إكمالاً ناجحاً. يؤدي وصف المهمة المكتوب جيداً إلى تقديم إثباتات أفضل وتحقق آلي أكثر دقة.

توضح طريقة waitForEstimate مراقبة المهام القائمة على الفحص الدوري (polling). في بيئة الإنتاج، عادةً ما تستخدم webhooks بدلاً من الفحص الدوري، ولكن الفحص الدوري أبسط لأغراض العرض ويعمل بشكل جيد للوكلاء الذين يعالجون عدداً صغيراً من المهام. تتحقق الطريقة من حالة المهمة كل ثلاثين ثانية، بحثاً عن الانتقال من POSTED إلى ESTIMATED، مما يشير إلى أن المشغل قد قدم تقديراً زمنياً وهو جاهز لبدء العمل.

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

تم دمج معالجة الأخطاء في كل استدعاء API. يتم التقاط حالات فشل الشبكة وتسجيلها برسائل ذات معنى. يتم تحليل استجابات أخطاء HTTP لاستخراج كود الخطأ ووصفه من API. تتضمن استجابات حدود المعدل (Rate limit) قيمة رأس retry-after حتى يتمكن وكيلك من التراجع بشكل مناسب. هذا الأسلوب البرمجي الدفاعي ضروري لوكلاء الإنتاج الذين يحتاجون إلى العمل بشكل موثوق دون إشراف بشري.

تكامل MCP Server

يوفر HumanOps MCP server مسار تكامل بديل قوي بشكل خاص لوكلاء الذكاء الاصطناعي الذين يعملون في بيئات متوافقة مع MCP مثل Claude Desktop و Cursor. بدلاً من إجراء طلبات HTTP وتحليل استجابات JSON، يمكن لوكيلك استدعاء عمليات HumanOps كأدوات أصلية، مما يجعل التكامل يبدو طبيعياً ويقلل من كمية الأكواد المتكررة التي تحتاج إلى كتابتها.

لإعداد MCP server، قم بتثبيت حزمة humanops-mcp-server عالمياً أو أضفها إلى تبعيات مشروعك. ثم أضف تكوين الخادم إلى ملف تكوين مضيف MCP الخاص بك. بالنسبة لـ Claude Desktop، يعني هذا إضافة إدخال إلى قسم mcpServers في التكوين الخاص بك مع الأمر لبدء الخادم ومتغير البيئة الذي يحتوي على مفتاح API الخاص بك. يتكون التكوين الكامل من ثلاثة أسطر: مسار الأمر، ومصفوفة الوسائط، وكائن env مع HUMANOPS_API_KEY الخاص بك.

بمجرد التكوين، يكتسب وكيل الذكاء الاصطناعي الخاص بك الوصول إلى أربع أدوات أساسية: post_task لإنشاء مهام جديدة مع معلمات الوصف والموقع والمكافأة والموعد النهائي؛ approve_estimate لتفويض مشغل لبدء العمل في مهمة؛ get_task_result لاسترداد المهمة المكتملة مع نتائج التحقق؛ و check_verification_status لمراقبة تقدم تحليل AI Guardian. تقبل كل أداة معلمات منظمة وتعيد استجابات محددة النوع، مما يلغي الحاجة إلى تحليل JSON يدوياً.

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

تكامل Webhook للتحديثات في الوقت الفعلي

بينما يعمل الفحص الدوري للوكلاء البسيطين، يجب أن تستخدم عمليات النشر في بيئة الإنتاج webhooks لإشعارات دورة حياة المهمة في الوقت الفعلي. ترسل HumanOps webhooks طلبات HTTP POST موقعة بـ HMAC-SHA256 إلى نقطة النهاية الخاصة بك كلما حدث حدث مهم في دورة حياة المهمة. يؤدي هذا إلى التخلص من زمن الانتقال وهدر الموارد الناتج عن الفحص الدوري ويضمن استجابة وكيلك للأحداث بأسرع ما يمكن.

لإعداد webhooks، قم بتسجيل عنوان URL لنقطة النهاية من خلال API أو لوحة التحكم. ستتلقى سراً للـ webhook يُستخدم لتوقيع جميع عمليات تسليم الـ webhook. يجب أن تتحقق نقطة النهاية الخاصة بك من توقيع HMAC في كل طلب وارد عن طريق حساب التوقيع على جسم الطلب الخام باستخدام السر ومقارنته بالقيمة الموجودة في رأس X-HumanOps-Signature. يجب رفض الطلبات ذات التواقيع غير الصالحة أو المفقودة فوراً، حيث قد تكون منتحلة.

تشمل أحداث Webhook حدث task.estimated عندما يقدم المشغل تقديراً زمنياً، و task.started عندما يبدأ المشغل العمل، و task.proof_submitted عند تحميل الإثبات، و task.verified عندما يكمل AI Guardian تحليله، و task.completed عند تحرير الدفعة. يتضمن كل حدث معرف المهمة، ونوع الحدث، وطابعاً زمنياً، وبيانات خاصة بالحدث. على سبيل المثال، يتضمن حدث task.verified درجة ثقة Guardian وتحديد النجاح أو الفشل، مما يسمح لوكيلك بمعالجة النتيجة فوراً دون إجراء استدعاء API منفصل.

يتضمن نظام تسليم webhook عمليات إعادة محاولة تلقائية مع تراجع أسي. إذا أعادت نقطة النهاية الخاصة بك كود حالة غير ٢٠٠ أو لم تستجب في غضون عشر ثوانٍ، فسيتم إعادة محاولة التسليم حتى خمس مرات مع زيادة التأخير بين المحاولات. بعد استنفاد جميع عمليات إعادة المحاولة، يتم وضع الحدث في زمام الرسائل الميتة (dead letter queue) حيث يمكن إعادة تشغيله يدوياً. يضمن ضمان الموثوقية هذا ألا يفوت وكيلك أي حدث أبداً، حتى لو تعرض خادمك لتوقف مؤقت.

مواضيع متقدمة: التجميع، الأولوية، والتحجيم

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

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

يتضمن تحجيم وكيلك من مرحلة إثبات المفهوم إلى الإنتاج عدة اعتبارات. أولاً، انتقل من الفحص الدوري إلى webhooks لتقليل زمن الانتقال واستهلاك الموارد. ثانياً، قم بتنفيذ إنشاء المهام المتماثل (idempotent) عن طريق تضمين مفتاح تماثل تم إنشاؤه بواسطة العميل مع كل طلب إنشاء مهمة، مما يمنع تكرار المهام إذا أعاد وكيلك محاولة طلب بسبب مهلة الشبكة. ثالثاً، قم بتنفيذ معالجة صحيحة للأخطاء لحدود المعدل، وعدم كفاية الرصيد، وتوقف API. رابعاً، أضف التسجيل والمراقبة حتى تتمكن من تتبع معدلات إنشاء المهام، ودرجات التحقق، وأوقات الإكمال عبر أسطول وكلاءك.

تدعم HumanOps API تقسيم الصفحات (pagination) لسرد المهام والتصفية حسب الحالة، ونطاق التاريخ، والموقع. بالنسبة للوكلاء الذين يديرون مئات المهام المتزامنة، تعد قدرات التصفية هذه ضرورية للحفاظ على سير عمل فعال. يمكنك الاستعلام عن جميع المهام في حالة ESTIMATED لمعالجة الموافقات المعلقة، وجميع المهام في حالة IN_PROGRESS لمراقبة المهام التي تقترب من مواعيدها النهائية، وجميع المهام المكتملة ضمن نطاق تاريخي لإعداد التقارير والتحليل.

تجميع كل شيء معاً

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

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

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

لبدء البناء، قم بزيارة وثائق HumanOps للحصول على مرجع API الكامل، وأدلة تثبيت SDK، وأمثلة برمجية إضافية. تتوفر بيئة الاختبار فور التسجيل دون الحاجة إلى بطاقة ائتمان. إذا كنت تفضل مسار تكامل MCP، فإن وثائق MCP server تتضمن أمثلة تكوين لـ Claude Desktop و Cursor والمضيفين المدعومين الآخرين. بالنسبة للمشغلين المهتمين بإكمال مهام التحقق وكسب USDC، يغطي دليل المشغل عملية التسجيل والتوثيق.