Agent runs

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

بدء تشغيل

POST/v1/workspaces/{workspace_id}/agent/runs —

ابدأ التشغيل. التشغيل مفصول عن الاتصال: يُرجئ هذا المُنفّذ كائن JSON صغيرًا فورًا ويستمر المحرك في العمل منفصلًا. تابع البث المباشر عبر GET …/attach (أدناه).

أبسط تكامل — حقل واحد. أرسل {"task": "…"} فقط وقد انتهيت. تُوجِّه المنصة تلقائيًا إلى أفضل نموذج، وتختار وتستدعي الأدوات المناسبة تلقائيًا (بحث الويب، قاعدة معرفتك، الكود، المتصفح…)، وتُدفّق النتيجة عائدًا. لا تحتاج أبدًا إلى توصيل الأدوات أو النماذج أو الـ prompts بنفسك — كل حقل آخر أدناه هو تجاوز اختياري عندما تريد مزيدًا من التحكم. راجع Cookbook لأمثلة جاهزة للنسخ.

يُرجع POST الكائن {"run_id", "trace_id"} — معرّف التشغيل هو كل ما تحتاجه لمتابعته. انقطاع العميل لا يُلغي التشغيل أبدًا؛ الفوترة والاستمرارية والإجابة النهائية تصل دائمًا.

مطلوب:

task — ماذا يفعل، باللغة الطبيعية (حتى 20,000 حرف). هذا هو الحقل الوحيد الذي يجب إرساله.

اختياري (لها جميعًا قيم افتراضية معقولة — تجاوزها فقط عند الحاجة):

model — تركه فارغًا يتيح للمنصة اختيار مشغّل يدعم الأدوات. ثبّته فقط لإجبار تحديد نموذج معيّن.
max_steps — سقف لعدد تكرارات الأداة/التفكير (1–50).
budget_usd — سقف تكلفة صارم (> 0، حتى 100).
pro — يفتح تفكيرًا أعمق ومتعدد الخيوط (sub-agents متوازية على المهام المعقدة).
project_id — تشغيل مع تعليمات وملفات مشروع مُحقنة كسياق.
conversation_id — ربط هذا التشغيل تحت محادثة قائمة بالفعل (تُكتب النتيجة مرة أخرى إلى ذلك الموضوع). احذفه لمهمة مستقلة.
skills — الـ slugs لـ skills التي اختارها المستخدم صراحةً (حتى 8)؛ تركه فارغًا يُشغّل الخط الأساسي النقي (لا تُرفق المهارات تلقائيًا أبدًا).
persona_slug — دور متخصص من مكتبة agency-agents؛ يُحقن كرأس هوية لهذا التشغيل. واحد على الأكثر.
history — الأدوار الأخيرة ({role, content}، حيث role هو user أو assistant) لاستمرارية الأدوار. يُهمَل عند ضبط conversation_id (تُعاد بناء السجل حينها من جانب الخادم).
mode — تلميح مسار المؤلّف (auto يتيح للموجّه اختيار chat / agent / cowork / code). يُستشار فقط عند تفعيل الموجّه الموحّد.
approval_mode — الموقف من الإجراءات الخطرة على الجهاز المحلي: ask (الافتراضي، يتوقف لموافقة المستخدم) أو auto (يعمل دون توقف).

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "قارن جداول رسوم Wise و Airwallex؛ وأخرج جدولًا.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

متابعة التشغيل (Server-Sent Events)

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/attach —

تابع بث أحداث التشغيل (text/event-stream). كل إطار هو كائن JSON واحد على سطر data:.

إنه آمن عند إعادة الاتصال: يحمل سطر id: معرّف إدخال بث، لذا يتتبّع EventSource القيمة lastEventId أصليًا ويعيد إرسالها كـ Last-Event-ID عند إعادة الاتصال — تحديث الصفحة، أو انقطاع الـ WiFi، أو جهاز ثانٍ يفتح التشغيل، يُستأنف تمامًا من حيث توقف (تُعاد الإطارات المتراكمة من آخر معرّف رأيته). يُغلق المُولّد بعد الإطار النهائي للتشغيل؛ تحصل الفترات الخاملة على نبضة : ping حتى لا تُسقط البروكسيات الاتصال.

أنواع الأحداث type:

type	الحقول	متى
`step_start`	`step_no`	بدأت تكرار حلقي
`llm_delta`	`step_no`, `text`	نص نموذج مُدفّق
`reasoning` / `reasoning_delta`	`step_no`, `text`	سلسلة تفكير الخطوة (كاملة عند نهاية الدور؛ تُدفّق الـ deltas مباشرة)
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	طلب النموذج أداة (تُدفّق الـ deltas الوسائط)
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	أداة طويلة تُبلّغ عن تقدّم مرحلي
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	انتهت أداة (قد تحمل `artifacts`, `sources`, `screenshot_url`)
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	إجراء محلي خطر ينتظر (أو حصل على) قرار المستخدم
`step_end`	`step_no`, `cost_usd`	اكتمل التكرار
`context_compacted`	`step_no`, `summary`	دُمجت الأدوار القديمة في ملخص لتناسب نافذة السياق
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	نهائي — الإجابة النهائية في `final_text`
`error`	`message`	فشل نهائي

يحمل كل حدث أيضًا run_id (وstep_no) بحيث يستطيع المستهلك المتعدد الإرسال توجيه الإطارات دون حالة لكل اتصال. ينتهي البث بالإطار النهائي run_end (أو error) — لا يوجد حارس [DONE].

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs/$RUN_ID/attach \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# id: 1719900000-0
# data: {"type":"step_start","run_id":"…","step_no":1}
# id: 1719900000-1
# data: {"type":"llm_delta","run_id":"…","step_no":1,"text":"…"}
# …
# data: {"type":"run_end","run_id":"…","status":"succeeded","final_text":"…",…}

فضّل GET …/attach على إعادة POST: فهو قابل للاستئناف من Last-Event-ID، لذا لن تفقد العملاء الذين يعيدون الاتصال أي إطار. يستمر التشغيل سواء كان أحدهم متصلًا أم لا.

إدارة عمليات التشغيل

GET/v1/workspaces/{workspace_id}/agent/runs —

سرد التشغيلات (معاملات الاستعلام: limit, project_id, scheduled_only, include_archived).

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

جلب واحد: الحالة، final_text المُستمر، مسار steps الكامل، التكلفة، والـ artifacts المُنتَجة.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/cancel —

إيقاف مهمة قيد التشغيل. تعاوني وعبر الـ workers (يضبط علمًا يفحصه الحلقة عند حدّ الخطوة التالي)؛ idempotent — إلغاء تشغيل مُنتهٍ هو لا-عملية ويُرجع حالته النهائية.

PATCH/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

تحرير إدخال الأخيرة: title, archived, favorited, أو نقله إلى project_id (قيمة project_id بـ null تُخرجه).

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

حذف تشغيل من السجل (تُحذف خطواته تسلسليًا). ألغِ التشغيل الجاري أولًا.

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/artifacts.zip —

تنزيل كل artifact أنتجه التشغيل كـ .zip واحد.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

إنشاء / إبطال رابط إعادة تشغيل عام للقراءة فقط (الجسم: expires_in_days اختياري).

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/approvals/{approval_id} —

الرد على موافقة إجراء محلي خطر (الجسم: {approved: true|false})، النوع الذي يُظهره حدث approval_request.

حالة التشغيل

قيمة run_end.status (وكذلك GET …/runs/{run_id}) تكون واحدة من pending, running, succeeded, failed, cancelled, أو partial (انتهت المهمة بنتيجة جزئية لا تزال مفيدة). الحالات النهائية هي succeeded, failed, cancelled, و partial.

تأتي الملفات التي يُنتجها الـ agent (مستندات، جداول، شرائح، رسوم بيانية، تطبيقات ويب) كـ artifacts على التشغيل. يُقيّد التشغيل كلٌّ من budget_usd ورصيد مساحة العمل، لذا لا يمكنه الانفلات أبدًا.