بناء وكلاء ذكاء اصطناعي باستخدام Google ADK و TypeScript: دليل شامل من الصفر

mkdir my-adk-agent
cd my-adk-agent
npm init -y

npm install @google/adk @google/adk-devtools
npm install -D typescript

{
  "compilerOptions": {
    "target": "es2020",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "verbatimModuleSyntax": false
  }
}

GOOGLE_GENAI_API_KEY=your_api_key_here
GOOGLE_GENAI_USE_VERTEXAI=false

// agent.ts
import { Agent } from "@google/adk";
 
const agent = new Agent({
  name: "MyAssistant",
  model: "gemini-2.5-flash",
  instruction: `أنت مساعد ذكي باللغة العربية.
    أجب على أسئلة المستخدم بدقة ووضوح.
    استخدم الأدوات المتاحة عند الحاجة.`,
});
 
export default agent;

npx adk run agent.ts

npx adk web

npx adk api_server

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "ما هي عاصمة تونس؟"}'

// tools/weather.ts
import { FunctionTool } from "@google/adk";
import { z } from "zod";
 
const weatherData: Record<string, { temp: number; condition: string }> = {
  tunis: { temp: 18, condition: "مشمس جزئياً" },
  riyadh: { temp: 32, condition: "مشمس وحار" },
  cairo: { temp: 25, condition: "صافي" },
  dubai: { temp: 35, condition: "مشمس" },
  casablanca: { temp: 20, condition: "غائم جزئياً" },
};
 
export const getWeather = new FunctionTool({
  name: "get_weather",
  description: "الحصول على معلومات الطقس الحالية لمدينة محددة",
  parameters: z.object({
    city: z
      .string()
      .describe("اسم المدينة بالإنجليزية مثل: tunis, riyadh, cairo"),
  }),
  handler: async ({ city }) => {
    const normalizedCity = city.toLowerCase().trim();
    const weather = weatherData[normalizedCity];
 
    if (!weather) {
      return {
        error: `لا تتوفر بيانات طقس للمدينة: ${city}`,
        availableCities: Object.keys(weatherData),
      };
    }
 
    return {
      city: normalizedCity,
      temperature: weather.temp,
      condition: weather.condition,
      unit: "celsius",
    };
  },
});

// tools/calculator.ts
import { FunctionTool } from "@google/adk";
import { z } from "zod";
 
export const calculate = new FunctionTool({
  name: "calculate",
  description: "تنفيذ عمليات حسابية رياضية",
  parameters: z.object({
    expression: z
      .string()
      .describe("التعبير الحسابي مثل: 2 + 3 * 4"),
  }),
  handler: async ({ expression }) => {
    // تنظيف التعبير والسماح فقط بالأحرف الحسابية الآمنة
    const sanitized = expression.replace(/[^0-9+\-*/().%\s]/g, "");
 
    if (sanitized !== expression.trim()) {
      return { error: "التعبير يحتوي على أحرف غير مسموح بها" };
    }
 
    try {
      const result = Function(`"use strict"; return (${sanitized})`)();
      return {
        expression: sanitized,
        result: Number(result),
      };
    } catch {
      return { error: `فشل في حساب التعبير: ${sanitized}` };
    }
  },
});

// tools/search.ts
import { FunctionTool } from "@google/adk";
import { z } from "zod";
 
export const searchWeb = new FunctionTool({
  name: "search_web",
  description: "البحث في الويب عن معلومات محدثة حول موضوع معين",
  parameters: z.object({
    query: z.string().describe("عبارة البحث"),
    language: z
      .enum(["ar", "en", "fr"])
      .optional()
      .describe("لغة النتائج المطلوبة"),
  }),
  handler: async ({ query, language = "ar" }) => {
    // في بيئة الإنتاج، استخدم Google Custom Search API أو SerpAPI
    // هذا مثال توضيحي
    return {
      query,
      language,
      results: [
        {
          title: `نتيجة بحث عن: ${query}`,
          snippet: `معلومات محدثة حول ${query} في عام 2026...`,
          url: `https://example.com/search?q=${encodeURIComponent(query)}`,
        },
      ],
      note: "في الإنتاج، اربط هذا بـ Google Custom Search API",
    };
  },
});

// agent.ts
import { Agent } from "@google/adk";
import { getWeather } from "./tools/weather.js";
import { calculate } from "./tools/calculator.js";
import { searchWeb } from "./tools/search.js";
 
const agent = new Agent({
  name: "SmartAssistant",
  model: "gemini-2.5-flash",
  instruction: `أنت مساعد ذكي متعدد القدرات. لديك الأدوات التالية:
 
    1. **get_weather**: للحصول على معلومات الطقس. استخدمها عندما يسأل المستخدم عن الطقس.
    2. **calculate**: لتنفيذ العمليات الحسابية. استخدمها لأي حسابات رياضية.
    3. **search_web**: للبحث في الويب. استخدمها للمعلومات المحدثة.
 
    قواعد مهمة:
    - أجب دائماً بالعربية
    - استخدم الأدوات فقط عند الحاجة
    - إذا سأل المستخدم سؤالاً عاماً، أجب من معرفتك مباشرة
    - قدم إجابات واضحة ومنظمة`,
  tools: [getWeather, calculate, searchWeb],
});
 
export default agent;

// agents/researcher.ts
import { Agent } from "@google/adk";
import { searchWeb } from "../tools/search.js";
 
export const researcher = new Agent({
  name: "Researcher",
  model: "gemini-2.5-flash",
  description: "وكيل متخصص في البحث وجمع المعلومات حول موضوع محدد",
  instruction: `أنت باحث متخصص. مهمتك:
    1. ابحث عن المعلومات المطلوبة باستخدام أداة البحث
    2. نظّم النتائج في نقاط واضحة
    3. حدد المصادر الموثوقة
    4. قدم ملخصاً شاملاً للنتائج
 
    اكتب نتائجك بالعربية بشكل منظم.`,
  tools: [searchWeb],
  outputKey: "research_results",
});

// agents/writer.ts
import { Agent } from "@google/adk";
 
export const writer = new Agent({
  name: "Writer",
  model: "gemini-2.5-flash",
  description: "وكيل متخصص في كتابة محتوى احترافي بناءً على بيانات البحث",
  instruction: `أنت كاتب محتوى محترف. مهمتك:
    1. اقرأ نتائج البحث من {research_results}
    2. اكتب مقالاً منظماً وجذاباً بناءً على هذه النتائج
    3. استخدم عناوين فرعية واضحة
    4. أضف مقدمة جذابة وخاتمة ملخصة
 
    اكتب بالعربية بأسلوب احترافي وسلس.`,
  outputKey: "final_article",
});

// agent.ts - نظام الوكلاء المتعددين
import { Agent, SequentialAgent } from "@google/adk";
import { researcher } from "./agents/researcher.js";
import { writer } from "./agents/writer.js";
 
const contentPipeline = new SequentialAgent({
  name: "ContentPipeline",
  description: "خط إنتاج المحتوى: بحث ثم كتابة",
  subAgents: [researcher, writer],
});
 
// الوكيل الرئيسي الذي ينسق كل شيء
const orchestrator = new Agent({
  name: "Orchestrator",
  model: "gemini-2.5-flash",
  instruction: `أنت منسق ذكي. عندما يطلب المستخدم كتابة مقال أو محتوى:
    1. وجّه المهمة إلى خط إنتاج المحتوى
    2. قدم النتيجة النهائية للمستخدم
 
    للأسئلة البسيطة، أجب مباشرة.`,
  subAgents: [contentPipeline],
});
 
export default orchestrator;

import { Agent, ParallelAgent, SequentialAgent } from "@google/adk";
 
// وكيل يبحث في مصادر عربية
const arabicResearcher = new Agent({
  name: "ArabicResearcher",
  model: "gemini-2.5-flash",
  instruction: "ابحث عن الموضوع في مصادر عربية وقدم النتائج بالعربية.",
  tools: [searchWeb],
  outputKey: "arabic_research",
});
 
// وكيل يبحث في مصادر إنجليزية
const englishResearcher = new Agent({
  name: "EnglishResearcher",
  model: "gemini-2.5-flash",
  instruction: "Search for the topic in English sources and summarize findings.",
  tools: [searchWeb],
  outputKey: "english_research",
});
 
// البحث المتوازي: كلا الوكيلين يعملان في نفس الوقت
const parallelResearch = new ParallelAgent({
  name: "ParallelResearch",
  description: "بحث متوازي في مصادر عربية وإنجليزية",
  subAgents: [arabicResearcher, englishResearcher],
});
 
// وكيل يدمج النتائج
const synthesizer = new Agent({
  name: "Synthesizer",
  model: "gemini-2.5-flash",
  instruction: `اقرأ نتائج البحث من:
    - المصادر العربية: {arabic_research}
    - المصادر الإنجليزية: {english_research}
 
    ادمج النتائج في تقرير شامل ومنظم بالعربية.`,
  outputKey: "final_report",
});
 
// خط الإنتاج الكامل: بحث متوازي → دمج
const advancedPipeline = new SequentialAgent({
  name: "AdvancedPipeline",
  subAgents: [parallelResearch, synthesizer],
});

const agent = new Agent({
  name: "PreciseAgent",
  model: "gemini-2.5-flash",
  instruction: "أنت مساعد دقيق ومختصر.",
  generateContentConfig: {
    temperature: 0.3, // إجابات أكثر دقة (0 = حتمي، 1 = إبداعي)
    maxOutputTokens: 2048, // الحد الأقصى لطول الإجابة
    topP: 0.8, // التنوع في اختيار الكلمات
    topK: 40, // عدد الخيارات المرشحة لكل كلمة
  },
});

const structuredAgent = new Agent({
  name: "StructuredAgent",
  model: "gemini-2.5-flash",
  instruction: "حلل البيانات وقدم النتائج بتنسيق JSON.",
  outputSchema: {
    type: "object",
    properties: {
      summary: { type: "string", description: "ملخص التحليل" },
      keyPoints: {
        type: "array",
        items: { type: "string" },
        description: "النقاط الرئيسية",
      },
      confidence: {
        type: "number",
        description: "مستوى الثقة من 0 إلى 1",
      },
    },
    required: ["summary", "keyPoints", "confidence"],
  },
});

const personalAgent = new Agent({
  name: "PersonalAssistant",
  model: "gemini-2.5-flash",
  instruction: `أنت مساعد شخصي لـ {user_name}.
    تفضيلات المستخدم: {user_preferences}
    سجل المحادثات السابقة: {conversation_history?}
 
    خاطب المستخدم باسمه وراعِ تفضيلاته.`,
});

import { Agent } from "@google/adk";
 
const technicalSupport = new Agent({
  name: "TechnicalSupport",
  model: "gemini-2.5-flash",
  description: "يتعامل مع المشاكل التقنية والأعطال",
  instruction: "أنت فني دعم تقني. ساعد المستخدم في حل مشاكله التقنية.",
});
 
const salesAgent = new Agent({
  name: "SalesAgent",
  model: "gemini-2.5-flash",
  description: "يتعامل مع استفسارات المبيعات والأسعار",
  instruction: "أنت ممثل مبيعات. أجب عن الأسعار والعروض والخدمات.",
});
 
const generalAgent = new Agent({
  name: "GeneralAgent",
  model: "gemini-2.5-flash",
  description: "يتعامل مع الاستفسارات العامة",
  instruction: "أنت مساعد عام. أجب على الأسئلة العامة.",
});
 
// الموجّه الرئيسي — يقرر تلقائياً أي وكيل يستخدم
const router = new Agent({
  name: "Router",
  model: "gemini-2.5-flash",
  instruction: `أنت موجّه ذكي. حلل طلب المستخدم ووجّهه:
    - مشاكل تقنية → TechnicalSupport
    - أسئلة عن الأسعار والخدمات → SalesAgent
    - أي شيء آخر → GeneralAgent`,
  subAgents: [technicalSupport, salesAgent, generalAgent],
});

import { Agent, SequentialAgent } from "@google/adk";
 
const dataCollector = new Agent({
  name: "DataCollector",
  model: "gemini-2.5-flash",
  instruction: "اجمع البيانات المطلوبة من المستخدم.",
  outputKey: "collected_data",
});
 
const validator = new Agent({
  name: "Validator",
  model: "gemini-2.5-flash",
  instruction: `تحقق من البيانات في {collected_data}:
    - هل جميع الحقول المطلوبة موجودة؟
    - هل البيانات بالتنسيق الصحيح؟
    - هل هناك تناقضات؟
    قدم تقرير التحقق.`,
  outputKey: "validation_report",
});
 
const processor = new Agent({
  name: "Processor",
  model: "gemini-2.5-flash",
  instruction: `بناءً على البيانات في {collected_data}
    وتقرير التحقق في {validation_report}:
    نفذ المعالجة المطلوبة وقدم النتيجة النهائية.`,
  outputKey: "final_output",
});
 
const pipeline = new SequentialAgent({
  name: "DataPipeline",
  subAgents: [dataCollector, validator, processor],
});

npx adk api_server --port 3000

FROM node:20-slim
 
WORKDIR /app
 
COPY package*.json ./
RUN npm ci --only=production
 
COPY . .
 
EXPOSE 8000
 
CMD ["npx", "adk", "api_server", "--host", "0.0.0.0"]

docker build -t my-adk-agent .
docker run -p 8000:8000 --env-file .env my-adk-agent

# بناء الصورة ودفعها إلى Container Registry
gcloud builds submit --tag gcr.io/PROJECT_ID/my-adk-agent
 
# نشر على Cloud Run
gcloud run deploy my-adk-agent \
  --image gcr.io/PROJECT_ID/my-adk-agent \
  --platform managed \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_GENAI_API_KEY=your_key

# تأكد من وجود ملف .env بالمفتاح الصحيح
echo $GOOGLE_GENAI_API_KEY
 
# أو مررها مباشرة
GOOGLE_GENAI_API_KEY=your_key npx adk run agent.ts

# تأكد من استخدام امتداد .js في الاستيرادات (حتى لملفات .ts)
# صحيح:
import { getWeather } from "./tools/weather.js";
# خطأ:
import { getWeather } from "./tools/weather";

// تأكد من استخدام Zod لتعريف مخطط المعاملات
import { z } from "zod";
 
// كل معامل يحتاج .describe() لمساعدة النموذج
parameters: z.object({
  query: z.string().describe("وصف واضح للمعامل"),
});

// حسّن التعليمات لتوضح متى يستخدم كل أداة
instruction: `
  استخدم أداة get_weather عندما يسأل المستخدم عن:
  - الطقس أو درجة الحرارة
  - حالة الجو في مدينة معينة
 
  لا تستخدمها للأسئلة العامة.
`;