بناء وكلاء ذكاء اصطناعي جاهزين للإنتاج باستخدام Mastra وTypeScript

npm create mastra@latest

cd support-agent
npm install

OPENAI_API_KEY=sk-...
# أو
ANTHROPIC_API_KEY=sk-ant-...

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { ticketTool, knowledgeBaseTool } from "../tools/ticket-tool";
 
export const supportAgent = new Agent({
  name: "SupportBot",
  instructions: `أنت وكيل دعم عملاء متعاون لمنصة نقطة.
 
  مسؤولياتك:
  - الإجابة على أسئلة المنصة باستخدام أداة قاعدة المعرفة
  - إنشاء تذاكر دعم للمشكلات غير المحلولة
  - الحرص على أن تكون إجاباتك متعاطفة وموجزة ومركّزة على الحل
  - التصعيد إلى إنسان في حال كانت المشكلة حرجة أو تقنية`,
  model: openai("gpt-4o"),
  tools: {
    ticketTool,
    knowledgeBaseTool,
  },
});

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
// أداة للبحث في قاعدة المعرفة
export const knowledgeBaseTool = createTool({
  id: "search-knowledge-base",
  description: "ابحث في الأسئلة الشائعة والوثائق للإجابة على أسئلة المستخدم",
  inputSchema: z.object({
    query: z.string().describe("سؤال المستخدم للبحث عنه"),
    limit: z.number().optional().default(3).describe("عدد النتائج المطلوبة"),
  }),
  outputSchema: z.object({
    results: z.array(
      z.object({
        title: z.string(),
        content: z.string(),
        relevance: z.number(),
      })
    ),
  }),
  execute: async ({ context }) => {
    const { query, limit } = context;
    const results = await searchVectorDB(query, limit);
    return { results };
  },
});
 
// أداة لإنشاء تذكرة دعم
export const ticketTool = createTool({
  id: "create-ticket",
  description: "أنشئ تذكرة دعم عند عدم إمكانية حل المشكلة فوراً",
  inputSchema: z.object({
    title: z.string().describe("ملخص قصير للمشكلة"),
    description: z.string().describe("وصف تفصيلي للمشكلة"),
    priority: z.enum(["low", "medium", "high", "critical"]).describe("مستوى أولوية المشكلة"),
    userEmail: z.string().email().describe("عنوان بريد العميل"),
  }),
  outputSchema: z.object({
    ticketId: z.string(),
    status: z.string(),
    estimatedResolution: z.string(),
  }),
  execute: async ({ context }) => {
    const { title, description, priority, userEmail } = context;
    const ticket = await createSupportTicket({ title, description, priority, userEmail });
    return {
      ticketId: ticket.id,
      status: "created",
      estimatedResolution: priority === "critical" ? "ساعتان" : "24 ساعة",
    };
  },
});
 
async function searchVectorDB(query: string, limit: number) {
  return [{ title: "الأسئلة الشائعة", content: "إجابة نموذجية لـ: " + query, relevance: 0.9 }];
}
 
async function createSupportTicket(data: object) {
  return { id: "TKT-" + Math.random().toString(36).substr(2, 8).toUpperCase() };
}

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { LibSQLStore } from "@mastra/memory/storage/libsql";
import { openai } from "@ai-sdk/openai";
 
const memory = new Memory({
  storage: new LibSQLStore({
    url: "file:./support-memory.db",
    // للإنتاج: url: process.env.DATABASE_URL
  }),
  options: {
    lastMessages: 20,
    semanticRecall: {
      topK: 5,
      messageRange: 2,
    },
  },
});
 
export const supportAgent = new Agent({
  name: "SupportBot",
  instructions: "...",
  model: openai("gpt-4o"),
  memory,
  tools: { ticketTool, knowledgeBaseTool },
});

const response = await supportAgent.generate(
  "فشلت عملية الدفع لكن تم خصم المبلغ من حسابي",
  {
    resourceId: "user-123",   // يُعرِّف المستخدم
    threadId: "session-456",  // يُعرِّف جلسة المحادثة
  }
);
 
console.log(response.text);

import { createWorkflow, createStep } from "@mastra/core/workflows";
import { z } from "zod";
 
// الخطوة 1: تحليل التذكرة
const analyzeTicketStep = createStep({
  id: "analyze-ticket",
  description: "تصنيف أولوية التذكرة وفئتها",
  inputSchema: z.object({
    userMessage: z.string(),
    userEmail: z.string().email(),
  }),
  outputSchema: z.object({
    priority: z.enum(["low", "medium", "high", "critical"]),
    category: z.string(),
    needsEscalation: z.boolean(),
  }),
  execute: async ({ inputData }) => {
    const classification = await classifyWithLLM(inputData.userMessage);
    return classification;
  },
});
 
// الخطوة 2: توجيه التذكرة
const routeTicketStep = createStep({
  id: "route-ticket",
  description: "توجيه التذكرة إلى الفريق المناسب",
  inputSchema: z.object({
    priority: z.enum(["low", "medium", "high", "critical"]),
    category: z.string(),
    needsEscalation: z.boolean(),
  }),
  outputSchema: z.object({
    assignedTeam: z.string(),
    ticketId: z.string(),
  }),
  execute: async ({ inputData }) => {
    const team = inputData.needsEscalation
      ? "tier-2-engineering"
      : "tier-1-support";
    const ticketId = await assignToTeam(team, inputData);
    return { assignedTeam: team, ticketId };
  },
});
 
// الخطوة 3: إشعار المستخدم
const notifyUserStep = createStep({
  id: "notify-user",
  description: "إرسال بريد تأكيد للمستخدم",
  inputSchema: z.object({
    assignedTeam: z.string(),
    ticketId: z.string(),
  }),
  outputSchema: z.object({
    notificationSent: z.boolean(),
  }),
  execute: async ({ inputData }) => {
    await sendConfirmationEmail(inputData.ticketId, inputData.assignedTeam);
    return { notificationSent: true };
  },
});
 
// تجميع سير العمل
export const escalationWorkflow = createWorkflow({
  name: "ticket-escalation",
  triggerSchema: z.object({
    userMessage: z.string(),
    userEmail: z.string().email(),
  }),
})
  .then(analyzeTicketStep)
  .then(routeTicketStep)
  .then(notifyUserStep)
  .commit();
 
async function classifyWithLLM(message: string) {
  return { priority: "high" as const, category: "billing", needsEscalation: true };
}
async function assignToTeam(team: string, data: object) {
  return "TKT-" + Date.now();
}
async function sendConfirmationEmail(ticketId: string, team: string) {
  console.log(`تم إرسال البريد لـ ${ticketId} إلى ${team}`);
}

import { Mastra } from "@mastra/core";
import { supportAgent } from "./agents/support-agent";
import { escalationWorkflow } from "./workflows/escalation-workflow";
 
export const mastra = new Mastra({
  agents: { supportAgent },
  workflows: { escalationWorkflow },
  logger: {
    type: "CONSOLE",
    level: "INFO",
  },
});

npm run dev

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 4111
CMD ["npm", "start"]

npm install @mastra/vercel-functions
npx vercel deploy

fly launch --name support-agent
fly deploy

# Fly.io
fly secrets set OPENAI_API_KEY=sk-...
 
# Vercel
vercel env add OPENAI_API_KEY

import { createTestRun } from "@mastra/testing";
import { mastra } from "./src/mastra";
 
const testRun = createTestRun({ mastra });
 
test("ينشئ الوكيل تذكرة لمشكلات الفوترة", async () => {
  const result = await testRun.agent("supportAgent").generate(
    "تم خصم مبلغ الاشتراك مرتين من حسابي",
    { resourceId: "test-user", threadId: "test-thread" }
  );
 
  expect(result.toolCalls).toContainEqual(
    expect.objectContaining({ toolName: "create-ticket" })
  );
  expect(result.text).toContain("ticket");
});