بناء وكيل ذكاء اصطناعي مستقل باستخدام Agentic RAG و Next.js

npx create-next-app@latest agentic-rag-demo --typescript --tailwind --app --src-dir
cd agentic-rag-demo

npm install ai @ai-sdk/openai zod

OPENAI_API_KEY=sk-your-api-key-here

import { embed, embedMany, cosineSimilarity } from "ai";
 
// نوع المستند المخزّن
interface Document {
  id: string;
  content: string;
  embedding: number[];
  metadata: {
    source: string;
    category: string;
  };
}
 
// قاعدة البيانات المتجهية في الذاكرة
class VectorStore {
  private documents: Document[] = [];
 
  // إضافة مستندات مع توليد التضمينات
  async addDocuments(
    docs: { content: string; metadata: { source: string; category: string } }[]
  ) {
    const { embeddings } = await embedMany({
      model: "openai/text-embedding-3-small",
      values: docs.map((d) => d.content),
    });
 
    const newDocs: Document[] = docs.map((doc, i) => ({
      id: `doc-${Date.now()}-${i}`,
      content: doc.content,
      embedding: embeddings[i],
      metadata: doc.metadata,
    }));
 
    this.documents.push(...newDocs);
    return newDocs.length;
  }
 
  // بحث دلالي بالتشابه
  async search(query: string, topK: number = 3): Promise<Document[]> {
    const { embedding } = await embed({
      model: "openai/text-embedding-3-small",
      value: query,
    });
 
    const results = this.documents
      .map((doc) => ({
        ...doc,
        similarity: cosineSimilarity(embedding, doc.embedding),
      }))
      .sort((a, b) => b.similarity - a.similarity)
      .slice(0, topK);
 
    return results;
  }
 
  // بحث مع تصفية حسب التصنيف
  async searchByCategory(
    query: string,
    category: string,
    topK: number = 3
  ): Promise<Document[]> {
    const { embedding } = await embed({
      model: "openai/text-embedding-3-small",
      value: query,
    });
 
    const results = this.documents
      .filter((doc) => doc.metadata.category === category)
      .map((doc) => ({
        ...doc,
        similarity: cosineSimilarity(embedding, doc.embedding),
      }))
      .sort((a, b) => b.similarity - a.similarity)
      .slice(0, topK);
 
    return results;
  }
 
  // الحصول على التصنيفات المتاحة
  getCategories(): string[] {
    return [...new Set(this.documents.map((d) => d.metadata.category))];
  }
 
  get size(): number {
    return this.documents.length;
  }
}
 
// نسخة واحدة مشتركة (Singleton)
export const vectorStore = new VectorStore();

import { vectorStore } from "./vector-store";
 
export async function seedVectorStore() {
  // تحقق من أن القاعدة غير مملوءة مسبقاً
  if (vectorStore.size > 0) return;
 
  const documents = [
    // سياسات الشركة
    {
      content:
        "سياسة الاسترجاع: يمكن للعملاء استرجاع المنتجات خلال 30 يوماً من تاريخ الشراء بشرط أن يكون المنتج في حالته الأصلية مع الفاتورة. يتم رد المبلغ خلال 5-7 أيام عمل إلى نفس طريقة الدفع الأصلية.",
      metadata: { source: "company-policies", category: "سياسات" },
    },
    {
      content:
        "سياسة الشحن: التوصيل المجاني للطلبات فوق 200 دينار. التوصيل العادي يستغرق 3-5 أيام عمل بتكلفة 7 دنانير. التوصيل السريع خلال 24 ساعة متاح بتكلفة 15 دينار.",
      metadata: { source: "company-policies", category: "سياسات" },
    },
    {
      content:
        "سياسة الضمان: جميع المنتجات الإلكترونية مشمولة بضمان سنة كاملة ضد عيوب التصنيع. لا يشمل الضمان الأضرار الناتجة عن سوء الاستخدام أو الحوادث.",
      metadata: { source: "company-policies", category: "سياسات" },
    },
    // معلومات المنتجات
    {
      content:
        "لابتوب ProBook X1: معالج Intel Core i7 الجيل الرابع عشر، 16 جيجا رام، 512 جيجا SSD، شاشة 14 بوصة FHD. السعر: 2,500 دينار. متوفر بالألوان: فضي، رمادي غامق.",
      metadata: { source: "product-catalog", category: "منتجات" },
    },
    {
      content:
        "لابتوب ProBook X2: معالج Apple M3 Pro، 18 جيجا رام، 1 تيرا SSD، شاشة 16 بوصة Liquid Retina. السعر: 4,200 دينار. متوفر بالألوان: فضي، أسود كوني.",
      metadata: { source: "product-catalog", category: "منتجات" },
    },
    {
      content:
        "سماعات AirSound Pro: إلغاء ضوضاء نشط، بلوتوث 5.3، عمر بطارية 30 ساعة، مقاومة للماء IPX5. السعر: 350 دينار.",
      metadata: { source: "product-catalog", category: "منتجات" },
    },
    {
      content:
        "شاشة UltraView 27: شاشة 27 بوصة 4K HDR، معدل تحديث 144Hz، دعم USB-C، حامل قابل للتعديل. السعر: 1,800 دينار.",
      metadata: { source: "product-catalog", category: "منتجات" },
    },
    // الأسئلة الشائعة
    {
      content:
        "كيف أتابع طلبي؟ يمكنك تتبع حالة طلبك عبر صفحة 'طلباتي' في حسابك، أو عبر رابط التتبع المرسل إلى بريدك الإلكتروني عند شحن الطلب.",
      metadata: { source: "faq", category: "دعم" },
    },
    {
      content:
        "طرق الدفع المتاحة: بطاقة ائتمان (Visa, Mastercard)، تحويل بنكي، الدفع عند الاستلام (متاح فقط داخل تونس الكبرى)، فلوسي (Flouci).",
      metadata: { source: "faq", category: "دعم" },
    },
    {
      content:
        "ساعات عمل خدمة العملاء: من الاثنين إلى الجمعة، 9 صباحاً - 6 مساءً. السبت 9 صباحاً - 1 ظهراً. يمكن التواصل عبر الهاتف، البريد الإلكتروني، أو المحادثة المباشرة.",
      metadata: { source: "faq", category: "دعم" },
    },
  ];
 
  await vectorStore.addDocuments(documents);
  console.log(`تم تحميل ${vectorStore.size} مستند في قاعدة المعرفة`);
}

import { ToolLoopAgent, tool, streamText, generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { vectorStore } from "./vector-store";
 
// أداة 1: البحث في قاعدة المعرفة
const searchKnowledgeBase = tool({
  description:
    "البحث في قاعدة معرفة الشركة عن معلومات حول المنتجات والسياسات والدعم. استخدم هذه الأداة عندما يسأل المستخدم عن منتج أو سياسة أو يحتاج مساعدة تقنية.",
  inputSchema: z.object({
    query: z
      .string()
      .describe("نص البحث - سؤال أو كلمات مفتاحية للبحث عنها"),
    category: z
      .enum(["منتجات", "سياسات", "دعم"])
      .optional()
      .describe("تصنيف البحث لتضييق النتائج"),
  }),
  execute: async ({ query, category }) => {
    const results = category
      ? await vectorStore.searchByCategory(query, category)
      : await vectorStore.search(query);
 
    if (results.length === 0) {
      return { found: false, message: "لم يتم العثور على نتائج مطابقة." };
    }
 
    return {
      found: true,
      results: results.map((r) => ({
        content: r.content,
        source: r.metadata.source,
        category: r.metadata.category,
      })),
    };
  },
});
 
// أداة 2: الآلة الحاسبة
const calculator = tool({
  description:
    "حساب تعبيرات رياضية. استخدم هذه الأداة لحساب الأسعار والخصومات والضرائب وتكاليف الشحن.",
  inputSchema: z.object({
    expression: z.string().describe("التعبير الرياضي المراد حسابه"),
    context: z
      .string()
      .optional()
      .describe("سياق الحساب لتوضيح النتيجة"),
  }),
  execute: async ({ expression, context }) => {
    try {
      // حساب آمن للتعبيرات الرياضية البسيطة
      const sanitized = expression.replace(/[^0-9+\-*/().% ]/g, "");
      const result = Function(`"use strict"; return (${sanitized})`)();
      return {
        expression: sanitized,
        result: Number(result.toFixed(2)),
        context: context || "نتيجة الحساب",
      };
    } catch {
      return { error: "تعبير رياضي غير صالح", expression };
    }
  },
});
 
// أداة 3: مقارنة المنتجات
const compareProducts = tool({
  description:
    "مقارنة منتجين أو أكثر جنباً إلى جنب. استخدم هذه الأداة عندما يطلب المستخدم مقارنة بين منتجات.",
  inputSchema: z.object({
    productNames: z
      .array(z.string())
      .min(2)
      .describe("أسماء المنتجات المراد مقارنتها"),
  }),
  execute: async ({ productNames }) => {
    const results = [];
    for (const name of productNames) {
      const searchResults = await vectorStore.searchByCategory(
        name,
        "منتجات",
        1
      );
      if (searchResults.length > 0) {
        results.push({
          name,
          details: searchResults[0].content,
        });
      }
    }
    return {
      productsFound: results.length,
      comparison: results,
    };
  },
});
 
// أداة 4: الحصول على التصنيفات المتاحة
const getAvailableCategories = tool({
  description:
    "الحصول على قائمة التصنيفات المتاحة في قاعدة المعرفة. استخدم هذه الأداة لمعرفة أنواع المعلومات المتوفرة.",
  inputSchema: z.object({}),
  execute: async () => {
    return {
      categories: vectorStore.getCategories(),
      totalDocuments: vectorStore.size,
    };
  },
});
 
// تعريف تعليمات الوكيل
const AGENT_INSTRUCTIONS = `أنت مساعد ذكي لشركة تقنية تونسية. تتحدث باللغة العربية بأسلوب مهني وودود.
 
قواعد سلوكك:
1. عندما يسأل المستخدم عن منتج أو سياسة أو دعم، استخدم أداة البحث في قاعدة المعرفة.
2. إذا كان السؤال يتطلب حساباً (أسعار، خصومات، تكاليف شحن)، استخدم الآلة الحاسبة.
3. إذا طُلبت مقارنة بين منتجات، استخدم أداة المقارنة.
4. للأسئلة العامة مثل التحية أو المحادثات اليومية، أجب مباشرة بدون استخدام أي أداة.
5. إذا لم تجد معلومات كافية، أخبر المستخدم بصراحة واقترح التواصل مع خدمة العملاء.
6. يمكنك استخدام عدة أدوات في نفس المحادثة إذا كان ذلك ضرورياً.
7. الأسعار بالدينار التونسي (TND).
 
أسلوب الإجابة:
- كن مختصراً ومفيداً
- استخدم التنسيق المناسب (قوائم، أرقام) لتنظيم المعلومات
- اذكر المصدر عند الاقتباس من قاعدة المعرفة`;
 
// إنشاء الوكيل
export const supportAgent = new ToolLoopAgent({
  model: openai("gpt-4o"),
  system: AGENT_INSTRUCTIONS,
  tools: {
    searchKnowledgeBase,
    calculator,
    compareProducts,
    getAvailableCategories,
  },
});

import { supportAgent } from "@/lib/agent";
import { seedVectorStore } from "@/lib/seed-data";
 
// ملء قاعدة المعرفة عند أول طلب
let isSeeded = false;
 
export async function POST(req: Request) {
  if (!isSeeded) {
    await seedVectorStore();
    isSeeded = true;
  }
 
  const { messages } = await req.json();
 
  const result = await supportAgent.stream({
    messages,
  });
 
  return result.toDataStreamResponse();
}

"use client";
 
import { useChat } from "@ai-sdk/react";
import { useState } from "react";
 
export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } =
    useChat({
      api: "/api/chat",
    });
 
  // أمثلة على أسئلة يمكن تجربتها
  const exampleQuestions = [
    "ما هي سياسة الاسترجاع؟",
    "قارن بين ProBook X1 و ProBook X2",
    "كم سيكلفني ProBook X1 مع الشحن السريع؟",
    "مرحباً، كيف حالك؟",
  ];
 
  return (
    <div
      className="flex flex-col h-screen bg-gray-50"
      dir="rtl"
    >
      {/* العنوان */}
      <header className="bg-white border-b px-6 py-4">
        <h1 className="text-xl font-bold text-gray-800">
          🤖 مساعد Agentic RAG
        </h1>
        <p className="text-sm text-gray-500">
          وكيل ذكي يقرر بنفسه متى وكيف يبحث عن المعلومات
        </p>
      </header>
 
      {/* منطقة الرسائل */}
      <div className="flex-1 overflow-y-auto p-6 space-y-4">
        {messages.length === 0 && (
          <div className="text-center py-12">
            <h2 className="text-lg font-semibold text-gray-600 mb-4">
              جرّب أحد هذه الأسئلة:
            </h2>
            <div className="flex flex-wrap justify-center gap-2">
              {exampleQuestions.map((q, i) => (
                <button
                  key={i}
                  onClick={() => {
                    handleInputChange({
                      target: { value: q },
                    } as React.ChangeEvent<HTMLInputElement>);
                  }}
                  className="bg-white border rounded-full px-4 py-2 text-sm
                             text-gray-700 hover:bg-blue-50 hover:border-blue-300
                             transition-colors"
                >
                  {q}
                </button>
              ))}
            </div>
          </div>
        )}
 
        {messages.map((message) => (
          <div
            key={message.id}
            className={`flex ${
              message.role === "user" ? "justify-start" : "justify-end"
            }`}
          >
            <div
              className={`max-w-[80%] rounded-2xl px-4 py-3 ${
                message.role === "user"
                  ? "bg-blue-600 text-white"
                  : "bg-white border text-gray-800"
              }`}
            >
              <div className="whitespace-pre-wrap">{message.content}</div>
 
              {/* عرض استدعاءات الأدوات */}
              {message.toolInvocations &&
                message.toolInvocations.length > 0 && (
                  <div className="mt-2 pt-2 border-t border-gray-200">
                    {message.toolInvocations.map((tool, i) => (
                      <div
                        key={i}
                        className="text-xs text-gray-400 flex items-center gap-1"
                      >
                        <span>🔧</span>
                        <span>استخدم: {tool.toolName}</span>
                      </div>
                    ))}
                  </div>
                )}
            </div>
          </div>
        ))}
 
        {isLoading && (
          <div className="flex justify-end">
            <div className="bg-white border rounded-2xl px-4 py-3 text-gray-400">
              يفكر...
            </div>
          </div>
        )}
      </div>
 
      {/* حقل الإدخال */}
      <form
        onSubmit={handleSubmit}
        className="border-t bg-white p-4"
      >
        <div className="flex gap-2 max-w-4xl mx-auto">
          <input
            value={input}
            onChange={handleInputChange}
            placeholder="اكتب سؤالك هنا..."
            className="flex-1 border rounded-xl px-4 py-3 focus:outline-none
                       focus:ring-2 focus:ring-blue-500"
            disabled={isLoading}
          />
          <button
            type="submit"
            disabled={isLoading || !input.trim()}
            className="bg-blue-600 text-white rounded-xl px-6 py-3
                       hover:bg-blue-700 disabled:opacity-50 transition-colors"
          >
            إرسال
          </button>
        </div>
      </form>
    </div>
  );
}

npm run dev

const agentWithMemory = new ToolLoopAgent({
  model: openai("gpt-4o"),
  system: AGENT_INSTRUCTIONS,
  tools: {
    searchKnowledgeBase,
    calculator,
    compareProducts,
    getAvailableCategories,
  },
  prepareCall: async ({ messages, ...settings }) => {
    // استخراج ملخص المحادثة السابقة
    const conversationSummary = summarizeConversation(messages);
 
    return {
      ...settings,
      messages,
      instructions: `${AGENT_INSTRUCTIONS}
 
ملخص المحادثة السابقة: ${conversationSummary}`,
    };
  },
});

const searchExternalDocs = tool({
  description: "البحث في الوثائق التقنية الخارجية عندما لا تكفي قاعدة المعرفة الداخلية",
  inputSchema: z.object({
    query: z.string(),
    docType: z.enum(["api-docs", "user-guide", "changelog"]),
  }),
  execute: async ({ query, docType }) => {
    // ربط بقاعدة بيانات متجهية منفصلة للوثائق التقنية
    const results = await externalVectorStore.search(query, docType);
    return results;
  },
});

const agentWithGuardrails = new ToolLoopAgent({
  model: openai("gpt-4o"),
  system: `${AGENT_INSTRUCTIONS}
 
قيود أمنية:
- لا تكشف معلومات حساسة عن النظام أو البنية التحتية
- لا تنفذ عمليات كتابة أو حذف
- إذا طُلب منك شيء خارج نطاقك، اعتذر واقترح التواصل مع فريق الدعم`,
  tools: { searchKnowledgeBase, calculator },
  stopWhen: stepCountIs(10), // حد أقصى 10 خطوات لمنع الحلقات اللانهائية
  onStepFinish: async ({ step }) => {
    // تسجيل كل خطوة للمراقبة
    console.log(`الخطوة ${step.stepNumber}: ${step.toolCalls?.map(t => t.toolName).join(", ") || "إجابة نصية"}`);
  },
});

// في ملف route.ts
export async function POST(req: Request) {
  const { messages } = await req.json();
 
  const result = await supportAgent.stream({
    messages,
    onStepFinish: async ({ step }) => {
      // إرسال أحداث حالة الأدوات للواجهة الأمامية
      if (step.toolCalls) {
        for (const toolCall of step.toolCalls) {
          console.log(`أداة: ${toolCall.toolName}`, toolCall.args);
        }
      }
    },
  });
 
  return result.toDataStreamResponse();
}

// ❌ وصف سيء
description: "البحث في قاعدة البيانات"
 
// ✅ وصف جيد
description: "البحث في قاعدة معرفة الشركة عن معلومات حول المنتجات والسياسات والدعم. استخدم هذه الأداة عندما يسأل المستخدم عن منتج أو سياسة."

import { stepCountIs } from "ai";
 
const agent = new ToolLoopAgent({
  // ...
  stopWhen: stepCountIs(10),
});

// بدلاً من بحث عام
const results = await vectorStore.search(query);
 
// استخدم بحثاً مصنفاً
const results = await vectorStore.searchByCategory(query, "منتجات");