OPENAI_API_KEY للـ model المستخدم هنا)، ومجلد مشروع تشغّله فيه. الملف الجاهز في آخر الخطوة 5، وتشغّله هكذا npx tsx coding.ts "Fix the failing test".
1. أعطِ الـ agent workspace
الـ workspace مجلد يعمل فيه الـ agent.NodeWorkspace هو نظام الملفات والـ shell لها، وcreateFsTools() وcreateShellTool() تحوّل الـ workspace إلى tools.
root مهم: كل path يمرّره الـ model ينحصر داخله، و.. والمسارات المطلقة وحروف الأقراص مرفوضة (راجع نموذج الأمان). شغّل البرنامج من مجلد المشروع واستخدم process.cwd() كـ root، وبهذا لا تصل file tools إلى أي شيء خارج المشروع.
يرى الـ model سبع tools: read_file وwrite_file وedit_file وlist_dir وglob وgrep من createFsTools()، وshell من createShellTool(). وسيطاتها وخياراتها في Workspace tools.
2. حدّد ما يحتاج approval
أي tool عليهاneedsApproval توقف الـ run قبل التنفيذ، لكي يقرر إنسان. القراءة لا ضرر فيها، فاطلب approval (موافقة) على file tools التي تغيّر شيئًا فقط، بخريطة لكل tool. وللـ shell مرّر predicate (دالة تعيد true أو false) على نص الأمر، واطلب approval على الأوامر التي تعتبرها خطرة فقط.
needsApproval: true)؛ الـ predicate أعلاه يجعل أي شيء آخر، مثل npm test أو git status، يعمل دون سؤال. الطريقة الأخرى لتخطّي السؤال هي قائمة allow بالأوامر التي تثق بها مع needsApproval: false، كما هو مكتوب في بداية Workspace tools. استخدم هناك قواعد دقيقة مثل { command: 'npm test' }: النص العادي مثل 'npm test' يسمح بالأمر مع أي arguments، بما فيها flags تكتب خارج الـ workspace. الـ regex تسهيل، وليس حدًا أمنيًا: أمر الـ shell يمكن كتابته بطرق كثيرة. لأي شيء لا تتحكم فيه، أبقِ الافتراضي ووافق على كل أمر، أو شغّل الـ shell داخل sandbox (راجع SandboxShell في Workspace tools).
3. شغّله وتابع الـ stream
أنشئ الـ agent بالـ tools، ثم استدعِagent.stream(). تعيد run تمرّ عليه بـ for await وتأخذ typed events: text.delta يحمل نص الـ model أولًا بأول أثناء كتابته، وtool.start يعلن عن كل tool call (راجع Streaming).
maxSteps يحدد عدد استدعاءات الـ model في run واحد، فلا يدور الـ agent المرتبك إلى ما لا نهاية. هذا البرنامج يتوقف عند أول call يحتاج approval: ينتهي الـ stream بحدث approval.requested وينتهي الـ run بالحالة 'awaiting-approval'. الخطوة التالية تعالج هذا. بادئة vendor/ في اسم الـ model تختار الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).
4. تعامل مع التوقف
عندما ينتهي الـ stream، يعطيكawait run.result النتيجة النهائية. إذا توقف الـ run، يسمّي result.approvalId الـ call المعلّق. اسأل المستخدم، ثم تابع بـ agent.approvals.streamResolve() التي تعيد run جديدًا لبقية العمل. وقد يتوقف هذا الـ run مرة أخرى، فكرّر الحلقة حتى لا يبقى approvalId.
tool.resume — فقد طُبع tool.start الخاص به في الـ run الذي توقف، فتطبع الحلقة كل call مرة واحدة (وtool.resume هو الحدث الذي تطابقه إذا أردت أن تعلّم الـ call بأنه عاد إلى العمل). والـ call المرفوض لا يُفشل الـ run: يأخذ الـ model نتيجة رفض بدلًا من output الـ tool ويتابع. ولإخباره بالسبب، مرّر note: streamResolve({ id, approved: false, note: 'Do not touch the lockfile' }). وtry / finally تغلق واجهة readline حتى لو رُفض run.result لأن الـ run فشل.
حدث approval.requested يحمل أيضًا toolName وargs، فتستطيع طباعة ما سينفذه الـ call قبل أن تسأل. راجع Approvals للـ API كامل.
5. حافظ على استمرار المحادثة
حتى الآن تبدأ كل مهمة من الصفر.agent.session() تنشئ session (جلسة) تحتفظ بالـ transcript (سجل المحادثة)، فترى متابعةٌ مثل “now add a test for the empty case” الـ turns السابقة. وsession.stream(input) هي agent.stream() لكن لمحادثة، وتعيد نوع الـ run نفسه؛ والـ turn الذي يتوقف على call يحتاج approval يكتمل في الـ session نفسها عندما تحسمه عبر الـ agent نفسه (راجع الـ streaming داخل session). حوّل الحلقة إلى REPL: session.stream() واحدة لكل سطر يكتبه المستخدم، مع معالجة التوقف نفسها.
exit ينهي البرنامج. الـ session موجودة في الذاكرة، فتنتهي بانتهاء العملية؛ إذا أردت محادثة تبقى بين runs، أعطِ الـ agent store (مخزن) (راجع اختيار store).
الـ turns الطويلة وإعادة التشغيل
- السياق. الـ turn في coding agent يقرأ ملفات ويشغّل اختبارات ويعدّل على مدى خطوات كثيرة؛ وكل نتيجة tool تبقى في الـ transcript، فقد يتجاوز turn من 40 خطوة نافذة سياق (context window) بحجم 128k token قبل أن ينتهي. مرّر
createAgent({ compaction: true })(أو دالة تلخيص، راجع ضغط السياق): يضغط السياق قبل كل استدعاء للـ model، حتى بين خطوات الـ turn الواحد. - الانهيار. مع store متين، يُكمل
session.send()التالي أوsession.resume()الـ turn الذي قُتل في منتصفه. والـ tool call الذي كان قيد التشغيل عندما توقفت العملية يعمل مرة أخرى (at-least-once). وwrite_fileوedit_fileالمدمجتان آمنتان لإعادة التشغيل:write_fileتكتب المحتوى نفسه مرة أخرى، وedit_fileالتي يوجد تعديلها أصلًا في الملف (old_stringاختفى وnew_stringموجود) تنجح برسالة “the edit was already applied” بدلًا من أن تفشل. ومعWorkspaceCheckpoints، تُحفظ نسخة احتياطية لكل تغيير قبل كتابة الملف، وتحتفظ إعادة التشغيل بالنسخة الأولى، فيعيدrewind()الأصل حتى بعد الانهيار. - عرض التقدّم أثناء الاستئناف.
session.resume()تعيد نتيجة، لا stream، وsession.stream()لا تبث الـ turn المعلّق الذي تكمله قبل الرسالة الجديدة. لعرض التقدّم، سجّلsession.on((event) => ...)قبل الاستدعاء، أو مرّرcreateAgent({ onEvent }): كلاهما يستلمAgentEvents الخاصة بالـ turn المستأنف (tool.start،text.delta، …،run.done) أولًا بأول. - الـ approvals بعد إعادة التشغيل.
agent.approvals.streamResolve({ id, approved })(أوresolve()) من process جديد، بالـ store المتين نفسه، يكمل الـ turn المتوقف في الـ session الخاصة به؛ دون أن تستدعيsession.resume()قبل ذلك.
6. اختبره بدون model
الـ agent لا يحتاج إلى شبكة لكي تختبره.MemoryWorkspace يُبقي الملفات في الذاكرة ويأخذ exec مكتوبًا مسبقًا للـ shell، وmockModel يؤدي دور الـ model. تحقق من workspace.snapshot() وworkspace.commands.
write_file كما يفعل الـ agent الحقيقي. send() تنتهي بـ finishReason: 'awaiting-approval' وapprovalId، ويبقى الملف دون تغيير، وagent.approvals.resolve() تنفّذ الكتابة وتنهي الـ turn.
الخطوات التالية
- Workspace tools: المرجع الكامل للـ tools، ونموذج الأمان، و
SandboxShellلتشغيل الأوامر في Docker. - التراجع عن تعديلات الـ agent على الملفات: مرّر
WorkspaceCheckpointsإلىcreateFsTools(workspace, { checkpoints })، ثم يعرض لكcheckpoints.rewind(turn, { sessionId: session.id, dryRun: true })ما سيُستعاد إذا عدت إلى turn معيّن. - Approvals: الـ durable approval stores، ودوال
approve، واتخاذ القرار من process آخر. - Streaming: كل أنواع الـ events، وإلغاء run، وصيغ الـ stream للويب.
- Sessions: الـ stores والحدود والـ durable sessions.
- Durable execution: يكتمل الـ run حتى لو تعطّلت العملية في منتصفه.
- Configuration:
projectInstructions: trueيلحق ملفAGENTS.mdأوCLAUDE.mdبالـ instructions.