درس تعليمي لـ Google ADK: بناء وكلاء الذكاء الاصطناعي من الصفر حتى الإنتاج

درس تعليمي لـ Google ADK: بناء وكلاء الذكاء الاصطناعي من الصفر حتى الإنتاج

مجموعة أدوات تطوير الوكلاء من Google هي الإطار البرمجي الذي يجعل أنظمة الوكلاء المتعددة في متناول الجميع. إذا كنت تبني وكلاء ذكاء اصطناعي باستخدام LangChain أو CrewAI وشعرت أنك تصارع الإطار البرمجي بدلاً من البناء عليه، فهذا الدرس التعليمي لـ Google ADK يأخذك خطوة بخطوة — من أول وكيل لك وصولاً إلى نشره على Cloud Run.

ما هو Google ADK (ولماذا يهمك أمره)؟

مجموعة أدوات تطوير الوكلاء (ADK) من Google هي إطار برمجي مفتوح المصدر بلغة Python لبناء وتقييم ونشر وكلاء الذكاء الاصطناعي. صدر عام 2025، وهو محسَّن للعمل مع Gemini لكنه يدعم أكثر من 100 نموذج عبر LiteLLM. الميزة الفارقة في ADK هي التنسيق الأصلي لأنظمة الوكلاء المتعددة — وكلاء تُفوِّض المهام لوكلاء آخرين دون الحاجة لكود وصل معقد.

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

إذا كان LangChain سكينة جيش سويسرية متعددة الاستخدامات، فإن ADK هي مجموعة أدوات Google المصممة خصيصاً لسير عمل الوكلاء المتعددة. CrewAI أقرب في الفلسفة — وكلاء قائمة على الأدوار تتعاون — لكن ADK يذهب أبعد مع التقييم المدمج، وتحسين Gemini الأصلي، ونشر Cloud Run بأمر واحد. للاطلاع على مقارنة أعمق، راجع مقارنتنا التفصيلية لأطر عمل الوكلاء.

لمن هو ADK؟ لمطوري Python الذين يريدون أنظمة وكلاء متعددة منظمة. للفرق العاملة على Google Cloud أو Gemini بالفعل. ولكل من يمل من كتابة منطق التنسيق المكرر.

إليك مقارنة سريعة بين الأطر البرمجية:

الخلاصة المختصرة: إذا كنت تريد أسرع مسار من "فكرة" إلى "نظام وكلاء متعددة منشور"، فـ ADK صعب المنافسة في الوقت الحالي.

المتطلبات الأساسية وتثبيت Google ADK

للبدء مع Google ADK، تحتاج إلى Python 3.9 أو أحدث، ومفتاح Gemini API (الطبقة المجانية متاحة في Google AI Studio)، وحزمة google-adk. ثبّت بـ pip install google-adk، واضبط مفتاح API كمتغير بيئة، وستكون جاهزاً لبناء أول وكيل في أقل من 5 دقائق.

إليك قائمة التحقق من الإعداد:

• Python 3.9+ (3.10+ موصى به للحصول على دعم كامل لتلميحات الأنواع)
• مفتاح Gemini API — احصل على واحد مجاناً من aistudio.google.com. الطبقة المجانية توفر 15 طلباً في الدقيقة، وهو أكثر من كافٍ للتطوير.
• pip (أو uv إذا كنت تفضل السرعة — uv pip install google-adk تعمل أيضاً)

ثبّت الحزمة واضبط مفتاحك:

pip install google-adk

# اضبط مفتاح API الخاص بك (أضفه إلى .bashrc/.zshrc للحفاظ عليه)
export GOOGLE_API_KEY="your-api-key-here"

يتوقع ADK هيكلاً محدداً للمجلدات. كل وكيل يعيش في مجلد الحزمة الخاص به:

my_agent/
  __init__.py    # تصدير root_agent
  agent.py       # تعريف الوكيل
.env             # اختياري: GOOGLE_API_KEY=your-key

اسم المجلد يصبح اسم حزمة الوكيل، لذا اختر اسماً وصفياً. لا تسمّه test أو agent — ستُربك نظام استيراد Python.

نصيحة متقدمة: إذا كنت تستخدم uv، أنشئ بيئة افتراضية أولاً بـ uv venv && source .venv/bin/activate. إنها أسرع بشكل ملحوظ من pip العادية لحل التبعيات.

بناء أول وكيل لك باستخدام Google ADK

يحتاج أول وكيل ADK لك إلى ثلاثة أشياء فقط: اسم، ونموذج (مثل gemini-2.0-flash)، وسلسلة تعليمات. عرِّفه في agent.py، وضعه داخل مجلد يحتوي على __init__.py، وشغِّل adk web للتحدث معه عبر واجهة المتصفح. الإعداد بأكمله لا يتجاوز 10 أسطر من Python.

أنشئ مجلداً باسم my_agent وأضف ملفين. أولاً، تعريف الوكيل:

# my_agent/agent.py
from google.adk.agents import LlmAgent

root_agent = LlmAgent(
    name="my_assistant",
    model="gemini-2.0-flash",
    instruction="""You are a helpful coding assistant. 
    You explain concepts clearly and provide working code examples.
    Keep responses concise but thorough.""",
    description="A coding assistant that explains concepts and writes code"
)

ثم ملف init الذي يصدّر وكيلك:

# my_agent/__init__.py
from .agent import root_agent

اسم المتغير مهم — ADK يبحث عن root_agent تحديداً. افتقدته وستحصل على خطأ "agent not found" لا يشرح السبب.

الآن شغّله. لديك خياران:

# وضع CLI — تحدث في طرفيتك
adk run my_agent

# وضع واجهة الويب — يفتح واجهة في المتصفح
adk web my_agent

واجهة adk web مفيدة فعلاً. تُظهر لك تتبع المحادثة الكامل، والأدوات التي استدعاها الوكيل، وما استقبله النموذج، وما أعاده. فكّر فيها كـ Chrome DevTools لوكيلك. حين تبدأ في بناء أنظمة الوكلاء المتعددة لاحقاً، تصبح ضرورية لفهم تدفق التفويض.

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

إضافة أدوات مخصصة لوكيل Google ADK الخاص بك

تصبح وكلاء ADK مفيدةً حين تمنحها أدوات. عرِّف دالة Python بتوثيق docstring واضح، وسيحوّلها ADK تلقائياً إلى أداة يمكن للوكيل استدعاؤها. الـ docstring أمر بالغ الأهمية — تُخبر النموذج ما تفعله الأداة ومتى يستخدمها. كذلك يأتي ADK بأدوات مدمجة كـ Google Search وتنفيذ الكود.

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

أدوات الدوال المخصصة

إليك مثال عملي — أداة تبحث عن أسعار الأسهم:

# my_agent/agent.py
from google.adk.agents import LlmAgent

def get_stock_price(ticker: str) -> dict:
    """Get the current stock price for a given ticker symbol.
    
    Args:
        ticker: The stock ticker symbol (e.g., 'AAPL', 'GOOGL', 'MSFT')
    
    Returns:
        A dictionary with the ticker and its current price.
    """
    # في الإنتاج، ستستدعي API حقيقية هنا
    mock_prices = {"AAPL": 198.50, "GOOGL": 175.20, "MSFT": 425.80}
    price = mock_prices.get(ticker.upper(), None)
    if price:
        return {"ticker": ticker.upper(), "price": price, "currency": "USD"}
    return {"error": f"Ticker {ticker} not found"}

root_agent = LlmAgent(
    name="finance_assistant",
    model="gemini-2.0-flash",
    instruction="You help users check stock prices. Use the get_stock_price tool when asked about any stock.",
    tools=[get_stock_price],
    description="A financial assistant that looks up stock prices"
)

لاحظ تلميحات الأنواع والـ docstring. هذه ليست رفاهية اختيارية — ADK يستخدمها لتوليد مخطط الأداة الذي يراه النموذج. أغفل الـ docstring ولن يعرف النموذج متى يستدعي دالتك. أغفل تلميحات الأنواع وستحصل على خطأ في التوقيع.

الأدوات المدمجة (Google Search، تنفيذ الكود)

يأتي ADK بأدوات يمكنك إضافتها دون كتابة أي كود:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search, code_execution

root_agent = LlmAgent(
    name="research_agent",
    model="gemini-2.0-flash",
    instruction="You research topics using Google Search and can run Python code to analyze data.",
    tools=[google_search, code_execution],
    description="A research agent with search and code execution capabilities"
)

google_search تتيح للوكيل الاستعلام على الويب في الوقت الفعلي. code_execution تمنحه بيئة Python معزولة لإجراء الحسابات. هاتان الأداتان وحدهما تغطيان عدداً مدهشاً من حالات الاستخدام.

أنظمة الوكلاء المتعددة: كيف تُفوِّض وكلاء Google ADK العمل

يستخدم نظام الوكلاء المتعددة في ADK وكيلاً جذراً يُفوِّض المهام لوكلاء فرعية متخصصة. كل وكيل فرعي يتعامل مع مجال واحد — البحث، الكتابة، البرمجة. الوكيل الجذر يقرر أي وكيل فرعي يستدعي بناءً على طلب المستخدم. يمكنك أيضاً استخدام نمط الوكيل-كأداة، حيث يستدعي وكيل آخر كما لو كان دالة. يتعمق مدونة Google الرسمية حول أنظمة الوكلاء المتعددة في أنماط المعمارية.

فكّر في الأمر كمدير مشروع يُفوِّض لمتخصصين. الوكيل الجذر يقرأ طلب المستخدم، يحدد أي متخصص يجب أن يتولاه، ويوجّهه وفق ذلك. الوكلاء الفرعية لا تعرف بعضها — تؤدي عملها وتُبلِّغ بالنتائج فحسب.

نمط الوكيل الجذر + الوكلاء الفرعية

إليك مثال عملي مع وكيل جذر يُفوِّض لوكيل بحث ووكيل كتابة:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search

# الوكيل الفرعي 1: يتولى البحث
research_agent = LlmAgent(
    name="researcher",
    model="gemini-2.0-flash",
    instruction="You research topics thoroughly using Google Search. Return factual, well-sourced information.",
    tools=[google_search],
    description="Researches topics and returns factual information"
)

# الوكيل الفرعي 2: يتولى الكتابة
writing_agent = LlmAgent(
    name="writer",
    model="gemini-2.0-flash",
    instruction="You write clear, engaging content based on provided information. Focus on readability and accuracy.",
    description="Writes polished content from research notes"
)

# الوكيل الجذر: يُفوِّض للوكيل المناسب
root_agent = LlmAgent(
    name="content_manager",
    model="gemini-2.0-flash",
    instruction="""You manage content creation. 
    - When the user wants information gathered, delegate to the researcher.
    - When the user wants content written or edited, delegate to the writer.
    - You can chain both: research first, then write.""",
    sub_agents=[research_agent, writing_agent],
    description="Manages content creation by delegating to research and writing specialists"
)

حقل description في كل وكيل فرعي هو الطريقة التي يفهم بها الوكيل الجذر ما يمكنه فعله. اكتب أوصافاً واضحة — الغامضة منها تؤدي إلى قرارات توجيه سيئة.

نمط الوكيل-كأداة

أحياناً تريد مزيداً من التحكم في كيفية استدعاء وكيل لآخر. نمط الوكيل-كأداة يُغلّف وكيلاً فرعياً كأداة قابلة للاستدعاء:

from google.adk.tools import agent_tool

research_tool = agent_tool.AgentTool(agent=research_agent)

root_agent = LlmAgent(
    name="writer_with_research",
    model="gemini-2.0-flash",
    instruction="You write articles. Use the research tool to gather facts before writing.",
    tools=[research_tool],
    description="A writer that can research topics on demand"
)

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

وكلاء سير العمل: التسلسلي والمتوازي والحلقي

ما وراء التفويض المدفوع بنموذج اللغة، يقدم ADK ثلاثة أنواع من وكلاء سير العمل لتنسيق حتمي: SequentialAgent يُشغِّل الوكلاء الفرعية واحداً تلو الآخر، ParallelAgent يُشغِّلها في آنٍ واحد، وLoopAgent يكرر تسلسلاً حتى تتحقق شرط معين. هذه مفيدة حين تحتاج ترتيباً تنفيذياً متوقعاً بدلاً من ترك النموذج يقرر.

الفارق مهم. التفويض المدفوع بنموذج اللغة (نمط sub_agents أعلاه) يترك للنموذج اختيار من يستدعي. وكلاء سير العمل تمنحك تحكماً برمجياً. استخدم وكلاء سير العمل حين يكون ترتيب التنفيذ معروفاً مسبقاً.

from google.adk.agents import SequentialAgent, ParallelAgent, LlmAgent

# ثلاثة وكلاء يجب أن تعمل بالترتيب
research_agent = LlmAgent(name="researcher", model="gemini-2.0-flash",
    instruction="Research the given topic.", description="Researches topics")
    
draft_agent = LlmAgent(name="drafter", model="gemini-2.0-flash",
    instruction="Write a draft based on the research.", description="Writes drafts")
    
review_agent = LlmAgent(name="reviewer", model="gemini-2.0-flash",
    instruction="Review the draft for accuracy and clarity.", description="Reviews content")

# خط الأنابيب: بحث -> مسودة -> مراجعة
content_pipeline = SequentialAgent(
    name="content_pipeline",
    sub_agents=[research_agent, draft_agent, review_agent],
    description="Runs a complete content creation pipeline"
)

للمهام المستقلة التي يمكن تشغيلها في آنٍ واحد، يوفّر ParallelAgent وقتاً حقيقياً:

# ثلاثة جالبي بيانات يعملون بالتوازي
fetch_news = LlmAgent(name="news_fetcher", model="gemini-2.0-flash",
    instruction="Fetch latest tech news.", description="Fetches news")
    
fetch_stocks = LlmAgent(name="stock_fetcher", model="gemini-2.0-flash",
    instruction="Fetch stock market summary.", description="Fetches stocks")
    
fetch_weather = LlmAgent(name="weather_fetcher", model="gemini-2.0-flash",
    instruction="Fetch weather forecast.", description="Fetches weather")

morning_briefing = ParallelAgent(
    name="morning_briefing",
    sub_agents=[fetch_news, fetch_stocks, fetch_weather],
    description="Gathers morning briefing data in parallel"
)

إدارة الحالة والذاكرة

يدير ADK حالة الوكيل على مستويين: حالة الجلسة (البيانات داخل محادثة، كتفضيلات المستخدم المجموعة أثناء الدردشة) وخدمات الذاكرة (البيانات التي تستمر عبر المحادثات). حالة الجلسة هي مخزن بسيط لأزواج المفتاح-القيمة يُوصَل إليه عبر context.state. الذاكرة تستخدم خدمات مثل InMemoryMemoryService أو VertexAIMemoryBankService للإنتاج.

حالة الجلسة هي الأبسط. إنها قاموس مرتبط بكل محادثة:

from google.adk.agents import LlmAgent

def save_preference(key: str, value: str, context) -> str:
    """Save a user preference to session state.
    
    Args:
        key: The preference name (e.g., 'language', 'theme')
        value: The preference value
        context: The ADK context object
    
    Returns:
        Confirmation message
    """
    context.state[key] = value
    return f"Saved preference: {key} = {value}"

def get_preference(key: str, context) -> str:
    """Retrieve a user preference from session state.
    
    Args:
        key: The preference name to look up
        context: The ADK context object
    
    Returns:
        The preference value or a not-found message
    """
    value = context.state.get(key, "Not set")
    return f"{key} = {value}"

root_agent = LlmAgent(
    name="personalized_assistant",
    model="gemini-2.0-flash",
    instruction="You remember user preferences. Save them when told, recall them when asked.",
    tools=[save_preference, get_preference],
    description="An assistant that remembers user preferences"
)

للذاكرة عبر المحادثات — النوع الذي يجعل وكيلك يتذكر مستخدماً من الثلاثاء الماضي — تحتاج خدمة ذاكرة:

from google.adk.memory import InMemoryMemoryService

# للتطوير (البيانات تُفقد عند إعادة التشغيل)
memory_service = InMemoryMemoryService()

# للإنتاج، استخدم VertexAIMemoryBankService
# memory_service = VertexAIMemoryBankService(project="your-project")

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

الاستدعاءات الراجعة: التحكم في سلوك الوكيل

تتيح لك الاستدعاءات الراجعة في ADK اعتراض سلوك الوكيل وتعديله في أربع نقاط: before_model_callback (قبل استدعاء نموذج اللغة)، after_model_callback (بعد رد نموذج اللغة)، before_tool_callback (قبل تنفيذ الأداة)، وafter_tool_callback (بعد نتيجة الأداة). استخدمها للتحقق من المدخلات، وتصفية المحتوى للسلامة، والتسجيل، أو تعديل الردود قبل وصولها للمستخدم.

الاستدعاءات الراجعة هي المكان الذي تضيف فيه الحواجز الأمنية. فكّر فيها كـ middleware لوكيلك — كل طلب ورد يمر خلالها، ويمكنك فحص أو تعديل أو حجب أي شيء.

from google.adk.agents import LlmAgent

def safety_filter(callback_context, llm_request):
    """Block requests containing harmful content patterns."""
    user_message = str(llm_request)
    blocked_patterns = ["ignore your instructions", "pretend you are"]
    
    for pattern in blocked_patterns:
        if pattern.lower() in user_message.lower():
            # إعادة رد مباشرة، متجاوزاً استدعاء النموذج
            return {"blocked": True, "reason": "Request matched safety filter"}
    
    # إعادة None للمتابعة عادياً
    return None

def log_tool_usage(callback_context, tool_name, tool_result):
    """Log every tool call for monitoring."""
    print(f"[TOOL LOG] {tool_name}: {tool_result}")
    return None  # لا تعدّل النتيجة

root_agent = LlmAgent(
    name="safe_assistant",
    model="gemini-2.0-flash",
    instruction="You are a helpful assistant.",
    before_model_callback=safety_filter,
    after_tool_callback=log_tool_usage,
    description="A safety-filtered assistant with tool logging"
)

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

اختبار وتقييم وكلاء ADK الخاصة بك

يتضمن ADK إطار تقييم مدمجاً بنوعين من المقيِّمين: ResponseEvaluator يتحقق من صحة الإجابة النهائية للوكيل، وTrajectoryEvaluator يتحقق من أن الوكيل اتخذ الخطوات الصحيحة — استدعى الأدوات الصحيحة بالترتيب الصحيح. اكتب حالات الاختبار كملفات JSON وشغِّلها مع pytest لاكتشاف التراجعات قبل النشر.

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

حالات اختبارك تذهب في ملف JSON:

[
  {
    "input": "What's the stock price of AAPL?",
    "expected_output": "198.50",
    "expected_trajectory": [
      {"tool_name": "get_stock_price", "args": {"ticker": "AAPL"}}
    ]
  },
  {
    "input": "Compare AAPL and GOOGL prices",
    "expected_output": "AAPL.*198.*GOOGL.*175",
    "expected_trajectory": [
      {"tool_name": "get_stock_price", "args": {"ticker": "AAPL"}},
      {"tool_name": "get_stock_price", "args": {"ticker": "GOOGL"}}
    ]
  }
]

ثم شغِّل التقييمات مع pytest. يحتوي مستودع ADK Python على مرجع كامل لواجهة برمجة التقييم:

# test_agent.py
import pytest
from google.adk.evaluation import ResponseEvaluator, TrajectoryEvaluator

def test_stock_agent_response():
    evaluator = ResponseEvaluator(agent=root_agent)
    results = evaluator.evaluate("test_cases.json")
    
    assert results.pass_rate >= 0.8, f"Response pass rate too low: {results.pass_rate}"

def test_stock_agent_trajectory():
    evaluator = TrajectoryEvaluator(agent=root_agent)
    results = evaluator.evaluate("test_cases.json")
    
    assert results.pass_rate >= 0.9, f"Trajectory pass rate too low: {results.pass_rate}"

شغِّل بـ pytest test_agent.py -v. اضبط عتباتك بناءً على الأهمية — دقة استجابة 80% قد تكون مقبولة لوكيل كتابة إبداعية، لكنك ستريد 95%+ لأي شيء يتعامل مع بيانات مالية.

نشر وكيل Google ADK الخاص بك على الإنتاج

انشر وكيل ADK على Google Cloud Run بأمر واحد: adk deploy cloud_run --project YOUR_PROJECT --region us-central1. ADK يُغلّف كودك، يبني حاوية، ويُطلق نقطة نهاية بدون خادم. للاستضافة المُدارة، استخدم Vertex AI Agent Engine. للبنية التحتية المخصصة، يدعم ADK أيضاً حاويات Docker.

لقد نشرنا وكلاء ADK على Cloud Run لأدوات داخلية، وأوقات البدء الباردة سريعة بشكل مفاجئ — أقل من 3 ثوانٍ لوكيل أساسي. للأنظمة الإنتاجية، فكّر في إقران نشرك مع أدوات المراقبة لوكلاء الإنتاج.

النشر على Cloud Run (الموصى به لمعظم الحالات)

Cloud Run هو المسار الأبسط. أمر واحد ووكيلك على الهواء بنقطة نهاية HTTPS:

adk deploy cloud_run \
  --project your-gcp-project-id \
  --region us-central1 \
  --service-name my-agent-service \
  --with_ui

علامة --with_ui تنشر واجهة ADK Web جنباً إلى جنب مع وكيلك، لتحصل على دردشة قائمة على المتصفح للاختبار في الإنتاج. خلف الكواليس، يبني ADK صورة حاوية، يدفعها إلى Google Artifact Registry، وينشئ خدمة Cloud Run. تدفق النشر الكامل موثق في البدء السريع لـ Google Cloud Run مع ADK.

للبنية التحتية المخصصة، إليك ملف Dockerfile بسيط:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["adk", "api_server", "--port", "8080", "my_agent"]

البديل: Vertex AI Agent Engine

للفرق المؤسسية التي تحتاج قياساً مُداراً ومراقبة وإصدارات، يتولى Vertex AI Agent Engine البنية التحتية بالكامل. تتداول المرونة مقابل الراحة — لا حاويات لإدارتها، قياس تلقائي، وتحليلات مدمجة.

اعتبارات التكلفة

أرقام حقيقية يجب أن تعرفها:

• الطبقة المجانية لـ Gemini API: 15 طلباً في الدقيقة، مليون رمز يومياً. كافٍ للتطوير والعروض التوضيحية الخفيفة.
• Gemini 2.0 Flash (مدفوع): $0.10 لكل مليون رمز مدخل، $0.40 لكل مليون رمز مخرج. رخيص بما يكفي للإنتاج.
• الطبقة المجانية لـ Cloud Run: مليونا طلب شهرياً، 360,000 GB-ثانية من الحوسبة. وكيل أساسي يتعامل مع 1,000 طلب يومياً يبقى جيداً ضمن الطبقة المجانية.
• نصيحة للتحسين: استخدم gemini-2.0-flash (وليس gemini-2.0-pro) للوكلاء الفرعية التي تقوم بتوجيه أو تنسيق بسيط. احتفظ بالنماذج الأكثر قدرة للوكلاء التي تجري استدلالاً معقداً.

كيف تتعامل Techsy مع تطوير وكلاء الذكاء الاصطناعي

في Techsy، بنينا أنظمة وكلاء متعددة لعملاء باستخدام ADK وLangGraph وCrewAI. اختيار الإطار البرمجي يعتمد على مجموعتك التقنية: إذا كنت على Google Cloud بالفعل، فإن ADK يُزيل الكثير من احتكاك التكامل. إذا كنت تحتاج دعم نماذج متعددة المزودين من البداية، فإن LangGraph يمنحك مرونة أكبر.

مشاركتنا النموذجية تبدأ بالاستشارة المعمارية — تعيين حالة استخدامك على أنماط الوكلاء الصحيحة — يليها تطوير النموذج الأولي ونشره على Cloud Run. وجدنا أن الفرق توفر من 2 إلى 3 أسابيع بالحصول على المعمارية الصحيحة مقدماً بدلاً من إعادة الهيكلة لاحقاً.

تبني وكلاء ذكاء اصطناعي لفريقك؟ احصل على استشارة مجانية — سنساعدك في اختيار الإطار البرمجي الصحيح واستراتيجية النشر.

الأخطاء الشائعة واستكشاف المشكلات

هذه هي الأخطاء التي نصطدم بها أكثر ما يكون عند البدء مع ADK. وفّر على نفسك وقت التنقيح:

نصيحة للتنقيح: adk web هو أفضل صديق لك هنا. يُظهر تتبع المحادثة الكامل — كل استدعاء للنموذج، واستدعاء الأداة، وتفويض الوكيل — في الوقت الفعلي. حين يسوء الأمر في نظام الوكلاء المتعددة، تُظهر لك واجهة الويب بالضبط أين انكسرت السلسلة.

الأسئلة الشائعة

ما هو Google ADK؟

مجموعة أدوات تطوير الوكلاء (ADK) من Google هي إطار برمجي مفتوح المصدر بلغة Python لبناء وتقييم ونشر وكلاء الذكاء الاصطناعي. محسَّن لنماذج Google Gemini لكنه يدعم أكثر من 100 نموذج لغوي كبير عبر تكامل LiteLLM. قوة ADK الجوهرية هي التنسيق الأصلي لتعدد الوكلاء مع أدوات مدمجة وواجهة تطوير ونشر بأمر واحد على Cloud Run.

هل Google ADK مجاني للاستخدام؟

نعم. ADK نفسه مفتوح المصدر تحت رخصة Apache 2.0. تحتاج مفتاح Gemini API، الذي يملك طبقة مجانية توفر 15 طلباً في الدقيقة ومليون رمز يومياً. تكاليف النشر السحابي تعتمد على خيار الاستضافة — الطبقة المجانية لـ Cloud Run تغطي مليوني طلب شهرياً.

ما الفرق بين Google ADK وLangChain؟

ADK هو إطار Google المُتحيّز المحسَّن لـ Gemini مع تنسيق أصلي لتعدد الوكلاء وأدوات نشر مدمجة. LangChain مستقل عن النموذج مع تكاملات أطراف ثالثة أوسع لكنه أكثر تعقيداً بكثير. ADK أفضل للفرق الأولى بـ Gemini التي تريد نشراً سريعاً؛ LangChain يناسب الإعدادات متعددة المزودين التي تحتاج أقصى مرونة.

هل يدعم Google ADK أنظمة الوكلاء المتعددة؟

نعم، وهي الميزة الرئيسية لـ ADK. تنشئ وكيلاً جذراً يُفوِّض لوكلاء فرعية متخصصة بناءً على طلبات المستخدم. يقدم ADK أيضاً SequentialAgent وParallelAgent وLoopAgent لتنسيق سير العمل الحتمي. نمط الوكيل-كأداة يتيح للوكلاء استدعاء وكلاء أخرى كدوال قابلة للاستدعاء.

كيف أنشر وكيل Google ADK؟

شغِّل adk deploy cloud_run --project YOUR_PROJECT --region us-central1 للنشر بدون خادم على Google Cloud Run. أضف --with_ui لتضمين واجهة الدردشة القائمة على المتصفح. يمكنك أيضاً النشر على Vertex AI Agent Engine للاستضافة المُدارة، أو بناء حاوية Docker للبنية التحتية المخصصة.

هل يمكن لـ Google ADK استخدام نماذج غير Gemini؟

نعم. يدعم ADK أكثر من 100 نموذج عبر تكامل LiteLLM، بما فيها Anthropic Claude وOpenAI GPT-4 وMeta Llama وMistral. اضبط معامل النموذج على سلسلة نموذج LiteLLM — مثلاً، litellm/anthropic/claude-3-sonnet أو litellm/openai/gpt-4o. نماذج Gemini تعمل بشكل أصلي دون بادئة LiteLLM.

ما هي واجهة ADK Web UI؟

واجهة تنقيح قائمة على المتصفح تُطلق بـ adk web your_agent_folder. تعرض تتبع المحادثة في الوقت الفعلي، واستدعاءات الأدوات، وسلاسل تفويض الوكلاء، وتغييرات الحالة حال حدوثها. واجهة الويب ضرورية لتنقيح أنظمة الوكلاء المتعددة لأنها تُظهر بالضبط أي وكيل فرعي تولى كل طلب.

هل يدعم Google ADK بروتوكول سياق النموذج (MCP)؟

نعم. يدعم ADK بروتوكول سياق النموذج بشكل أصلي، مما يتيح للوكلاء الاتصال بأي خادم أدوات متوافق مع MCP للأدوات ومصادر البيانات الخارجية. هذا يجعل وكلاء ADK قابلة للتشغيل البيني مع منظومة MCP المتنامية. للاطلاع على خلفية البروتوكول، راجع دليلنا لـ MCP.

كيف أختبر وكلاء ADK؟

يأتي ADK بمقيِّمين مدمجين: ResponseEvaluator للتحقق من جودة المخرج مقابل الإجابات المتوقعة، وTrajectoryEvaluator للتحقق من أن الوكيل استدعى الأدوات الصحيحة بالترتيب الصحيح. اكتب حالات الاختبار كملفات JSON تحدد المدخلات والمخرجات المتوقعة وتسلسلات استدعاء الأدوات المتوقعة، ثم شغِّلها مع pytest.

ما إصدار Python الذي يتطلبه Google ADK؟

يتطلب ADK Python 3.9 أو أعلى. يوصى بـ Python 3.10+ للحصول على دعم كامل لتلميحات الأنواع، وهو مهم لأن ADK يستخدم تلميحات الأنواع لتوليد مخططات الأدوات. Python 3.11 أو 3.12 يقدمان أيضاً تحسينات أداء ذات مغزى لأحمال عمل الوكلاء. ثبّت بـ pip install google-adk.