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

mkdir ai-agent-langgraph && cd ai-agent-langgraph
npm init -y
npm install @langchain/langgraph @langchain/openai @langchain/core zod
npm install -D typescript tsx @types/node

npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true
  },
  "include": ["src/**/*"]
}

OPENAI_API_KEY=sk-your-key-here

import { Annotation, MessagesAnnotation } from "@langchain/langgraph";
 
// تعريف مخطط الحالة للوكيل
export const AgentState = Annotation.Root({
  // الرسائل تتراكم خلال المحادثة
  ...MessagesAnnotation.spec,
 
  // تتبع عدد استدعاءات الأدوات (للتصحيح)
  toolCallCount: Annotation<number>({
    reducer: (current, update) => (update ?? current ?? 0),
    default: () => 0,
  }),
 
  // الإجابة النهائية من الوكيل
  finalAnswer: Annotation<string>({
    reducer: (current, update) => update ?? current ?? "",
    default: () => "",
  }),
});
 
export type AgentStateType = typeof AgentState.State;

import { tool } from "@langchain/core/tools";
import { z } from "zod";
 
// الأداة 1: آلة حاسبة
export const calculatorTool = tool(
  async ({ expression }) => {
    try {
      const sanitized = expression.replace(/[^0-9+\-*/().%\s]/g, "");
      if (!sanitized || sanitized !== expression.trim()) {
        return "خطأ: تعبير غير صالح. يُسمح فقط بالأرقام والعمليات الأساسية (+, -, *, /, %).";
      }
      const result = new Function(`return (${sanitized})`)();
      return `النتيجة: ${result}`;
    } catch (error) {
      return `خطأ في الحساب: ${(error as Error).message}`;
    }
  },
  {
    name: "calculator",
    description:
      "ينفذ عمليات حسابية. المدخل يجب أن يكون تعبيراً رياضياً مثل '2 + 2' أو '(10 * 5) / 3'.",
    schema: z.object({
      expression: z
        .string()
        .describe("التعبير الرياضي المراد حسابه"),
    }),
  }
);
 
// الأداة 2: بحث الويب (محاكاة لأغراض الدرس)
export const webSearchTool = tool(
  async ({ query }) => {
    console.log(`[أداة] البحث في الويب عن: "${query}"`);
 
    const results = [
      {
        title: `أفضل نتيجة لـ: ${query}`,
        snippet: `معلومات شاملة حول ${query}. يغطي أحدث التطورات والحقائق الرئيسية حتى 2026.`,
        url: `https://example.com/search?q=${encodeURIComponent(query)}`,
      },
    ];
 
    return JSON.stringify(results, null, 2);
  },
  {
    name: "web_search",
    description:
      "يبحث في الويب عن معلومات حديثة. استخدمه عندما تحتاج حقائق أو أخبار أو بيانات محدثة.",
    schema: z.object({
      query: z.string().describe("استعلام البحث"),
    }),
  }
);
 
// الأداة 3: التاريخ والوقت
export const dateTimeTool = tool(
  async ({ timezone }) => {
    const now = new Date();
    const formatter = new Intl.DateTimeFormat("ar-SA", {
      timeZone: timezone || "UTC",
      dateStyle: "full",
      timeStyle: "long",
    });
    return formatter.format(now);
  },
  {
    name: "get_current_datetime",
    description:
      "يحصل على التاريخ والوقت الحالي. يمكن تحديد المنطقة الزمنية مثل 'Asia/Riyadh' أو 'Africa/Tunis'.",
    schema: z.object({
      timezone: z
        .string()
        .optional()
        .describe("اسم المنطقة الزمنية IANA (الافتراضي: UTC)"),
    }),
  }
);
 
export const allTools = [calculatorTool, webSearchTool, dateTimeTool];

import { StateGraph, END, START } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import {
  AIMessage,
  HumanMessage,
  SystemMessage,
} from "@langchain/core/messages";
import { AgentState } from "./state.js";
import { allTools } from "./tools.js";
 
// تهيئة النموذج اللغوي مع ربط الأدوات
const llm = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0,
}).bindTools(allTools);
 
// التوجيه النظامي الذي يحدد سلوك الوكيل
const SYSTEM_PROMPT = `أنت مساعد ذكي لديك وصول لأدوات.
 
قدراتك:
- calculator: لأي عمليات حسابية
- web_search: للبحث عن معلومات حديثة
- get_current_datetime: للحصول على التاريخ والوقت
 
إرشادات:
- استخدم الأدوات عندما تحتاج بيانات واقعية أو حسابات
- فكّر خطوة بخطوة للأسئلة المعقدة
- إذا أرجعت أداة خطأ، اشرحه للمستخدم
- كن موجزاً لكن شاملاً في إجاباتك النهائية`;
 
// العقدة 1: استدعاء النموذج اللغوي
async function callModel(
  state: typeof AgentState.State
): Promise<Partial<typeof AgentState.State>> {
  const messages = [new SystemMessage(SYSTEM_PROMPT), ...state.messages];
  const response = await llm.invoke(messages);
  return { messages: [response] };
}
 
// العقدة 2: تنفيذ الأدوات
const toolNode = new ToolNode(allTools);
 
// حافة شرطية: هل نواصل للأدوات أم ننتهي؟
function shouldContinue(
  state: typeof AgentState.State
): "tools" | typeof END {
  const lastMessage = state.messages[state.messages.length - 1];
 
  if (
    lastMessage instanceof AIMessage &&
    lastMessage.tool_calls &&
    lastMessage.tool_calls.length > 0
  ) {
    return "tools";
  }
 
  return END;
}
 
// بناء الرسم البياني
export function createAgentGraph() {
  const graph = new StateGraph(AgentState)
    .addNode("agent", callModel)
    .addNode("tools", toolNode)
    .addEdge(START, "agent")
    .addConditionalEdges("agent", shouldContinue, {
      tools: "tools",
      [END]: END,
    })
    .addEdge("tools", "agent");
 
  return graph.compile();
}

import "dotenv/config";
import { HumanMessage } from "@langchain/core/messages";
import { createAgentGraph } from "./agent.js";
 
async function main() {
  const agent = createAgentGraph();
 
  console.log("🤖 الوكيل جاهز. لنختبر بعض الاستعلامات.\n");
 
  // اختبار 1: عملية حسابية
  console.log("--- اختبار 1: رياضيات ---");
  const result1 = await agent.invoke({
    messages: [
      new HumanMessage(
        "ما هو 15% من 2,340؟ وأضف 99 للنتيجة."
      ),
    ],
  });
  const lastMsg1 = result1.messages[result1.messages.length - 1];
  console.log("الإجابة:", lastMsg1.content, "\n");
 
  // اختبار 2: بحث في الويب
  console.log("--- اختبار 2: بحث ---");
  const result2 = await agent.invoke({
    messages: [
      new HumanMessage(
        "ابحث عن أحدث اتجاهات تطوير TypeScript في 2026"
      ),
    ],
  });
  const lastMsg2 = result2.messages[result2.messages.length - 1];
  console.log("الإجابة:", lastMsg2.content, "\n");
 
  // اختبار 3: استخدام أدوات متعددة
  console.log("--- اختبار 3: أدوات متعددة ---");
  const result3 = await agent.invoke({
    messages: [
      new HumanMessage(
        "كم الساعة الآن في طوكيو؟ واحسب كم ساعة متبقية حتى منتصف الليل هناك."
      ),
    ],
  });
  const lastMsg3 = result3.messages[result3.messages.length - 1];
  console.log("الإجابة:", lastMsg3.content, "\n");
}
 
main().catch(console.error);

npx tsx src/index.ts

import "dotenv/config";
import { StateGraph, END, START, MemorySaver } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import {
  AIMessage,
  HumanMessage,
  SystemMessage,
} from "@langchain/core/messages";
import { AgentState } from "./state.js";
import { allTools } from "./tools.js";
 
const memory = new MemorySaver();
 
const llm = new ChatOpenAI({ model: "gpt-4o", temperature: 0 }).bindTools(
  allTools
);
 
const SYSTEM_PROMPT = `أنت مساعد ذكي مع ذاكرة.
تتذكر الرسائل السابقة في المحادثة.
استخدم الأدوات عند الحاجة: calculator, web_search, get_current_datetime.`;
 
async function callModel(state: typeof AgentState.State) {
  const messages = [new SystemMessage(SYSTEM_PROMPT), ...state.messages];
  const response = await llm.invoke(messages);
  return { messages: [response] };
}
 
function shouldContinue(state: typeof AgentState.State) {
  const last = state.messages[state.messages.length - 1];
  if (
    last instanceof AIMessage &&
    last.tool_calls &&
    last.tool_calls.length > 0
  ) {
    return "tools";
  }
  return END;
}
 
const agentWithMemory = new StateGraph(AgentState)
  .addNode("agent", callModel)
  .addNode("tools", new ToolNode(allTools))
  .addEdge(START, "agent")
  .addConditionalEdges("agent", shouldContinue, {
    tools: "tools",
    [END]: END,
  })
  .addEdge("tools", "agent")
  .compile({ checkpointer: memory }); // ← الذاكرة مفعّلة!
 
async function main() {
  // إعدادات مع معرّف المحادثة
  const config = { configurable: { thread_id: "user-123" } };
 
  // الجولة 1
  console.log("👤 المستخدم: اسمي سارة وأعمل في شركة ناشئة.");
  const res1 = await agentWithMemory.invoke(
    {
      messages: [
        new HumanMessage("اسمي سارة وأعمل في شركة ناشئة."),
      ],
    },
    config
  );
  console.log(
    "🤖 الوكيل:",
    res1.messages[res1.messages.length - 1].content
  );
  console.log();
 
  // الجولة 2 — الوكيل يجب أن يتذكر الاسم
  console.log("👤 المستخدم: ما اسمي؟");
  const res2 = await agentWithMemory.invoke(
    { messages: [new HumanMessage("ما اسمي؟")] },
    config
  );
  console.log(
    "🤖 الوكيل:",
    res2.messages[res2.messages.length - 1].content
  );
  console.log();
 
  // الجولة 3 — خطوات متعددة مع سياق الذاكرة
  console.log("👤 المستخدم: احسب عدد حروف اسمي مضروباً في 100.");
  const res3 = await agentWithMemory.invoke(
    {
      messages: [
        new HumanMessage("احسب عدد حروف اسمي مضروباً في 100."),
      ],
    },
    config
  );
  console.log(
    "🤖 الوكيل:",
    res3.messages[res3.messages.length - 1].content
  );
}
 
main().catch(console.error);

npx tsx src/memory-agent.ts

import { AIMessage } from "@langchain/core/messages";
 
// غلاف إعادة المحاولة مع تراجع أسي
export function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  return new Promise(async (resolve, reject) => {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const result = await fn();
        return resolve(result);
      } catch (error) {
        console.warn(
          `المحاولة ${attempt}/${maxRetries} فشلت:`,
          (error as Error).message
        );
        if (attempt === maxRetries) {
          return reject(error);
        }
        await new Promise((r) =>
          setTimeout(r, Math.pow(2, attempt) * 1000)
        );
      }
    }
  });
}
 
// غلاف المهلة الزمنية
export async function invokeWithTimeout(
  agent: any,
  input: any,
  config: any,
  timeoutMs = 30000
) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
 
  try {
    const result = await agent.invoke(input, {
      ...config,
      signal: controller.signal,
    });
    return result;
  } catch (error) {
    if ((error as Error).name === "AbortError") {
      throw new Error(
        `انتهت المهلة الزمنية للوكيل بعد ${timeoutMs}ms. الاستعلام قد يكون معقداً جداً.`
      );
    }
    throw error;
  } finally {
    clearTimeout(timeout);
  }
}
 
// تتبع استهلاك التوكنات
export function extractTokenUsage(result: any) {
  const messages = result.messages || [];
  let totalTokens = 0;
 
  for (const msg of messages) {
    if (msg instanceof AIMessage && msg.usage_metadata) {
      totalTokens +=
        (msg.usage_metadata.input_tokens || 0) +
        (msg.usage_metadata.output_tokens || 0);
    }
  }
 
  return totalTokens;
}

import "dotenv/config";
import { HumanMessage } from "@langchain/core/messages";
import { createAgentGraph } from "./agent.js";
 
async function streamAgent() {
  const agent = createAgentGraph();
 
  const input = {
    messages: [
      new HumanMessage(
        "اشرح الحوسبة الكمية بشكل مبسط، ثم احسب 2^64."
      ),
    ],
  };
 
  console.log("🤖 بث الاستجابة:\n");
 
  for await (const event of await agent.streamEvents(input, {
    version: "v2",
  })) {
    if (event.event === "on_chat_model_stream") {
      const chunk = event.data.chunk;
      if (chunk.content) {
        process.stdout.write(chunk.content);
      }
    }
 
    if (event.event === "on_tool_start") {
      console.log(`\n\n🔧 استدعاء أداة: ${event.name}`);
      console.log(`   المدخل: ${JSON.stringify(event.data.input)}`);
    }
 
    if (event.event === "on_tool_end") {
      console.log(`   النتيجة: ${event.data.output.content}\n`);
    }
  }
 
  console.log("\n\n✅ اكتمل البث.");
}
 
streamAgent().catch(console.error);

npx tsx src/stream.ts

npm install @langchain/anthropic

import { ChatAnthropic } from "@langchain/anthropic";
 
const llm = new ChatAnthropic({
  model: "claude-sonnet-4-20250514",
  temperature: 0,
}).bindTools(allTools);

npm install @langchain/google-genai

import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
 
const llm = new ChatGoogleGenerativeAI({
  model: "gemini-2.0-flash",
  temperature: 0,
}).bindTools(allTools);

npm install @langchain/ollama

import { ChatOllama } from "@langchain/ollama";
 
const llm = new ChatOllama({
  model: "llama3.3",
  temperature: 0,
}).bindTools(allTools);

import { RateLimiter } from "limiter";
 
const limiter = new RateLimiter({
  tokensPerInterval: 10,
  interval: "minute",
});
 
async function rateLimitedInvoke(agent: any, input: any) {
  await limiter.removeTokens(1);
  return agent.invoke(input);
}

npm install langsmith

LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langsmith-key
LANGCHAIN_PROJECT=my-ai-agent

import { interrupt } from "@langchain/langgraph";
 
async function sensitiveToolNode(state: typeof AgentState.State) {
  const lastMessage = state.messages[state.messages.length - 1];
 
  const approval = interrupt({
    action: "tool_call",
    description: "الوكيل يريد تنفيذ إجراء حساس",
    toolCalls: (lastMessage as any).tool_calls,
  });
 
  if (!approval.approved) {
    return {
      messages: [new HumanMessage("تم رفض الإجراء من المستخدم.")],
    };
  }
 
  const toolNode = new ToolNode(allTools);
  return toolNode.invoke(state);
}

const MAX_ITERATIONS = 10;
 
function shouldContinue(state: typeof AgentState.State) {
  const aiMessages = state.messages.filter(
    (m) => m instanceof AIMessage
  );
  if (aiMessages.length >= MAX_ITERATIONS) {
    console.warn("تم الوصول للحد الأقصى من التكرارات");
    return END;
  }
 
  const last = state.messages[state.messages.length - 1];
  if (last instanceof AIMessage && last.tool_calls?.length > 0) {
    return "tools";
  }
  return END;
}