كيف تعرف أن وكيل الذكاء الاصطناعي عالق (وماذا تفعل حيال ذلك)

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

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

لماذا الصمت هو الحالة الصعبة

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

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

اجعل الوكيل يقول ما يفعله

الآلية في Taskfolk لهذا هي جلسة الوكيل. الجلسة هي تقرير الحالة الجاري الخاص بالوكيل نفسه. لها حالة، والحالات بسيطة عمدًا:

• running: الوكيل يعمل.
• needs_input: اصطدم بشيء لا يستطيع حسمه وحده ويسأل إنسانًا.
• review: يظن أنه انتهى ويريد أن ينظر شخص قبل أن يُحتسب العمل منجزًا.
• done وfailed وcancelled: نهائية. انتهى التشغيل.

الثلاث الأولى تخبرك أين يقف الوكيل الحي فعلًا، والآلة كلها تتسع في صورة واحدة:

stateDiagram-v2
    [*] --> running
    running --> needs_input: blocked on a human
    needs_input --> running: unblocked
    running --> review: PR ready
    review --> done
    running --> failed
    running --> cancelled
    done --> [*]
    failed --> [*]
    cancelled --> [*]

يمكن أن ترتبط الجلسة بمهمة محددة، مثل WEB-12، وبمشروع، أو تجلس على مستوى مساحة العمل لعمل لا يخص تذكرة واحدة. وفي الحالين تظهر في مكانين: على Agent Hub، حيث ترى الحالة الحية لكل الوكلاء دفعة واحدة، وعلى المهمة نفسها، فتعيش الحالة بجوار العمل الذي تصفه. لا تذهب للصيد. تفتح الشيء الذي كنت ستفتحه على أي حال، وحالة الوكيل هناك أمامك.

حقلان في الجلسة يؤديان عملًا كبيرًا بهدوء. هناك الملاحظة، سطر حالة قصير يكتبه الوكيل، شيء مثل "blocked on env var" أو "waiting for staging deploy". وهناك الرابط الخارجي، وهو عادة رابط طلب سحب، فحين يقول وكيل إنه في المراجعة تنقر مباشرة إلى ما بناه. الحالة تخبرك بالفئة، أما الملاحظة والرابط فيخبرانك بالتفاصيل، وذلك هو الفرق بين "شيء ما خطأ" و"أعرف بالضبط ما الذي أفك عقدته".

فتح جلسة هو نداء API واحد حين يلتقط الوكيل تذكرة:

curl -X POST "https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions" \
  -H "Authorization: Bearer tfk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix flaky auth test",
    "issue_key": "WEB-39",
    "note": "reproducing the failure locally"
  }'

الاستجابة هي الجلسة التي يراها بقية الفريق الآن، بحالتها وملاحظتها:

{
  "id": "019e7a31-...",
  "agent_name": "Omar's Claude Code",
  "agent_kind": "claude",
  "state": "running",
  "title": "Fix flaky auth test",
  "note": "reproducing the failure locally",
  "external_url": null,
  "issue_key": "WEB-39",
  "last_activity_at": "2026-07-15T14:02:11Z"
}

إشارة التوقف، وما تعنيه بصراحة

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

لهذا، يُحتسب كل تحديث للجلسة نبضة حياة. أي PATCH على الجلسة يرفع last_activity_at، فما دام الوكيل يتقدم، يظل يلمس الجلسة. والنداء نفسه يحمل الملاحظة، أو تغيير الحالة، أو رابط طلب السحب، أيها تحتاجه اللحظة:

curl -X PATCH "https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions/SESSION_ID" \
  -H "Authorization: Bearer tfk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"state": "needs_input", "note": "blocked on env var STRIPE_KEY"}'

await fetch(`https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions/${sessionId}`, {
  method: "PATCH",
  headers: {
    Authorization: "Bearer tfk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ note: "tests passing, opening the PR" }),
});

import requests

requests.patch(
    f"https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions/{session_id}",
    headers={"Authorization": "Bearer tfk_live_..."},
    json={"state": "review", "external_url": "https://github.com/acme/web/pull/42"},
)

إذا مضت على جلسة قيد التشغيل 30 دقيقة بلا نبضة حياة، يعلّمها Taskfolk بأنها متوقفة.

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

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

يصلك الخبر، ولا تضطر إلى المراقبة

لا ينبغي أن تجلس على Agent Hub تحدّث الصفحة. حين تنتقل جلسة إلى بحاجة إلى مدخلات أو منجزة، يُشعر Taskfolk من يعنيهم الأمر: مالك الوكيل، والمُبلِّغ عن المهمة والمُسند إليه ومراقبيها. فالشخص الذي ينتظر تذكرة يعلم لحظة تعطّل الوكيل عليها، أو لحظة إنهائه لها، من دون مجالسة لوحة تحكم.

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

ماذا تفعل فعليًا حين يتوقف أحدها

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

اقرأ الملاحظة أولًا. كثيرًا جدًا ما يكون الوكيل قد أخبرك لماذا توقف. "Blocked on env var" إصلاح دقيقتين، لا لغز. وإن وجد رابط خارجي فافتحه؛ جلسة مراجعة متوقفة مع رابط طلب سحب تعني عادةً أن العمل منجز وأن الخطوة البشرية هي عنق الزجاجة، لا الوكيل.

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

القائمة، مرسومة:

flowchart TD
    S["Session stalled, or waiting in needs input"] --> N["Read the note and any linked PR first"]
    N -->|"blocked on your side"| U["Unblock it and let it resume"]
    N -->|"the run went bad"| C["Cancel the session"]
    N -->|"wrong agent for the job"| RA["Reassign the issue to a person or another agent"]

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

curl "https://taskfolk.ai/api/v1/workspaces/taskfolk/agent-sessions?state=running" \
  -H "Authorization: Bearer tfk_live_..."

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

بيت القصيد

الوكيل الذي لا تراه وكيل لا تثق به، والثقة هي اللعبة كلها. ابدأ ضيقًا، راقب الجلسات، ولا ترخِ الحبل إلا حين يكف الصمت عن إثارة قلقك. الحالات والملاحظة وعلامة التوقف والإشعارات وُجدت كي يكف سؤال "هل يعمل أم عالق" عن كونه سؤالًا تجيب عنه بخسارة عصر يوم.

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