Phase 19: Capstone Projects

عقد العميل " هيرنيس لوب "

الحزام هو الوكيل، النموذج هو معالج، هذه الدروس تجمد عقد الحلقة يمكنك توصيل أي نموذج.

Type: Build

Languages: Python

Prerequisites: Phase 13 lessons 01-07, Phase 14 lesson 01

Time: ~90 minutes

أهداف التعلم

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

الإطار

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

هذه الدروس تبني العقد. نسمي ستة دول، عشرة مواضيع الرمز، نقطة سحب اثنين، 11 نوع من الأحداث، ومغلفة ميزانية. كل شيء آخر في الحزمة (سجل الأدوات، نقل JSON-RPC، المرسل، المخطط) وصل إلى هذا الشكل.

الولايات

الحلقة لديها ستة حالات، خمسة نشطة، واحدة هي نهاية.

stateDiagram-v2
    [*] --> IDLE
    IDLE --> PLANNING: run(goal)
    PLANNING --> EXECUTING: plan committed
    EXECUTING --> AWAITING_TOOL: tool_call needed
    AWAITING_TOOL --> REFLECTING: result
    EXECUTING --> REFLECTING: no_tool step done
    REFLECTING --> EXECUTING: next step
    REFLECTING --> PLANNING: replan
    REFLECTING --> DONE: goal_met
    PLANNING --> DONE: no_plan
    DONE --> [*]

IDLEهو نقطة دخول قانونية الوحيدةDONEهو الخروج القانوني الوحيدAWAITING_TOOLهي الحالة الوحيدة التي تنتج نقطة جذب. كل انتقال آخر داخلي.

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

الموضوعات المعلقة

المكعبات هي خياطة المشغل في الحلقة. يطلق الحزام عشرة مواضيع. يقبل كل موضوع أي عدد من المشتركين. يقوم المشتركون بإطلاق النار في ترتيب التسجيل. يمكن للمشترك تغيير الحمل المفيد، أو رفع لوقف التحول، أو إعادة حارس لتفوت الخطوة التالية.

textbefore_plan         after_plan
before_tool_call    after_tool_call
before_step         after_step
on_error
on_pause
on_budget_exceeded
on_complete

الشكل يعكس ما تجمع عليه كلود كود، كورسور، وOpenCode بحلول منتصف عام 2025 . الأسماء وظيفية، وليس علامة تجارية.rm -rfيعيش فيbefore_tool_call. العنق الذي يُرسل فترة OpenTelemetry يعيش فيafter_step. المُربّط الذي يستأنف جلسة توقف يعيش فيon_pause. . .

نقاط السحب

الحلقة تُعطى التحكم مرتينAWAITING_TOOLعندما لا يمكن أن تتقدم دون نتيجة أداة.on_pauseعندما يتم استنفاد الميزانية أو يطلب المُساعدة صراحة مراجعة بشرية.

نقطة السحب ليست استثناء إنها عودة، المُتصل يفتش حالة الحزام، ويحضر ما طلبه الحزام، ويتصلresume(payload).الخطوط تتحمل حيث توقفت. هذا هو نفس الشكل مثل مولد Python. النقل عبر نقطة السحب هو اختيارك. في TUI هو المفاتيح. على MCP هوtools/callفوق صف، إنه استطلاع عمل

سلسلة الأحداث

يرفع الحلقة الأحداث إلى سلسلة مدرجة في نقاط معينة في العقد. يتم إضافة التدفق فقط والمتمثلين يمكنهم إعادة تشغيلها من أي تعويض. أنواع الأحداث الـ11 المطبقة هي:

  • session.startإصدار مرة واحدة عندماrun(goal)يُدعى
  • plan.draft يتم إصدارها عندما يعيد المخطط مسودة خطة
  • plan.commit الصادر بعد أن يتم التزام مشروع الخطة النشطة
  • step.start يتم إصدارها في بداية كل خطوة تنفيذية
  • step.end يتم إصدارها في نهاية كل خطوة تنفيذية
  • tool.call يتم إصدارها عندما تتيح خطوة تتطلب أداة التحكم للمدعو
  • tool.result إصدار في سيرته الذاتية مع نتيجة أداة
  • tool.error إصدار في سيرته الذاتية مع خطأ أو عندما يقطع الرابط المكالمة
  • budget.warn يتم إصدارها عند الوصول إلى حد موازنة
  • session.pause يتم إصدارها عندما يصل الحلقة إلى توقف (ميزانية أو خطوة)
  • session.complete يتم إصدارها مرة واحدة عندما يصل الحلقة DONE

الأحداث لا تكرر حمولات الركبة. الحركات الضرورية (التغيير، الإجراءات المنسخة). الأحداث الملاحظة (الاستقبال، السفينة). تعاملها كحاملة.

ملف الموازنة

في جلسة واحدة، هناك ثلاثة حدود. عدد الدوران، عدد الدعوات الأداة، ثواني الساعة الحائطية. كل دور يتحول من خلال واحد. كل دفة يدعو الدعوات الدعوات الأداة يدعو واحد. يتم التحقق من الساعة الحائطية في كل انتقال الحالة. عندما يتم الوصول إلى أي حد، يبدأ الحلقة في الإطلاقon_budget_exceeded، يُصدّرbudget.warn، ثم الانتقال إلىIDLEمع سبب يتجاوز الميزانية في نقطة التقطير التالية.

الميزانية ليست مفاجأة، إنها عائدة، المُتصل يقرر ما إذا كان سيتم تمديد الميزانية و استئنافها، أو إنهاء الجلسة.

ما لا يفعله هذا الدروس

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

المخطط الحاسم فيmain.pyهو بديل. يعيد خطة مدمجة بقوة من ثلاث خطوات، اثنان منها تتطلب نتيجة أداة. النقطة هي الحلقة، وليس الخطة.

كيفية قراءة الرمز

HarnessLoopهو الطبقة الرئيسية، يحمل الحكومة، يحرق الركوب، ينشر الأحداث.Budgetتتبع حدودEventهو الغلاف المخطط على التيار.HookRegistryهو طاولة الإرسال_transitionهو الوظيفة الوحيدة التي تغير الحالة، لذلك آلة الحالة غير متغيرة يعيش في مكان واحد.

اقرأmain.pyمن أعلى إلى أسفل، ثم اقرأcode/tests/test_loop.pyالاختبارات تحدد كل انتقال وكل ترتيب إطلاق الرماية

الذهاب إلى أبعد

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

في الدروس التالية يضاف سجل الأدوات بعد ذلك ، نقل JSON-RPC بعد ذلك ، المرسل. من الدروس الرابعة والعشرين ، فإن الحلقة في هذا الملف سوف تعمل خطة حقيقية ضد الأدوات الحقيقية مع ميزانيات حقيقية تطبق.

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.