انتقل إلى المحتوى

تنسيق عمل الوكلاء

عرض بتنسيق Markdown التعديل على GitHub التوثيق في 2cc7b2b

يناسب Queuety أنظمة الوكلاء عندما تريد عملًا تكيفيًا مع الحفاظ على الحالة الدائمة، وإعادة المحاولة، والفحص، ودلالات انتظار واضحة.

لا تحتاج معظم تدفقات الوكلاء إلى محرك DAG قابل للتعديل أثناء التشغيل. عمليًا، يمكن نمذجة معظم الأنظمة بمجموعة صغيرة من عمليات التنسيق الدائمة. يوسّع for_each() العمل ضمن تنفيذ سير عمل واحد. ويسلّم start_agents() وwait_for_agents() العمل المكتشف أثناء التشغيل إلى تدفقات عمل مستقلة من المستوى الأعلى. ويتوقف wait_for_decision() وwait_for_input() لإتاحة التحكم البشري. ويتيح wait_for_workflow() وwait_for_workflows() وwait_for_agent_group() لتنفيذ واحد من المستوى الأعلى الانتظار حتى يكتمل تنفيذ آخر أو نصاب مُبدوء.

نموذج ذهني مفيد

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

الفرق المهم هو أن الوكيل يقرر العمل الذي ينبغي إنجازه، لكن Queuety يظل مسؤولًا عن كيفية حفظ ذلك العمل وإعادة محاولته واستئنافه وتجميعه. عندما يكون هدف التنسيق جلسة طويلة الأمد بدلًا من تنفيذ محدد المدة، أقرن ذلك بـ State Machines.

النمط 1: مخطط/منفّذ مع عمليات تنفيذ مستقلة للوكلاء

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

PHP
use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$agent_run = Queuety::workflow( 'agent_run' )
    ->then( FetchSourcesStep::class )
    ->then( DraftFindingStep::class );

Queuety::workflow( 'brief_research' )
    ->version( 'brief-research.v1' )
    ->idempotency_key( 'brief:42:research' )
    ->max_transitions( 20 )
    ->then( PlanResearchTasksStep::class )
    ->start_agents( 'agent_tasks', $agent_run, group_key: 'researchers' )
    ->wait_for_agent_group( 'researchers', WaitMode::Quorum, 2, 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

في هذا النمط، يكتب PlanResearchTasksStep العناصر المكتشفة أثناء التشغيل إلى $state['agent_tasks']، ويرسل start_agents() سير عمل دائمًا واحدًا لكل مهمة، ويوقف wait_for_agent_group() العملية الأم مؤقتًا حتى يتحقق شرط الإكمال المحدد. ثم يتلقى SynthesizeBriefStep حالات العمليات الفرعية المكتملة ضمن $state['agent_results'].

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

النمط 2: مراجعة بشرية قبل متابعة التنفيذ

استخدم wait_for_decision() عندما ينبغي لسير العمل التوقف بانتظار قرار فعلي بالموافقة أو الرفض، واستخدم wait_for_input() عندما يحتاج المشغّل إلى إرسال ملاحظات منظّمة إلى التنفيذ.

PHP
use Queuety\Queuety;

$workflow_id = Queuety::workflow( 'brief_review' )
    ->then( DraftBriefStep::class )
    ->wait_for_decision( result_key: 'review' )
    ->then( HandleReviewDecisionStep::class )
    ->wait_for_input( result_key: 'revision_notes' )
    ->then( ApplyRevisionNotesStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

إذا وافق المراجع:

PHP
Queuety::approve_workflow(
    $workflow_id,
    [
        'reviewer' => 'editor@example.com',
        'notes' => 'Looks good, publish after legal check',
    ],
    'approved'
);

إذا رفض المراجع:

PHP
Queuety::reject_workflow(
    $workflow_id,
    [
        'reviewer' => 'editor@example.com',
        'reason' => 'Needs citations and a stronger conclusion',
    ],
    'rejected'
);

بعد wait_for_decision()، يتلقى سير العمل حمولة منظّمة تتضمن النتيجة النهائية، والإشارة التي استأنفت التشغيل، وأي بيانات مراجعة وردت معها. يتيح لك ذلك إنشاء نقطة تحقق فعلية بمشاركة الإنسان، دون إبقاء عملية PHP مفتوحة أثناء انتظار التشغيل.

النمط 3: سير عمل واحد في المستوى الأعلى ينتظر سير عمل آخر

أحيانًا يكون النموذج الأنسب هو تجنب سير عمل واحد ضخم. يمكن لسير عمل أن يُنهي البحث، بينما ينتظره سير عمل آخر قبل بدء المرحلة التالية.

PHP
use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$research_id = Queuety::workflow( 'research_brief' )
    ->then( PlanResearchTasksStep::class )
    ->start_agents( 'agent_tasks', $agent_run )
    ->wait_for_agents( mode: WaitMode::All, result_key: 'agent_results' )
    ->then( SynthesizeBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

Queuety::workflow( 'publish_brief' )
    ->wait_for_workflow( $research_id, 'research' )
    ->wait_for_decision( result_key: 'editor_review' )
    ->then( PublishBriefStep::class )
    ->dispatch( [ 'brief_id' => 42 ] );

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

اختيار البدائية المناسبة

for_each() هي الأداة المناسبة عندما يكون العمل جزءًا من تشغيل سير عمل واحد، وتكون الفروع مجرد تنفيذ متوازٍ على مستوى الخطوات يستخدم حقيبة حالة مشتركة واحدة.

start_agents() أفضل عندما ينبغي أن تكون كل مهمة مكتشفة تشغيلًا مستقلًا ودائمًا في المستوى الأعلى، وعندما تريد فحص هذه التشغيلات أو إعادة محاولتها أو تصديرها بشكل منفصل.

wait_for_workflow() وwait_for_workflows() مناسبتان عندما يعتمد سير عمل في المستوى الأعلى على سير عمل آخر في المستوى نفسه، وتريد تنسيقًا غير متزامن ودائمًا بين طبقتي التنسيق.

wait_for_decision() وwait_for_input() مناسبتان للنقاط التي يحتاج فيها شخص إلى الموافقة على التشغيل أو رفضه أو توجيهه، بينما يظل سير العمل متوقفًا مؤقتًا دون استهلاك سعة العمال.

اصطلاحات مقترحة للحالة

يسهل تصحيح أخطاء أنظمة الوكلاء عندما تكون مفاتيح الحالة متوقعة. عمليًا، يعمل agent_tasks جيدًا لمخرجات المخطط، وagent_workflow_ids للتشغيلات التي بدأت في المستوى الأعلى، وagent_results لحالة سير عمل فرعي مكتمل، وreview أو decision لحمولات الموافقة أو الرفض. عادةً ما يكون تخزين المخرجات الكبيرة، مثل المسودات والاستشهادات وبيانات البحث، في مخزن العناصر أفضل من وضعها في حقيبة حالة سير العمل الرئيسية.

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

PHP
Queuety::workflow( 'agent_research' )
    ->version( 'agent-research.v2' )
    ->idempotency_key( 'brief:42:agent-research' )
    ->max_transitions( 20 )
    ->max_for_each_items( 12 )
    ->max_state_bytes( 32768 );

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

راجع أيضًا