إطار عمل Mastra للذكاء الاصطناعي: بناء وكلاء وسير عمل ذكية بـ TypeScript

npm create mastra@latest

cd research-assistant
npm install

OPENAI_API_KEY=sk-your-key-here

import { Mastra } from "@mastra/core";
import { researchAgent } from "./agents";
import { searchTool, summarizeTool } from "./tools";
import { researchWorkflow } from "./workflows";
 
export const mastra = new Mastra({
  agents: { researchAgent },
  workflows: { researchWorkflow },
});

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { searchTool, summarizeTool, reportTool } from "../tools";
 
export const researchAgent = new Agent({
  name: "Research Assistant",
  instructions: `You are a thorough research assistant. When given a topic:
    1. Search for relevant, up-to-date information
    2. Summarize key findings into concise points
    3. Generate a structured report with sections and citations
 
    Always verify information from multiple sources when possible.
    Be factual and cite your sources. If unsure, say so.`,
  model: openai("gpt-4o"),
  tools: {
    searchTool,
    summarizeTool,
    reportTool,
  },
});

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
// الأداة 1: البحث في الويب
export const searchTool = createTool({
  id: "web-search",
  description: "Search the web for information on a given query. Returns relevant results with titles, snippets, and URLs.",
  inputSchema: z.object({
    query: z.string().describe("The search query"),
    maxResults: z.number().default(5).describe("Maximum number of results to return"),
  }),
  execute: async ({ context }) => {
    const { query, maxResults } = context;
 
    // في الإنتاج، استخدم واجهة بحث حقيقية (Serper، Tavily، إلخ.)
    const response = await fetch(
      `https://api.tavily.com/search`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          api_key: process.env.TAVILY_API_KEY,
          query,
          max_results: maxResults,
        }),
      }
    );
 
    const data = await response.json();
 
    return {
      results: data.results.map((r: any) => ({
        title: r.title,
        url: r.url,
        snippet: r.content,
      })),
    };
  },
});
 
// الأداة 2: تلخيص النص
export const summarizeTool = createTool({
  id: "summarize-text",
  description: "Summarize a long piece of text into key bullet points.",
  inputSchema: z.object({
    text: z.string().describe("The text to summarize"),
    maxPoints: z.number().default(5).describe("Maximum number of bullet points"),
  }),
  execute: async ({ context }) => {
    const { text, maxPoints } = context;
 
    // تلخيص استخراجي بسيط — في الإنتاج، استخدم استدعاء نموذج لغة
    const sentences = text.split(". ").filter((s) => s.length > 20);
    const summary = sentences.slice(0, maxPoints).map((s) => s.trim());
 
    return { summary };
  },
});
 
// الأداة 3: توليد تقرير
export const reportTool = createTool({
  id: "generate-report",
  description: "Generate a structured markdown report from research findings.",
  inputSchema: z.object({
    title: z.string().describe("Report title"),
    sections: z.array(
      z.object({
        heading: z.string(),
        content: z.string(),
        sources: z.array(z.string()).optional(),
      })
    ).describe("Report sections with headings, content, and optional source URLs"),
  }),
  execute: async ({ context }) => {
    const { title, sections } = context;
 
    let markdown = `# ${title}\n\n`;
    markdown += `*Generated on ${new Date().toISOString().split("T")[0]}*\n\n`;
 
    for (const section of sections) {
      markdown += `## ${section.heading}\n\n`;
      markdown += `${section.content}\n\n`;
      if (section.sources?.length) {
        markdown += `**Sources:**\n`;
        for (const source of section.sources) {
          markdown += `- ${source}\n`;
        }
        markdown += "\n";
      }
    }
 
    return { report: markdown };
  },
});

import { Workflow, Step } from "@mastra/core/workflows";
import { z } from "zod";
import { researchAgent } from "../agents";
 
// الخطوة 1: البحث عن موضوع
const researchStep = new Step({
  id: "research",
  inputSchema: z.object({
    topic: z.string(),
    depth: z.enum(["shallow", "deep"]).default("deep"),
  }),
  execute: async ({ context }) => {
    const agent = researchAgent;
    const response = await agent.generate(
      `Research the following topic thoroughly: ${context.topic}.
       Depth level: ${context.depth}.
       Use the search tool to find current information.`
    );
    return { findings: response.text };
  },
});
 
// الخطوة 2: استخراج الرؤى الرئيسية
const analyzeStep = new Step({
  id: "analyze",
  inputSchema: z.object({
    findings: z.string(),
  }),
  execute: async ({ context }) => {
    const agent = researchAgent;
    const response = await agent.generate(
      `Analyze these research findings and extract 5-7 key insights:
       ${context.findings}
 
       Format as a JSON array of objects with "insight" and "confidence" fields.`
    );
    return { insights: response.text };
  },
});
 
// الخطوة 3: توليد التقرير النهائي
const reportStep = new Step({
  id: "report",
  inputSchema: z.object({
    topic: z.string(),
    insights: z.string(),
  }),
  execute: async ({ context }) => {
    const agent = researchAgent;
    const response = await agent.generate(
      `Create a comprehensive research report on "${context.topic}"
       using these insights: ${context.insights}.
       Use the report tool to generate a structured markdown document.`
    );
    return { report: response.text };
  },
});
 
// بناء رسم سير العمل
export const researchWorkflow = new Workflow({
  name: "research-pipeline",
  triggerSchema: z.object({
    topic: z.string().describe("The topic to research"),
    depth: z.enum(["shallow", "deep"]).default("deep"),
  }),
});
 
researchWorkflow
  .step(researchStep)
  .then(analyzeStep)
  .then(reportStep)
  .commit();

import { mastra } from "./mastra";
 
async function main() {
  // احصل على الوكيل
  const agent = mastra.getAgent("researchAgent");
 
  // توليد نص بسيط
  const response = await agent.generate(
    "What are the latest developments in quantum computing in 2026?"
  );
  console.log(response.text);
 
  // استجابة متدفقة
  const stream = await agent.stream(
    "Compare the top 3 TypeScript AI frameworks in 2026"
  );
  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk);
  }
}
 
main().catch(console.error);

npx tsx src/test.ts

import { mastra } from "./mastra";
 
async function runWorkflow() {
  const workflow = mastra.getWorkflow("researchWorkflow");
 
  const result = await workflow.execute({
    triggerData: {
      topic: "The state of WebAssembly in 2026",
      depth: "deep",
    },
  });
 
  // الوصول إلى نتائج كل خطوة
  console.log("Research:", result.results.research);
  console.log("Analysis:", result.results.analyze);
  console.log("Report:", result.results.report);
}
 
runWorkflow().catch(console.error);

npm install @mastra/rag @ai-sdk/openai

import { embed, embedMany } from "ai";
import { openai } from "@ai-sdk/openai";
import { PgVector } from "@mastra/rag";
 
// 1. تهيئة مخزن المتجهات
const vectorStore = new PgVector({
  connectionString: process.env.DATABASE_URL!,
});
 
// 2. إنشاء تضمينات من مستنداتك
const documents = [
  "Mastra is a TypeScript framework for building AI agents...",
  "Workflows in Mastra are directed acyclic graphs...",
  "Tools extend agent capabilities with custom functions...",
];
 
const { embeddings } = await embedMany({
  model: openai.embedding("text-embedding-3-small"),
  values: documents,
});
 
// 3. تخزين التضمينات في قاعدة بيانات المتجهات
await vectorStore.upsert({
  indexName: "docs",
  vectors: embeddings.map((embedding, i) => ({
    id: `doc-${i}`,
    values: embedding,
    metadata: { text: documents[i] },
  })),
});
 
// 4. الاستعلام عن المستندات المشابهة
const { embedding: queryEmbedding } = await embed({
  model: openai.embedding("text-embedding-3-small"),
  value: "How do Mastra workflows work?",
});
 
const results = await vectorStore.query({
  indexName: "docs",
  queryVector: queryEmbedding,
  topK: 3,
});

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { embed } from "ai";
import { openai } from "@ai-sdk/openai";
 
export const ragSearchTool = createTool({
  id: "search-knowledge-base",
  description: "Search the internal knowledge base for relevant information.",
  inputSchema: z.object({
    query: z.string().describe("What to search for in the knowledge base"),
  }),
  execute: async ({ context }) => {
    const { embedding } = await embed({
      model: openai.embedding("text-embedding-3-small"),
      value: context.query,
    });
 
    const results = await vectorStore.query({
      indexName: "docs",
      queryVector: embedding,
      topK: 5,
    });
 
    return {
      documents: results.map((r) => ({
        text: r.metadata?.text,
        score: r.score,
      })),
    };
  },
});

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";
import { openai } from "@ai-sdk/openai";
 
const memory = new Memory({
  // يخزن رسائل المحادثة الأخيرة
  options: {
    lastMessages: 20,
    semanticRecall: {
      topK: 3,
      messageRange: 50,
    },
  },
});
 
export const assistantAgent = new Agent({
  name: "Assistant",
  instructions: "You are a helpful assistant with memory of past conversations.",
  model: openai("gpt-4o"),
  memory,
});

// الرسالة الأولى
const res1 = await assistantAgent.generate("My name is Sarah", {
  threadId: "user-123",
});
 
// رسالة لاحقة — الوكيل يتذكر
const res2 = await assistantAgent.generate("What's my name?", {
  threadId: "user-123",
});
// المخرج: "Your name is Sarah"

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
 
const agent = new Agent({
  name: "Evaluated Agent",
  instructions: "Answer questions accurately and concisely.",
  model: openai("gpt-4o"),
  evals: {
    completeness: {
      type: "model-graded",
      prompt: "Rate if the response fully addresses the question (0-1):",
    },
    conciseness: {
      type: "model-graded",
      prompt: "Rate the conciseness of the response (0-1):",
    },
    hallucination: {
      type: "model-graded",
      prompt: "Rate if the response contains made-up information (0=hallucinated, 1=factual):",
    },
  },
});

npx mastra dev

npx mastra build
npx mastra deploy

import { openai } from "@ai-sdk/openai";
import { anthropic } from "@ai-sdk/anthropic";
import { google } from "@ai-sdk/google";
 
// استخدم نماذج مختلفة لوكلاء مختلفين
const fastAgent = new Agent({
  name: "Fast Responder",
  instructions: "Quick, concise answers.",
  model: openai("gpt-4o-mini"),
  tools: { searchTool },
});
 
const deepAgent = new Agent({
  name: "Deep Analyst",
  instructions: "Thorough, detailed analysis.",
  model: anthropic("claude-sonnet-4-20250514"),
  tools: { searchTool, summarizeTool },
});
 
const visionAgent = new Agent({
  name: "Image Analyzer",
  instructions: "Analyze and describe images.",
  model: google("gemini-2.0-flash"),
  tools: {},
});