Phase 14: Agent Engineering

حلقات ردود الفعل في الوقت الذي يتم تشغيلها فيه

العملاء الذين لا يرون خروج الأوامر الحقيقية تخمين. ركن ردود الفعل يلتقط stdout ، stderr ، رمز الخروج ، والتوقيت في سجل مهيكلي يمكن أن يقرأ الجولة التالية. ثم يتفاعل العميل مع الحقائق بدلاً من التنبؤ به الخاص بالحقائق.

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 14 · 32 (Minimal Workbench), Phase 14 · 35 (Init Script)

Time: ~50 minutes

أهداف التعلم

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

المشكلة

يقول الوكيل "تجربة الآن". الرسالة التالية تقول "كل الاختبارات تمر". الحقيقة هي أنه لم يتم إجراء أي اختبار. الوكيل تخيل الخروج، أو قام بإجراء الأمر ولم يقرأ النتيجة، أو قرأ النتيجة وقطع خط الفشل بصمت.

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

المفهوم

flowchart LR
  Agent[Agent Loop] --> Runner[run_with_feedback.py]
  Runner --> Shell[subprocess]
  Shell --> Capture[stdout / stderr / exit / duration]
  Capture --> Record[feedback_record.jsonl]
  Record --> Agent
  Record --> Gate[Verification Gate]

ما الذي يذهب في سجل المراجعة

Field	Why it matters
`command`	Exact argv, no shell expansion surprises
`stdout_tail`	Last N lines, deterministic truncation
`stderr_tail`	Last N lines, separate from stdout
`exit_code`	The unambiguous success signal
`duration_ms`	Surfaces slow probes and runaway processes
`started_at`	Timestamp for replay
`agent_note`	One line the agent writes about what it expected

التقطيع هو تحديد

سجل 50 ميغا بايت يدمّر الحلقة....truncated N lines...لا يوجد عينة، الأجزاء التي يحتاج الوكيل لرؤيتها (خطأ نهائي، ملخص نهائي) تعيش في الذيل.

ردود الفعل مقابل التلفاز

التلفاز (مرحلة 14 · 23 ، اتفاقيات OTel GenAI) هي للمشغلين البشريين الذين يراجعون الركوبات عبر الزمن. تعود المعلومات إلى الجولة التالية من هذه الركوبات. يشتركون حقلًا ولكنهم يعيشون في ملفات مختلفة مع احتفاظ مختلف.

رفض التقدم دون ردود الفعل

إذا كان الجاري يخطئ قبل أن يلتقط الخروج ، فإن السجل يحمل exit_code: nullوerror: <reason>يجب أن يرفض حلقة العملاء المطالبة بالنجاح فيnullلا خروج، لا تقدم

بناءها

code/main.pyتطبيقات:

run_with_feedback(command, agent_note)هذا يُغلفsubprocess.run، يحتوي على التوقف/التخفيض/الخروج/مدة، يختصر بشكل محدد، يضاف إلى feedback_record.jsonl. . .
محمول صغير ينشر JSONL إلى قائمة Python.
عرض تجريبي يدير ثلاثة أوامر (نجاح، فشل، بطيء) ويطبخ آخر سجل لكل أوامر.

إشغله

python3 code/main.py

الناتج: ثلاثة سجلات تعليقات ضمنت إلى feedback_record.jsonl، آخر واحد من كل خط مطبوع. التسلل الملف عبر إعادة التشغيل لرؤية الحلقة تتراكم.

أنماط الإنتاج في البرية

ثلاثة أنماط تقسيم الجاري بما فيه الكفاية للشحن.

Redact at write, not at read.أي سجل يلمس stdout أو stderr يمكن أن تسرب أسرار. يرسل الجاري مرسلة تحرير قبل إضافة JSONL: خطوط شريط مطابقة ^Bearer ،password=،api[_-]?key=،AKIA[0-9A-Z]{16}(أو إس)xox[baprs]-(سلاك) إصدار في وقت القراءة هو سلاح قدم، الملف على القرص هو ما يصل إليه المهاجم. مراجعة أنماط إصدار ربع سنوي ضد الأشكال السرية الملاحظة في وقت تشغيل الإنتاج.

Rotation policy, not a single file.كابfeedback_record.jsonlعند 1 MB لكل ملف ، عند الإفراط في التدفق ، قم بتدوير .1،.2، ألق.5. حلقة الوكيل يقرأ فقط الملف الحالي، لذلك تكلفة وقت تشغيل محدودة. تخزين الأثاث CI يحصل على مجموعة كاملة المدوارة. دون دوران الملف يصبح عنق الزجاجة في كل مكالمة محمول.

Parent-command id for retry chains.كل سجل يحصلcommand_id؛ محاولات إعادة حملparent_command_idوإذا لم يكن هناك أي اتصال، فإن المحاولات الثانية تبدو وكأنها نجاحات مستقلة، ويخفي المراجعة تاريخ الفشل.

استخدمها

أنماط الإنتاج:

Claude Code Bash tool.الأداة تمكن بالفعل من التقاط stdout ، stderr ، الخروج ، ومدة. الجاري في هذا الدروس هو المكافئ الإطار-الجهادية لأي منتج وكيل.
LangGraph nodes.لف أي عقدة القذيفة في المتدرب حتى يسجل خارج حالة الرسم البياني.
CI logs.قم بتوصيل JSONL إلى متجر الأثاث الخاص بك ؛ يمكن للمراجعين إعادة تشغيل أي أمر دون إعادة تشغيل الجلسة.

المركض هو غلاف رقيق ينجو من كل هجرة إطار لأنه يملك شكل السجل.

أرسله

outputs/skill-feedback-runner.mdيخلق مشروع محدد run_with_feedback.pyمع ميزانية التخفيض المناسبة، كاتب JSONL متصل بمكتب العمل، ومركز تحميل يقرأه الوكيل في كل اتجاه.

التمارين

إضافةcwdحقل لكل سجل بحيث يتم التمييز بين نفس الأوامر التي تم تشغيلها من إداريات مختلفة.
إضافةredactionخطوة تسقط خطوط متطابقة^Bearer أوpassword=اختبار على سجلات العجلة
إجمالي القيمةfeedback_record.jsonlحجم 1 MB عن طريق التناوب إلى .1،.2الملفات، الدفاع عن سياسة التدوير
إضافةparent_command_idلذا تجرب سلسلة أخرى مرئية: أي أمر أنتج المدخل الذي استهلكه الأوامر التالية.
قم بتوصيل JSONL إلى TUI صغير يسلط الضوء على أحدث الخروج غير الصفر. ثمانية ميزات رئيسية يجب أن تظهر TUI لتكون مفيدة في مراجعة.

الشروط الرئيسية

Term	What people say	What it actually means
Feedback record	"Run log"	Structured JSONL entry with command, output, exit, duration
Tail truncation	"Trim the log"	Deterministic head+tail capture so records fit in token budget
Refuse-on-null	"Block on missing data"	The loop must not advance when `exit_code` is null
Agent note	"Expectation tag"	The one-line prediction the agent writes before reading the result
Telemetry split	"Two log files"	Feedback for the next turn, telemetry for the operator