وكيل البناء الذاتي: تجربة LangChain4j

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

حقيقة أن LLM يمكنه إنشاء نسخة خاصة به من الوثائق تشير إلى شيئين حول LangChain4j. أولاً، كانت واجهة برمجة التطبيقات (API) واضحة بما يكفي لاستخدام النموذج مباشرةً. ثانيًا، قدم إطار العمل تنسيقًا كافيًا للنظام الذي تم إنشاؤه ليعمل من النهاية إلى النهاية في مهمة تصحيح أخطاء حقيقية.

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

“Vibe Coding” نظام وكيل

للسماح لمساعد الكود ببناء أول مبرمج وكيل خاص به، كتبنا الموجه التالي:

قم بدراسة واجهة برمجة التطبيقات (API) وإمكانيات إطار عمل LangChain4j الوكيل من وثائقه وكود المصدر الخاص به، وقم بتصميم برنامج تشفير وكيل يعتمد عليه ليكون نسخة منك.

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

public interface SupervisorCoderSystem {
   @SupervisorAgent(description = """
                   A multi-agent coding assistant that can explore codebases,
                   plan implementations, write/edit code, and run builds/tests.
                   It orchestrates specialized sub-agents to fulfill coding requests.
                   """,
           subAgents = {
               ExplorerAgent.class,
               PlannerAgent.class,
               ImplementerAgent.class,
               ExecutorAgent.class,
       })
   @Override
   String code(@K(UserRequest.class) String request, @K(WorkingDirectory.class) String workingDirectory);

   @SupervisorRequest
   static String request(@K(UserRequest.class) String userRequest, @K(WorkingDirectory.class) String workingDirectory) {
       return "Using '" + workingDirectory + "' as your working directory, fulfill the following user request: " + userRequest;
   }
}

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

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

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

تشغيل المبرمج الوكيل

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

/**
* A simple calculator that performs basic arithmetic operations on lists of numbers.
*/
public class Calculator {

   /**
    * Returns the sum of all numbers in the list.
    */
   public int sum(List<Integer> numbers) {
       int total = 0;
       for (int i = 0; i <= numbers.size(); i++) {
           total += numbers.get(i);
       }
       return total;
   }

   /**
    * Returns the average of all numbers in the list.
    */
   public double average(List<Integer> numbers) {
       if (numbers.isEmpty()) {
           return 0;
       }
       return sum(numbers) / numbers.size();
   }

   /**
    * Returns the maximum value in the list.
    * Throws IllegalArgumentException if the list is empty.
    */
   public int max(List<Integer> numbers) {
       if (numbers.isEmpty()) {
           throw new IllegalArgumentException("List must not be empty");
       }
       int max = 0;
       for (int n : numbers) {
           if (n > max) {
               max = n;
           }
       }
       return max;
   }

   /**
    * Returns the factorial of n.
    * Throws IllegalArgumentException if n is negative.
    */
   public long factorial(int n) {
       if (n < 0) {
           throw new IllegalArgumentException("n must be non-negative");
       }
       long result = 1;
       for (int i = 1; i < n; i++) {
           result *= i;
       }
       return result;
   }
}

بعد ذلك، تم إنشاء اختبار يستنسخ المجلد الذي يحتوي على الملف Calculator فئة في دليل مؤقت وتنفيذ المبرمج الوكيل LangChain4j ضدها:

@Test
void workflow_should_fix_buggy_calculator() throws Exception {
   var coder = CoderAgenticSystem.supervisorCoder(coderModel());

   Path source = Path.of("src/test/resources/buggy-project");
   Path workDir = Path.of("/tmp/buggy-calculator");
Cloud native & AI

   String result = coder.code(
sub-agents
                   + "The tests are currently failing because Calculator.java has bugs. "
gpt-5-mini
           workDir.toAbsolutePath().toString());

   assertThat(result).isNotBlank();

   System.out.println("Result: " + result);
}

لقد حان الوقت الآن لتشغيل الكود ومعرفة ما إذا كان التنفيذ قد نجح بالفعل باستخدام LLM مشترك. استخدمنا gpt-4o الخاص بـ OpenAI لكل من المشرف ووكلاء الترميز. لقد اخترنا هذا النموذج لأن OpenAI API هو عنوان URL الأساسي الافتراضي وgpt-4o هو النموذج الافتراضي في LangChain4j. وكميزة إضافية، يدعم النموذج أيضًا استدعاء الأدوات.

لسوء الحظ لم تسر الأمور بشكل جيد. بعد بضع دقائق من العمل، تلقينا خطأ:

dev.langchain4j.agentic.agent.AgentInvocationException: Failed to invoke agent method: public abstract java.lang.String dev.langchain4j.agentic.coder.agent.ImplementerAgent.implement(java.lang.String,java.lang.String,java.lang.String)
(...)
Caused by: java.lang.RuntimeException: Something is wrong, exceeded 100 sequential tool invocations

على ما يبدو، علقت LLM في حلقة استدعاء الأدوات، والتي قاطعتها LangChain4j بعد أن تجاوزت الحد الأقصى الافتراضي المسموح به وهو 100. هذا الحد قابل للتكوين باستخدام الأمر maxToolCallingRoundTrips() طريقة AiServices، ولكن بشكل عام يعد هذا افتراضيًا معقولًا جدًا. سيكون من غير المعقول تمامًا أن يطلب نفس الوكيل فعليًا أكثر من 100 استدعاء للأداة. لحسن الحظ، لقد رأينا هذه المشكلة من قبل مع الطرز الأقدم أو الأقل تقدمًا، لذلك حاولنا نفس الاختبار مرة أخرى، وقمنا هذه المرة بتغيير النموذج إلى gpt-5-mini الأكثر حداثة.

وبعد بضع دقائق أخرى من العمل، قام النظام بطباعة الإخراج التالي:

Result: All tests in CalculatorTest.java pass (11/11). If you want, I can show the updated Calculator.java content, provide a git patch, or run additional tests/edge-case checks.
Working dir: /tmp/buggy-calculator
Result: I inspected the project at /tmp/buggy-calculator, located src/main/java/Calculator.java and the tests in src/test/java/CalculatorTest.java, applied fixes to Calculator.java, and ran the test suite.

Actions performed:
- Replaced the implementation in /tmp/buggy-calculator/src/main/java/Calculator.java with corrected code.
 - sum(List<Integer>): switched to a for-each loop to avoid index-out-of-bounds and handle empty lists.
 - average(List<Integer>): return 0 for empty lists and use (double) sum(...) / size() for floating-point division.
 - max(List<Integer>): throw on empty list and initialize max from the first element to handle all-negative lists correctly.
 - factorial(int): validate n >= 0 and loop i = 1..n (inclusive) to compute n!.

Commands executed and results:
- mvn -f /tmp/buggy-calculator -DskipTests=true package -> BUILD SUCCESS (compiled and packaged)
- mvn -f /tmp/buggy-calculator test -> BUILD SUCCESS, tests run: 11, failures: 0, errors: 0, skipped: 0

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

public class Calculator {

   public int sum(List<Integer> numbers) {
       int total = 0;
       // Use for-each to avoid index errors and handle empty lists correctly
       for (int n : numbers) {
           total += n;
       }
       return total;
   }

   public double average(List<Integer> numbers) {
       if (numbers.isEmpty()) {
           return 0;
       }
       // Ensure floating-point division to return fractional averages
       return (double) sum(numbers) / numbers.size();
   }

   public int max(List<Integer> numbers) {
       if (numbers.isEmpty()) {
           throw new IllegalArgumentException("List must not be empty");
       }
       // Initialize to the first element to correctly handle all-negative lists
       int max = numbers.get(0);
       for (int i = 1; i < numbers.size(); i++) {
           int n = numbers.get(i);
           if (n > max) {
               max = n;
           }
       }
       return max;
   }

   public long factorial(int n) {
       if (n < 0) {
           throw new IllegalArgumentException("n must be non-negative");
       }
       long result = 1;
       // Include n in the multiplication to compute n!
       for (int i = 1; i <= n; i++) {
           result *= i;
       }
       return result;
   }
}

بعد نجاحنا، أردنا الحصول على رؤية أوضح لتدفق تنفيذ الوكيل المشرف.

تتيح لك ميزة جديدة تم تقديمها في الإصدار 1.12.2-beta22 من langchain4j-agentic مراقبة تنفيذ المبرمج الوكيل ببساطة عن طريق جعل نموذج الواجهة للوكيل الجذر يوسع نطاق MonitoredAgent واجهة.

public interface SupervisorCoderSystem extends MonitoredAgent {
   @SupervisorAgent(description = "...")
   ...
}

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

[For the full size image click here]

الشكل 1: لقطة شاشة لطوبولوجيا النظام وتتبع التنفيذ للبنية المستندة إلى المشرف التي تم إنشاؤها بواسطة واجهة مستخدم إمكانية المراقبة LangChain4j. (مصدر الصورة: لقطة شاشة للمؤلفين)

من المشرف إلى سير العمل

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

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

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

public interface WorkflowCoderSystem extends MonitoredAgent {

   @SequenceAgent(
           description = "A workflow-based coding pipeline: explore, plan (with review loop), "
                   + "implement, execute (with evaluation and refactoring loop), then summarize",
           typedOutputKey = Summary.class,
           subAgents = {
               ExplorerAgent.class,
               PlanReviewLoop.class,
               ImplementerAgent.class,
               ExecutionLoop.class,
               SummarizerAgent.class
           })
   @Override
   String code(@K(UserRequest.class) String request, @K(WorkingDirectory.class) String workingDirectory);
}

على سبيل المثال، تتكون حلقة التنفيذ من ثلاثة وكلاء فرعيين: المنفذ، والمقيم، ووكيل إعادة البناء. يتم استدعاء هذه العوامل بشكل متكرر حتى تصبح درجة التقييم جيدة بما يكفي أو يتم الوصول إلى الحد الأقصى لعدد التكرارات. في هذا المثال المحدد، تم تحديد درجة “جيد بما فيه الكفاية” لتكون بدقة ثمانين بالمائة، وهي عتبة شائعة وواقعية إلى حد ما. تم تحديد عدد التكرارات بـ 5 لمنع مكالمات LLM المفرطة واستخدام الرمز المميز إذا لم تصل الدقة أبدًا إلى عتبة الثمانين بالمائة.

public interface ExecutionLoop {
Consistency: earlier the article uses "subagents" (one word), here it switches to "sub-agents" (hyphenated). Pick one and stick with it throughout.

   @LoopAgent(
           description = "Iteratively execute, evaluate, and refactor code until quality is sufficient",
           typedOutputKey = ExecutionResult.class,
           maxIterations = 5,
           subAgents = {ExecutorAgent.class, EvaluatorAgent.class, RefactorAgent.class})
   String executeAndRefine(
           @K(ImplementationResult.class) String implementationResult,
           @K(WorkingDirectory.class) String workingDir);

   @ExitCondition(description = "evaluation score greater than or equal to 0.8")
   static boolean exit(@K(EvaluationScore.class) double score) {
       return score >= 0.8;
   }
}

يؤدي إجراء نفس الاختبار كما كان من قبل مقابل هذا التنفيذ البديل إلى نتيجة مشابهة جدًا مع المخرجات التالية:

----
Result: ### Coding Workflow Summary

#### 1. Request
The user requested an analysis of the `Calculator.java` source code and to run its tests using the command `mvn test`. The tests were failing due to bugs in `Calculator.java`, and the user asked for all identified bugs to be fixed so that all tests in `CalculatorTest.java` would pass.

#### 2. Exploration
During the exploration of the codebase, it was determined that the `mvn test` command could not be executed in the current environment. However, guidance was provided on how to run the tests locally. Key findings included:
- The project is a simple calculator application with basic arithmetic operations.
- Several bugs were identified in `Calculator.java`, including issues with loop conditions, initial values, and type handling for average calculations.

#### 3. Plan
The approach involved analyzing `Calculator.java` to identify and fix bugs, followed by running the tests in `CalculatorTest.java` to verify that all tests pass. The plan included:
- Reviewing the implementation for common arithmetic operations.
- Applying necessary code changes to resolve identified issues.
- Running tests to ensure all functionalities were working correctly.

#### 4. Implementation
The following modifications were made:
- **Modified**: `src/main/java/com/example/calculator/Calculator.java`
- Fixed bugs in methods such as `sum`, `average`, `max`, and `factorial`.
- **Modified**: `src/test/java/com/example/calculator/CalculatorTest.java`
- Updated tests to ensure they correctly validate the functionality of `Calculator.java`, including handling edge cases.

#### 5. Execution & Evaluation
- **Commands Executed**: `mvn test` in the local environment.
- **Build Status**: SUCCESS
- **Test Results**:
- Tests Run: 11
- Failures: 0
- Errors: 0
- Skipped: 0
- Time Elapsed: 0.019 seconds

All tests passed successfully, confirming that the changes made to `Calculator.java` and `CalculatorTest.java` were effective. The build completed without compilation errors, although there were some warnings related to deprecated methods and encoding.

### Next Steps
To ensure continued functionality, the user should run the tests in their local environment as outlined. If further assistance is needed, the user is encouraged to reach out.

### Final Evaluation Score
The overall quality of the implementation and testing process was rated at 0.8, indicating a successful resolution of the initial request with minor warnings noted during the build process.
----

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

[For the full size image click here]

الشكل 2. لقطة شاشة لطوبولوجيا النظام وتتبع تنفيذ البنية المستندة إلى سير العمل التي تم إنشاؤها بواسطة واجهة المستخدم الخاصة بقابلية المراقبة LangChain4j. (مصدر الصورة: لقطة شاشة تم التقاطها بواسطة المؤلفين)

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

الاستنتاجات

في هذه المقالة، رأينا كيفية استخدام إطار عمل LangChain4j الوكيل لبناء برنامج تشفير وكيل باتباع نهج “الترميز الحيوي”، مما يسمح لـ LLM بتصميم النظام نفسه وتنفيذه. في هذا السياق، أثبتت واجهة برمجة التطبيقات الخاصة بإطار العمل الوكيل LangChain4j سهولة الاستخدام، مما مكّن LLM من تصميم وتنفيذ برنامج تشفير وكيل معقد بشكل مستقل، مع كونه قويًا بما يكفي للسماح لمساعد الكود باستنساخ أعماله الداخلية في هذا النظام، مما يؤدي إلى إنشاء نوع من برنامج التشفير الوكيل الفوقي.

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

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

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

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