التشغيلات والبث

التشغيل (run) دور واحد للوكيل: يدخل المدخل، ويعمل النموذج والأدوات حتى max_tool_rounds جولة، ثم يخرج المخرج. كل سؤال ask، وكل رسالة جلسة يُجاب عنها، وكل إرسال لنتائج أدوات، ينتج تشغيلًا.

دورة الحياة

queued ──► in_progress ──► completed | failed | cancelled | superseded
                 ▲   │
                 │   ▼
           requires_action   (waiting for your client tool outputs)

• تنتقل status من queued إلى in_progress، وقد تتناوب مع requires_action، وتنتهي بحالة نهائية واحدة بالضبط.
• لا تُحدَّد outcome إلا عند انتهاء التشغيل: answered أو handed_off أو failed أو cancelled أو superseded أو client_tool_calls (الأخيرة في الواجهة المتوافقة مع OpenAI فقط). أما requires_action فحالةٌ وليست نتيجة أبدًا.
• لا صمت أبدًا. يُعاد تنفيذ خطأ المزوّد، ثم تُجرَّب نماذجك البديلة fallback_models؛ وإذا فشلت كلها يتلقى العميل رسالة الطوارئ التي كتبتها وتُحوَّل المحادثة إلى فريقك. ولا تُستخدم failed إلا حين لا يوجد مسار للتحويل أو حين تكون fallback.handoff_on_failure معطّلة.
• مشكلات الإعداد — غياب مفتاح النموذج، أو نموذج لا تشمله خطتك، أو إيقاف الذكاء الاصطناعي — ليست أعطال مزوّد: لا تُعاد محاولتها ولا تُحوَّل لموظف، وتتلقى طلبات الواجهة البرمجية 409 agent_not_ready.

كائن التشغيل

الحقل	الوصف
id وobject	run_… و"run"
agent	{id, version} — الإصدار الذي أجاب بالضبط
session_id وend_user_id	قيمتهما null في تشغيلات السؤال الواحد بلا عميل
mode وchannel	session أو one_shot أو playground؛ وapi أو widget أو playground أو openai
status وoutcome	انظر دورة الحياة أعلاه
input_message_ids	رسائل العميل التي أجاب عنها هذا التشغيل (قد تكون عدة رسائل بعد المقاطعة)
output وoutput_text	رسائل المساعد في هذا التشغيل، ونصّها مجمّعًا ("" حين لا يوجد)
handoff	null أو {id, reason_type, summary, status}
required_action	أثناء التوقف: {type: "submit_tool_outputs", tool_calls, expires_at}
error	null أو {code, message}
superseded_by	التشغيل الأحدث الذي حلّ محل هذا التشغيل
usage	{input_tokens, cached_input_tokens, output_tokens, model_calls, units, weight}
config_hash وsnapshot_hash	أي إعدادات، وأي تعليمات وقائمة أدوات مجمّدة، أنتجت هذه الإجابة
warnings	ملاحظات غير مانعة
created_at وstarted_at وcompleted_at	ثوانٍ بتوقيت يونكس

يعيد GET /v1/runs/{run} تشغيلًا، ويسرد GET /v1/runs التشغيلات، ويعيد GET /v1/runs/{run}/steps التتبع: كل استدعاء للنموذج وكل استدعاء أداة بمعاملاته ونتائجه وزمنه ورموزه (مع الإخفاء حيث تقتضي إعداداتك).

انتظار النتيجة

دون بث، تنتظر ask وmessages وsubmit_tool_outputs انتهاء التشغيل:

• wait_seconds تحدد مدة الانتظار (الافتراضي 60، والحد الأقصى 110).
• 200 حين ينتهي التشغيل، أو ينتظر نتائج أدوات جهة العميل، أو حين لا يلزم تشغيل أصلًا (وضع الموظف، أو تكرار client_message_id).
• 202 فقط حين يبقى التشغيل queued أو in_progress — لأنك أرسلت background: true أو انقضت مدة الانتظار. وتشير الترويسة Location إلى /v1/runs/{id}.

تستمر التشغيلات عند انقطاع اتصالك: انقطاع العميل لا يلغي التشغيل أبدًا. الذي يوقفه فقط POST /v1/runs/{run}/cancel (أو المقاطعة interrupt برسالة أحدث). وإلغاء تشغيل منتهٍ يعيد 409 run_already_completed.

البث

أضف "stream": true إلى ask أو POST /v1/sessions أو POST /v1/sessions/{session}/messages أو submit_tool_outputs، فتصبح الاستجابة text/event-stream. ويمكنك الاتصال ببث في أي وقت:

• بث التشغيل — GET /v1/runs/{run}/events: أحداث تشغيل واحد. ينتهي بحدث واحد بالضبط من run.completed أو run.failed أو run.cancelled أو run.superseded أو run.requires_action، ثم يغلقه الخادم.
• بث الجلسة — GET /v1/sessions/{session}/events: كل ما يحدث في الجلسة تشغيلًا بعد تشغيل، بما فيه ردود فريقك. لا يُغلق من تلقاء نفسه.

صيغة البث

id: 4185
event: message.completed
data: {"message":{"id":"msg_01k6rz8e0h2k4n6q8s0v2x4z6b","role":"assistant","content":[{"type":"text","text":"أكيد، خلال 7 أيام إذا كان مغلقًا وبتغليفه الأصلي."}]}}

: ping

• لكل حدث event: وdata: (بصيغة JSON). والأحداث الدائمة لها أيضًا id: — رقم يتزايد فقط، مشترك بين بث التشغيل وبث الجلسة.
• أحداث message.delta ليس لها id:: تُسلَّم مباشرة ولا تُحفظ ولا يُعاد إرسالها.
• يُرسَل سطر تعليق (: ping) كل 15 ثانية لمنع الوسطاء من إغلاق الاتصال.

يحتوي دليل البث في JavaScript على محلّل كامل.

قائمة الأحداث

الحدث	البيانات	ملاحظات
session.created	{session, created}	أول حدث في POST /v1/sessions مع stream: true.
run.created	{run}	أُنشئ التشغيل.
run.in_progress	{run}	بدأ الوكيل العمل عليه.
message.delta	{message_id, delta}	جزء من نص الرد. معاينة على أفضل جهد.
message.completed	{message, replaced?, discarded?, truncated?}	النص النهائي لرسالة مساعد واحدة. المرجع المعتمد.
tool_call.created	{call_id, name, arguments_preview}	استدعى النموذج أداة.
tool_call.completed	{call_id, ok, summary}	عادت الأداة بنتيجتها.
handoff.requested	{handoff}	سُجّل تحويل لموظف.
run.requires_action	{run}	توقف مؤقت: يسرد run.required_action استدعاءات أدوات جهة العميل. ينهي بث التشغيل.
run.completed	{run}	نهائي.
run.failed	{run}	نهائي؛ ويوضح run.error السبب.
run.cancelled	{run}	نهائي.
run.superseded	{run, superseded_by}	نهائي: تولّت رسالة أحدث الدور (interrupt).
message.created	{message}	في بث الجلسة: رسائل العميل الجديدة وردود فريقك العامة.
session.updated	{id, status, mode}	مثل تغيّر mode إلى human أو عودتها إلى agent.
session.closed	{session}	أُغلقت الجلسة.
handoff.assigned وhandoff.resolved وhandoff.expired وhandoff.unclaimed	{handoff}	دورة حياة التحويل، في بث الجلسة.
ticket.created وconversation.flagged		تطلقها الأدوات المدمجة.
note.created	{message}	الملاحظات الداخلية. فقط في البث الذي يفتحه فريقك، ولا تصل إلى العملاء أبدًا.
error	{code}	عطل في البث وليس فشل تشغيل: token_expired أو stream_timeout أو internal_error.

ما الذي يُعتمد عليه

• أحداث delta معاينات. قد يتأخر message.delta، أو يضيع عند إعادة الاتصال، أو ينتمي إلى محاولة تُركت.
• message.completed هو المرجع لنص الرسالة. استبدل به ما بنيته من أحداث delta:
  • discarded: true — تُركت تلك المحاولة (مثل إعادة المحاولة على نموذج آخر) وعلى العميل حذفها؛
  • replaced: true — استُبدل النص بـالرد الحرفي عند التصعيد الذي كتبته؛
  • truncated: true — نفدت رموز الرد لدى النموذج؛ فتحصل على النص الجزئي.
• أحداث run.* النهائية هي المرجع لطريقة انتهاء الدور.
• تجاهل ما لا تعرفه. تُضاف أنواع أحداث وحقول جديدة مع الوقت دون تغيير الإصدار.

مع إعداد الوكيل conversation.stream_mode: "auto" (الافتراضي)، يُجمَّع النص جولةً جولة متى كان رد التصعيد مُعدًّا، فلا يمكن أن تناقض جملة مبثوثة الردَّ الذي تفرضه سياستك.

الاستئناف بعد الانقطاع

أعد الاتصال بآخر id استلمته، في الترويسة Last-Event-ID أو في معامل الاستعلام after. ستتلقى كل حدث دائم بعده، ثم البث المباشر:

curl -N https://api.k-agent.kerneltics.com/v1/runs/run_01k6rz7d9f1h3k5n7q9s1v3x5z/events \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Last-Event-ID: 4185"

• بث التشغيل دون مؤشر يبدأ من أول التشغيل.
• بث الجلسة دون مؤشر يبدأ مباشرًا؛ و?after=0 يعيد كل ما زال محفوظًا (تُحفظ الأحداث 7 أيام).
• إعادة طلب بثّ بمفتاح عدم التكرار نفسه تعيد ربطك ببث التشغيل الأصلي من بدايته.

الأخطاء والحالات الخاصة

• الخطأ الذي يقع قبل بدء البث (مفتاح غير صالح، session_busy، خطأ تحقق) استجابة JSON عادية بحالة HTTP الخاصة بها.
• بعد بدء البث، ينتهي التشغيل الفاشل دائمًا بـ run.failed. ولا يُستخدم حدث error إلا لأعطال البث؛ وعلى العميل إعادة الاتصال مع Last-Event-ID (ومع رمز جديد في حالة token_expired).
• حين لا يلزم تشغيل — الجلسة في وضع الموظف، أو الرسالة مكررة — يرسل البث message.created ثم session.updated ثم يُغلق.
• المفاتيح القابلة للنشر ورموز العميل (المتصفحات) تتلقى مجموعة مختصرة: message.*، وrun.created|completed|failed|cancelled|superseded، وhandoff.requested، وsession.updated بالحقول {id, status, mode}، وtool_call.created بالحقلين {call_id, name}.