كيف تعمل PROMIVO

الوكلاء والإصدارات

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

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

الصلاحيات والمخاطر

كل أداة تعلن مستوى مخاطرتها. وكل إصدار وكيل يعلن أعلى مستوى يجوز له تنفيذه دون إنسان.

• READالجلب والبحث والتلخيص. لا يغيّر شيئًا.
• WRITEإرسال بريد، أو نشر تحديث، أو إضافة سجل أو تعديله.
• DESTRUCTIVEحذف بيانات أو إنفاق أموال.

نداء أداة فوق السقف يُرفض، ويُسجَّل كمهمّة تنتظر الموافقة، ويُبلَّغ النموذج بأنه لم يُنفَّذ. تستمرّ التشغيلة؛ والأثر الجانبي لا يحدث.

عقد مسار العمل

القوالب

إعداد العقدة يدرج قيمًا من سياق التشغيل. ولا يوجد تقييم للتعابير، فلا يستطيع القالب تنفيذ أي شفرة أبدًا.

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

واجهة برمجية عامة

أنشئ مفتاحًا محدود النطاق من صفحة مفاتيح الواجهة. يُعرض السرّ مرة واحدة، ولا يُخزَّن إلا تجزئته.

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

كل استجابة تستخدم الغلاف نفسه:

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

نقاط النهاية

• GET /api/agents
• POST /api/agents/run
• GET /api/workflows
• POST /api/workflows
• POST /api/workflows/:id/run
• GET /api/executions
• GET /api/executions/:id
• GET /api/usage

مشغّلات خطّاف الويب

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

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }