إنشاء وكلاء مستندين إلى الذكاء الاصطناعي باستخدام "حزمة تطوير الوكلاء" (ADK) للغة Java

1. مرحبًا بكم، مطوّرو وكلاء الذكاء الاصطناعي!

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية إنشاء وكلاء ذكاء اصطناعي في Java باستخدام حزمة تطوير الوكلاء (ADK) للغة Java. سنتجاوز طلبات البيانات البسيطة من واجهة برمجة التطبيقات الخاصة بالنماذج اللغوية الكبيرة (LLM) لإنشاء وكلاء مستقلين للذكاء الاصطناعي يمكنهم الاستدلال والتخطيط واستخدام الأدوات والعمل معًا لحل المشاكل المعقدة.

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

أهداف الدورة التعليمية

• كيفية إنشاء وكيل ذكاء اصطناعي أساسي مستند إلى شخصية
• كيفية تزويد الوكلاء بأدوات مخصّصة ومضمّنة (مثل "بحث Google")
• كيفية إضافة أدواتك الخاصة التي تم تنفيذها في Java
• كيفية تنسيق عدة وكلاء في مهام سير عمل متسلسلة ومتوازية ومتكررة فعّالة

المتطلبات

• متصفّح ويب سنستخدمه في وضع التصفّح المتخفي
• حساب Gmail شخصي
• مشروع جديد على Google Cloud مرتبط بحسابك الشخصي على Gmail
• حساب فوترة تم إنشاؤه باستخدام أرصدة Google Cloud التي تم تحصيل قيمتها
• أداة سطر الأوامر git لاستخراج الرمز المصدر
• ‫Java 17 والإصدارات الأحدث وApache Maven
• محرّر نصوص أو بيئة تطوير متكاملة (IDE)، مثل IntelliJ IDEA أو VS Code

يمكنك استخدام "محرّر الرموز" المضمّن في Cloud Shell، وذلك في وحدة تحكّم Google Cloud.

2. الإعداد: بيئتك

المطالبة بأرصدة Google Cloud الخاصة بورشة العمل

بالنسبة إلى ورشة العمل التي يقودها مدرّب، ستتلقّى رابطًا إلى الموقع الإلكتروني حيث يمكنك طلب رصيد Google Cloud لاستخدامه في ورشة العمل.

• استخدام حساب Google شخصي: من المهم استخدام حساب Google شخصي (مثل عنوان gmail.com) لأنّ عناوين البريد الإلكتروني الخاصة بالشركات أو المؤسسات التعليمية لن تعمل.
• استخدام Google Chrome في وضع التصفّح المتخفي: يُنصح بذلك لإنشاء جلسة جديدة ومنع حدوث تعارضات مع حسابات Google الأخرى.
• استخدام رابط الحدث الخاص: يجب استخدام رابط خاص بالحدث، ويبدو على النحو التالي: https://trygcp.dev/event/xxx متبوعًا برمز الحدث (هنا "xxx" في هذا المثال).
• قبول بنود الخدمة: بعد تسجيل الدخول، ستظهر لك بنود خدمة Google Cloud Platform، ويجب قبولها للمتابعة.
• إنشاء مشروع جديد: يجب إنشاء مشروع جديد فارغ من Google Cloud Console.
• ربط حساب فوترة: اربط المشروع الذي تم إنشاؤه حديثًا بحساب فوترة.
• تأكيد الرصيد: يوضّح الفيديو التالي كيفية التأكّد من تطبيق الرصيد على المشروع من خلال الاطّلاع على قسم "الأرصدة" في صفحة الفوترة.

يمكنك مشاهدة هذا الفيديو الذي يشرح كيفية تحصيل قيمة الرصيد واستخدامه.

تفعيل Vertex AI API

أولاً، فعِّل Vertex AI API. يمكنك إجراء ذلك من خلال البحث عن Vertex AI API في Google Cloud Console وتفعيل واجهة برمجة التطبيقات هناك. يمكنك أيضًا إجراء ذلك من Cloud Shell من خلال تنفيذ ما يلي:

gcloud services enable aiplatform.googleapis.com

ضبط ADK باستخدام Vertex AI

لإثبات هوية وكلاء الذكاء الاصطناعي في "حزمة تطوير التطبيقات" باستخدام Gemini على Vertex AI في هذا الدرس التطبيقي حول الترميز، اضبط متغيّرات البيئة التالية. تأكَّد من استخدام معرّف المشروع الفريد.

نظام التشغيل macOS أو Linux: افتح الوحدة الطرفية ونفِّذ الأمر التالي. لإجراء هذا التغيير بشكل دائم، أضِف هذا السطر إلى ملف بدء التشغيل الخاص بالصدفة (مثل ~/.bash_profile أو ~/.zshrc).

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=your-project-id

نظام التشغيل Windows (موجّه الأوامر): افتح موجّه أوامر جديدًا ونفِّذ ما يلي:

set GOOGLE_GENAI_USE_VERTEXAI=true
set GOOGLE_CLOUD_PROJECT=your-project-id

عليك إعادة تشغيل موجه الأوامر ليتم تطبيق هذا التغيير.

نظام التشغيل Windows (PowerShell): افتح وحدة تحكّم PowerShell وشغِّل:

$env:GOOGLE_GENAI_USE_VERTEXAI = "true"
$env:GOOGLE_CLOUD_PROJECT = "your-project-id"

لإجراء هذا التغيير بشكل دائم في PowerShell، عليك إضافته إلى نص ملفك الشخصي.

3- البدء: وكيلك الأول

أفضل طريقة لبدء مشروع جديد هي استخدام نموذج ADK for Java على GitHub. يوفر بنية المشروع وجميع التبعيات اللازمة.

إذا كان لديك حساب على Github، يمكنك إجراء ما يلي: Use this template > Create a new repository، ثم استخراج الرمز برمجيًا بشكل محلي باستخدام الأمر git clone.

في ما يلي لقطة شاشة تعرض القائمة أعلى يسار الصفحة لاستخدام النموذج.

النهج الآخر هو استنساخ هذا المستودع مباشرةً:

git clone https://github.com/glaforge/adk-java-maven-template.git

للتأكّد من أنّك مستعد لبدء كتابة رمز أول وكيل يعمل بالذكاء الاصطناعي في Java، تأكَّد من إمكانية تجميع الرمز في هذا المشروع باستخدام:

cd adk-java-maven-template
mvn compile

Code Step: A Friendly Science Teacher Agent

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

لننشئ فئة Java جديدة في حزمة com.example.agent ونسمّيها ScienceTeacher.

هذه هي الخطوة الأولى في إنشاء الوكيل. سنحدّد وكيلًا بسيطًا بشخصية معلّم علوم.

// src/main/java/com/example/agent/ScienceTeacher.java
package com.example.agent;

import com.google.adk.agents.LlmAgent;
import com.google.adk.web.AdkWebServer;

public class ScienceTeacher {
    public static void main(String[] args) {
        AdkWebServer.start(
            LlmAgent.builder()
                .name("science-teacher")
                .description("A friendly science teacher")
                .instruction("""
                    You are a science teacher for teenagers.
                    You explain science concepts in a simple, concise and direct way.
                    """)
                .model("gemini-2.5-flash")
                .build()
        );
    }
}

يتم إعداد وكيل الذكاء الاصطناعي من خلال الطريقة LlmAgent.builder(). المَعلمات name() وdescription() وmodel() إلزامية، ولإضفاء طابع شخصي محدّد وسلوك مناسب على وكيلك، عليك دائمًا تقديم إرشادات مفصّلة من خلال طريقة instruction().

اخترنا هنا استخدام نموذج Gemini 2.5 Flash، ولكن يمكنك أيضًا تجربة Gemini 2.5 Pro للمهام الأكثر تعقيدًا.

يتم تضمين هذا الوكيل في طريقة AdkWebServer.start(). هذه هي واجهة المحادثة المعروفة باسم واجهة مستخدم ADK Dev. تتيح لك هذه الميزة التحدّث مع الوكيل من خلال واجهة دردشة عادية. بالإضافة إلى ذلك، يكون من المفيد جدًا فهم ما يحدث في الخلفية، مثل جميع الأحداث التي تمر عبر النظام والطلبات والردود التي يتم إرسالها إلى النموذج اللغوي الكبير.

لإنشاء هذا البرنامج وتشغيله على جهازك، شغِّل الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.ScienceTeacher

بعد ذلك، انتقِل إلى المتصفّح على http://localhost:8080. إذا كنت تستخدم Cloud Shell، يمكنك الانتقال إلى معاينة الويب واختيار المعاينة على المنفذ 8080.

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

4. تزويد الوكلاء بالأدوات

لماذا يحتاج وكلاء الدعم إلى أدوات؟ تتميّز النماذج اللغوية الكبيرة بفعاليتها، ولكن معلوماتها ثابتة ولا يمكنها التفاعل مع العالم الخارجي. الأدوات هي الجسر. تسمح هذه الأدوات للوكيل بالوصول إلى المعلومات في الوقت الفعلي (مثل أسعار الأسهم أو الأخبار) أو طلب بيانات من واجهات برمجة التطبيقات الخاصة أو تنفيذ أي إجراء يمكنك ترميزه بلغة Java.

خطوة الرمز البرمجي: إنشاء أداة مخصّصة (StockTicker)

هنا، نقدّم للوكيل أداة للبحث عن أسعار الأسهم. يستنتج الوكيل أنّه عندما يطلب المستخدم سعرًا، يجب أن يستدعي طريقة Java.

// src/main/java/com/example/agent/StockTicker.java
package com.example.agent;

import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.Annotations.Schema;
import com.google.adk.tools.FunctionTool;
import com.google.adk.web.AdkWebServer;
import java.util.Map;

public class StockTicker {
    public static void main(String[] args) {
        AdkWebServer.start(
            LlmAgent.builder()
                .name("stock_agent")
                .instruction("""
                    You are a stock exchange ticker expert.
                    When asked about the stock price of a company,
                    use the `lookup_stock_ticker` tool to find the information.
                    """)
                .model("gemini-2.5-flash")
                .tools(FunctionTool.create(StockTicker.class, "lookupStockTicker"))
                .build()
        );
    }

    @Schema(
        name = "lookup_stock_ticker",
        description = "Lookup stock price for a given company or ticker"
    )
    public static Map<String, String> lookupStockTicker(
        @Schema(name = "company_name_or_stock_ticker", description = "The company name or stock ticker")
        String ticker) {
        // ... (logic to return a stock price)
    }
}

لجعل الوكلاء أكثر ذكاءً ومنحهم القدرة على التفاعل مع العالم (أو مع الرمز البرمجي وواجهات برمجة التطبيقات والخدمات وما إلى ذلك)، يمكنك ضبط الوكيل لاستخدام الأدوات، وخاصةً أدوات الرموز البرمجية المخصّصة، من خلال طريقة tools()، مع تمرير FunctionTool.create(...) إليها.

يتطلّب FunctionTool فئة واسم طريقة يشيران إلى طريقتك الثابتة، ويمكن أيضًا تمرير مثيل لفئة واسم طريقة مثيل لهذا العنصر.

من المهم تحديد name وdescription لكل من الطريقة ومعلَماتها من خلال التعليق التوضيحي @Schema، لأنّ النموذج اللغوي الكبير الأساسي سيستخدم هذه المعلومات لتحديد متى وكيف يجب استدعاء طريقة معيّنة.

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

يجب أن تعرض هذه الطريقة Map. عادةً، تكون الفكرة هي عرض خريطة تتضمّن مفتاحًا يمثّل النتيجة، مثل stock_price، وربط قيمة سعر السهم به. في النهاية، يمكنك إضافة زوج مفتاح / قيمة إضافي يشير إلى نجاح العملية. وفي حال حدوث خطأ، يجب إرجاع خريطة بمفتاح يُسمى، على سبيل المثال، error، وربط رسالة الخطأ بالقيمة المرتبطة. يساعد ذلك النموذج اللغوي الكبير في معرفة ما إذا كانت المكالمة قد نجحت أو تعذّر إجراؤها لسبب ما.

• عند النجاح، يتم عرض: {"stock_price": 123}
• في حال حدوث خطأ، يتم عرض: {"error": "Impossible to retrieve stock price for XYZ"}

بعد ذلك، شغِّل هذه الفئة باستخدام الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.StockTicker

يمكنك الآن أن تطلب من الوكيل أسعار الأسهم، مثلاً What's the stock price for GOOG?، وستتلقّى الردود وتلاحظ أنّه يتم استخدام أداة lookup_stock_ticker.

5- قوة "بحث Google" في تقديم معلومات محدّثة

تتضمّن "حزمة تطوير الوكلاء" للغة Java مجموعة من الأدوات الفعّالة، من بينها GoogleSearchTool. باستخدام هذه الأداة، يمكن أن يطلب الوكيل استخدام "بحث Google" للعثور على معلومات ذات صلة لتحقيق هدفه.

في الواقع، إنّ معرفة النموذج اللغوي الكبير ثابتة في الوقت الحالي، فقد تم تدريبه حتى تاريخ معيّن ("تاريخ الإيقاف") باستخدام بيانات حديثة أيضًا مثل وقت جمع المعلومات. وهذا يعني أنّ النماذج اللغوية الكبيرة قد لا تكون على دراية بالأحداث الأخيرة، أو قد تكون معرفتها محدودة وسطحية، وقد يساعدها محرك البحث في استعادة معلوماتها أو معرفة المزيد عن الموضوع.

لنلقِ نظرة على وكيل البحث البسيط عن الأخبار هذا:

// src/main/java/com/example/agent/LatestNews.java
package com.example.agent;

import java.time.LocalDate;
import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.GoogleSearchTool;
import com.google.adk.web.AdkWebServer;

public class LatestNews {
    public static void main(String[] args) {
        AdkWebServer.start(LlmAgent.builder()
            .name("news-search-agent")
            .description("A news search agent")
            .instruction("""
                You are a news search agent.
                Use the `google_search` tool
                when asked to search for recent events and information.
                Today is \
                """ + LocalDate.now())
            .model("gemini-2.5-flash")
            .tools(new GoogleSearchTool())
            .build());
    }
}

لاحظ كيف مرّرنا مثيلاً لأداة البحث باستخدام: tools(new GoogleSearchTool()). وهذا ما يمنح الوكيل القدرة على التعرّف على أحدث المعلومات المتوفّرة على الويب. بالإضافة إلى ذلك، حدّد الطلب تاريخ اليوم، لأنّ ذلك قد يساعد النموذج اللغوي الكبير في فهم ما إذا كانت الأسئلة تتعلّق بمعلومات سابقة وما إذا كان من المطلوب البحث عن معلومات أحدث.

بعد ذلك، شغِّل هذه الفئة باستخدام الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.LatestNews

يمكنك تجربة الطلب، مثلاً يمكنك طرح السؤال التالي: What's the latest news in the world?

خطوة الرمز البرمجي: استخدام "وكيل البحث" كأداة

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

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

// src/main/java/com/example/agent/SearchAgentAsTool.java
package com.example.agent;

import java.time.LocalDate;

import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.AgentTool;
import com.google.adk.tools.GoogleSearchTool;
import com.google.adk.web.AdkWebServer;

public class SearchAgentAsTool {
    public static void main(String[] args) {
        // 1. Define the specialized Search Agent
        LlmAgent searchAgent = LlmAgent.builder()
            .name("news-search-agent-tool")
            .description("Searches for recent events and provides a concise summary.")
            .instruction("""
                You are a concise information retrieval specialist.
                Use the `google_search` tool to find information.
                Always provide the answer as a short,
                direct summary, without commentary.
                Today is \
                """ + LocalDate.now())
            .model("gemini-2.5-flash")
            .tools(new GoogleSearchTool()) // This agent uses the Google Search Tool
            .build();

        // 2. Wrap the Search Agent as a Tool
        AgentTool searchTool = AgentTool.create(searchAgent);

        // 3. Define the Main Agent that uses the Search Agent Tool
        AdkWebServer.start(LlmAgent.builder()
            .name("main-researcher")
            .description("Main agent for answering complex, up-to-date questions.")
            .instruction("""
                You are a sophisticated research assistant.
                When the user asks a question that requires up-to-date or external information,
                you MUST use the `news-search-agent-tool` to get the facts before answering.
                After the tool returns the result, synthesize the final answer for the user.
                """)
            .model("gemini-2.5-flash")
            .tools(searchTool) // This agent uses the Search Agent as a tool
            .build()
       );
    }
}

AgentTool.create(searchAgent) هو المفهوم الأساسي هنا. تسجّل هذه الدالة searchAgent بأكملها (مع منطقها الداخلي وطلبها وأدواتها) كأداة واحدة قابلة للاستدعاء في mainAgent. ويعزّز ذلك إمكانية التعديل وإعادة الاستخدام.

نفِّذ هذه الفئة باستخدام الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.SearchAgentAsTool

بالنسبة إلى الأسئلة العادية، سيردّ الوكيل من قاعدة المعرفة الخاصة به، ولكن عند السؤال عن أحداث حديثة، سيحوّل البحث إلى وكيل البحث المتخصّص باستخدام أداة "بحث Google".

6. إتقان عمليات سير العمل بالذكاء الاصطناعي الوكيل

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

يكمن الحلّ في تقسيم المهام من خلال تنسيق عدّة وكلاء متخصصين. لحسن الحظ، تتضمّن "حزمة تطوير التطبيقات" وكلاء متخصصين مدمجين مختلفين:

• وكيل عادي يمكن تفويض المهام إليه،subAgent()
• SequentialAgent، لتنفيذ المهام بالتسلسل،
• ParallelAgent، لتنفيذ الوكلاء بالتوازي،
• ‫LoopAgent، عادةً ما يكون ذلك من أجل إجراء عملية تحسين عدة مرات حسب الحاجة.

يمكنك الاطّلاع على الجدول أدناه لمعرفة حالات الاستخدام الرئيسية ومزايا وعيوب كل سير عمل. لكن اعلم أنّ القوة الحقيقية ستأتي في الواقع من الجمع بين عدة منها.

7. مهام مستندة إلى الذكاء الاصطناعي الوكيل: التفويض باستخدام وكلاء فرعيين

يمكن لوكيل مشرف تفويض مهام معيّنة إلى وكلاء فرعيين. على سبيل المثال، تخيَّل وكيلًا لموقع إلكتروني للتجارة الإلكترونية يفوّض الأسئلة المتعلقة بالطلبات إلى وكيل آخر ("ما هي حالة طلبي؟") والأسئلة المتعلقة بخدمة ما بعد البيع إلى وكيل آخر ("لا أعرف كيفية تشغيله!"). هذه هي حالة الاستخدام التي سنناقشها.

// src/main/java/com/example/agent/SupportAgent.java
package com.example.agent;

import com.google.adk.agents.LlmAgent;
import com.google.adk.web.AdkWebServer;

public class SupportAgent {
    public static void main(String[] args) {
        LlmAgent orderAgent = LlmAgent.builder()
            .name("order-agent")
            .description("Order agent")
            .instruction("""
                Your role is to help our customers
                with all the questions they may have about their orders.
                Always respond that the order has been received, prepared,
                and is now out for delivery.
                """)
            .model("gemini-2.5-flash")
            .build();

        LlmAgent afterSaleAgent = LlmAgent.builder()
            .name("after-sale-agent")
            .description("After sale agent")
            .instruction("""
                You are an after sale agent,
                helping customers with the product they received.
                When a customer has a problem,
                suggest the person to switch the product off and on again.
                """)
            .model("gemini-2.5-flash")
            .build();

        AdkWebServer.start(LlmAgent.builder()
            .name("support-agent")
            .description("Customer support agent")
            .instruction("""
                Your role is to help our customers.
                Call the `order-agent` for all questions related to order status.
                Call the `after-sale-agent` for inquiries about the received product.
                """)
            .model("gemini-2.5-flash")
            .subAgents(afterSaleAgent, orderAgent)
            .build()
        );
    }
}

السطر الأساسي هنا هو المكان الذي يتم فيه استدعاء الطريقة subAgents()، مع تمرير الوكيلَين الفرعيَين اللذين سيتم التعامل مع دورهما المحدّد بشكل منفصل عن بعضهما البعض.

نفِّذ المثال أعلاه باستخدام الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.SupportAgent

يمكنك طرح أسئلة مثل I have a question about my order أو I have a question about my received order. من المفترض أن ترى الوكيل الرئيسي يفوّض الوكيل المناسب، استنادًا إلى السؤال المطروح.

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

8. مهام مستندة إلى الذكاء الاصطناعي الوكيل: خط التجميع

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

لنفترض أنّ شاعرًا إنجليزيًا يتعاون مع مترجم من الإنجليزية إلى الفرنسية لإنشاء قصائد باللغة الإنجليزية أولاً ثم ترجمتها إلى الفرنسية:

// src/main/java/com/example/agent/PoetAndTranslator.java
package com.example.agent;

import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.SequentialAgent;
import com.google.adk.web.AdkWebServer;

public class PoetAndTranslator {
    public static void main(String[] args) {
        LlmAgent poet = LlmAgent.builder()
            .name("poet-agent")
            .description("Poet writing poems")
            .model("gemini-2.5-flash")
            .instruction("""
                You are a talented poet,
                who writes short and beautiful poems.
                """)
            .outputKey("poem")
            .build();

        LlmAgent translator = LlmAgent.builder()
            .name("translator-agent")
            .description("English to French translator")
            .model("gemini-2.5-flash")
            .instruction("""
                As an expert English-French translator,
                your role is to translate the following poem into French,
                ensuring the poem still rhymes even after translation:

                {poem}
                """)
            .outputKey("translated-poem")
            .build();

        AdkWebServer.start(SequentialAgent.builder()
            .name("poet-and-translator")
            .subAgents(poet, translator)
            .build());
    }
}

نفِّذ المثال:

mvn compile exec:java -Dexec.mainClass=com.example.agent.PoetAndTranslator

يمكنك الآن أن تطلب من الوكيل شيئًا مثل Write me a poem about a lonely software developer. ستحصل على قصيدة باللغة الإنجليزية ثم ستتم ترجمتها إلى الفرنسية.

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

يُعدّ تقسيم مهمة ما بشكل فعّال إلى سلسلة من المهام الفرعية (عند الإمكان وعندما يكون ذلك منطقيًا) أمرًا بالغ الأهمية لتحقيق نتائج أكثر تحديدًا ونجاحًا، لأنّه يتيح إحراز تقدّم منظَّم وإدارة التبعيات بين الخطوات.

9. مهام مستندة إلى الذكاء الاصطناعي الوكيل — العمل بالتوازي

عندما تكون المهام مستقلة، يوفّر ParallelAgent تحسّنًا كبيرًا في الكفاءة من خلال تنفيذها في الوقت نفسه. في المثال التالي، سنجمع بين SequentialAgent وParallelAgent: يتم تنفيذ المهام المتوازية أولاً، ثم يلخّص وكيل نهائي نتائج المهام المتوازية.

لننشئ برنامجًا للتحقّق من الشركات، وستكون مهمته البحث عن معلومات حول:

• الملف التعريفي للشركة (الرئيس التنفيذي والمقر الرئيسي والشعار وما إلى ذلك)
• آخر الأخبار حول الشركة
• تعرض هذه السمة تفاصيل حول البيانات المالية للشركة.

// src/main/java/com/example/agent/CompanyDetective.java 
package com.example.agent;

import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.ParallelAgent;
import com.google.adk.agents.SequentialAgent;
import com.google.adk.tools.GoogleSearchTool;
import com.google.adk.web.AdkWebServer;

public class CompanyDetective {
    public static void main(String[] args) {
        var companyProfiler = LlmAgent.builder()
            .name("company-profiler")
            .description("Provides a general overview of a company.")
            .instruction("""
                Your role is to provide a brief overview of the given company.
                Include its mission, headquarters, and current CEO.
                Use the Google Search Tool to find this information.
                """)
            .model("gemini-2.5-flash")
            .tools(new GoogleSearchTool())
            .outputKey("profile")
            .build();

        var newsFinder = LlmAgent.builder()
            .name("news-finder")
            .description("Finds the latest news about a company.")
            .instruction("""
                Your role is to find the top 3-4 recent news headlines for the given company.
                Use the Google Search Tool.
                Present the results as a simple bulleted list.
                """)
            .model("gemini-2.5-flash")
            .tools(new GoogleSearchTool())
            .outputKey("news")
            .build();

        var financialAnalyst = LlmAgent.builder()
            .name("financial-analyst")
            .description("Analyzes the financial performance of a company.")
            .instruction("""
                Your role is to provide a snapshot of the given company's recent financial performance.
                Focus on stock trends or recent earnings reports.
                Use the Google Search Tool.
                """)
            .model("gemini-2.5-flash")
            .tools(new GoogleSearchTool())
            .outputKey("financials")
            .build();

        var marketResearcher = ParallelAgent.builder()
            .name("market-researcher")
            .description("Performs comprehensive market research on a company.")
            .subAgents(
                companyProfiler,
                newsFinder,
                financialAnalyst
            )
            .build();

        var reportCompiler = LlmAgent.builder()
            .name("report-compiler")
            .description("Compiles a final market research report.")
            .instruction("""
                Your role is to synthesize the provided information into a coherent market research report.
                Combine the company profile, latest news, and financial analysis into a single, well-formatted report.

                ## Company Profile
                {profile}

                ## Latest News
                {news}

                ## Financial Snapshot
                {financials}
                """)
            .model("gemini-2.5-flash")
            .build();

        AdkWebServer.start(SequentialAgent.builder()
            .name("company-detective")
            .description("Collects various information about a company.")
            .subAgents(
                marketResearcher,
                reportCompiler
            ).build());
    }
}

كالعادة، يمكنك تشغيل البرنامج باستخدام الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.CompanyDetective

اطرح عليه أسئلة حول شركات مختلفة، مثل Google أو Apple، واطّلِع على الردود التي ستحصل عليها.

يقدّم هذا الوكيل مزيجًا قويًا من سير العمل، حيث يتم استخدام الوكلاء المتوازيين والمتسلسلين بشكل جيد وبطريقة فعّالة بفضل التوازي في البحث عن المعلومات وتجميعها.

10. عمليات سير العمل المستندة إلى الذكاء الاصطناعي الوكيل: التحسين التكراري

بالنسبة إلى المهام التي تتطلّب دورة "إنشاء → مراجعة → تحسين"، استخدِم LoopAgent. تعمل هذه الميزة على أتمتة التحسين التكراري إلى أن يتم تحقيق هدف معيّن. على غرار SequentialAgent، سيطلب LoopAgent من الوكلاء الفرعيين تنفيذ المهام بالتسلسل، ولكنّه سيعود إلى البداية. يقرّر النموذج اللغوي الكبير المستخدَم داخليًا من قِبل الوكيل ما إذا كان سيطلب إجراء مكالمة إلى أداة خاصة، وهي الأداة المضمّنة exit_loop، لإيقاف تنفيذ الحلقة.

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

لنلقِ نظرة على الرمز:

// src/main/java/com/example/agent/CodeRefiner.java
package com.example.agent;

import com.google.adk.agents.LlmAgent;
import com.google.adk.agents.LoopAgent;
import com.google.adk.agents.SequentialAgent;
import com.google.adk.tools.ExitLoopTool;
import com.google.adk.web.AdkWebServer;

public class CodeRefiner {
    public static void main(String[] args) {
        var codeGenerator = LlmAgent.builder()
            .name("code-generator")
            .description("Writes and refines code based on a request and feedback.")
            .instruction("""
                Your role is to write a Python function based on the user's request.
                In the first turn, write the initial version of the code.
                In subsequent turns, you will receive feedback on your code.
                Your task is to refine the code based on this feedback.

                Previous feedback (if any):
                {feedback?}
                """)
            .model("gemini-2.5-flash")
            .outputKey("generated_code")
            .build();

        var codeReviewer = LlmAgent.builder()
            .name("code-reviewer")
            .description("Reviews code and decides if it's complete or needs more work.")
            .instruction("""
                Your role is to act as a senior code reviewer.
                Analyze the provided Python code for correctness, style, and potential bugs.

                Code to review:
                {generated_code}

                If the code is perfect and meets the user's request,
                you MUST call the `exit_loop` tool.

                Otherwise, provide constructive feedback for the `code-generator to improve the code.
                """)
            .model("gemini-2.5-flash")
            .outputKey("feedback")
            .tools(ExitLoopTool.INSTANCE)
            .build();

        var codeRefinerLoop = LoopAgent.builder()
            .name("code-refiner-loop")
            .description("Iteratively generates and reviews code until it is correct.")
            .subAgents(
                codeGenerator,
                codeReviewer
            )
            .maxIterations(3) // Safety net to prevent infinite loops
            .build();

        var finalPresenter = LlmAgent.builder()
            .name("final-presenter")
            .description("Presents the final, accepted code to the user.")
            .instruction("""
                The code has been successfully generated and reviewed.
                Present the final version of the code to the user in a clear format.

                Final Code:
                {generated_code}
                """)
            .model("gemini-2.5-flash")
            .build();

        AdkWebServer.start(SequentialAgent.builder()
            .name("code-refiner-assistant")
            .description("Manages the full code generation and refinement process.")
            .subAgents(
                codeRefinerLoop,
                finalPresenter)
            .build());
    }
}

شغِّل هذا الوكيل باستخدام الأمر التالي:

mvn compile exec:java -Dexec.mainClass=com.example.agent.CodeRefiner

يمكنك أن تطلب منه تنفيذ شيء معقّد مثل Tower of Hanoi أو Quicksort Algorithm.

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

11. تهانينا!

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

ما هي الخطوات التالية؟

• استكشِف مستودع GitHub الرسمي الخاص بـ "حزمة تطوير الوكلاء" للغة Java.
• يمكنك الاطّلاع على مزيد من المعلومات عن إطار العمل في المستندات.
• يمكنك الاطّلاع على مختلف مهام سير العمل المستندة إلى الوكلاء في سلسلة المدونات هذه، وعلى الأدوات المختلفة المتاحة.
• تعرَّف على الأدوات المضمّنة الأخرى وعمليات رد الاتصال المتقدّمة.
• التعامل مع السياق والحالة والنتائج للحصول على تفاعلات أكثر ثراءً ومتعددة الوسائط
• تنفيذ وتطبيق المكوّنات الإضافية التي تتكامل مع دورة حياة الوكلاء
• جرِّب إنشاء وكيلك الخاص الذي يحلّ مشكلة واقعية.