> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# تكامل Mastra

> ابنِ وكلاء وأدوات وسير عمل بلغة TypeScript باستخدام Mastra عبر نماذج Venice الخاصة والمتوافقة مع OpenAI.

[Mastra](https://mastra.ai/) هو إطار عمل بلغة TypeScript لبناء وكلاء الذكاء الاصطناعي وأدواتهم وسير العمل. اربطه بـ Venice عبر تهيئة نقطة نهاية نموذج مخصّصة متوافقة مع OpenAI.

## المتطلبات الأساسية

* Node.js 22.18 أو أحدث
* [مفتاح Venice API](/guides/getting-started/generating-api-key)

## إنشاء مشروع Mastra

<CodeGroup>
  ```bash npm theme={"system"}
  npm create mastra@latest
  ```

  ```bash pnpm theme={"system"}
  pnpm create mastra
  ```

  ```bash yarn theme={"system"}
  yarn create mastra
  ```

  ```bash bun theme={"system"}
  bunx create-mastra
  ```
</CodeGroup>

أضف مفتاح Venice API إلى ملف `.env` الخاص بالمشروع الذي تم إنشاؤه:

```bash theme={"system"}
VENICE_API_KEY=your-venice-api-key
```

<Warning>
  احتفظ بملف `.env` خارج إدارة الإصدارات. لا تكشف مفتاح Venice API الخاص بك في التعليمات البرمجية التي تعمل في المتصفح.
</Warning>

## إنشاء وكيل مدعوم بـ Venice

أنشئ وكيلًا ووجّه تهيئة النموذج الخاصة به إلى Venice API:

```typescript theme={"system"}
// src/mastra/agents/venice-agent.ts
import { Agent } from '@mastra/core/agent'

export const veniceAgent = new Agent({
  id: 'venice-agent',
  name: 'Venice Agent',
  instructions: `
    You are a concise, privacy-respecting assistant.
    Give accurate answers and say when you are uncertain.
  `,
  model: {
    id: 'venice/venice-uncensored',
    url: 'https://api.venice.ai/api/v1',
    apiKey: process.env.VENICE_API_KEY,
  },
})
```

الجزء الأول من `id` هو تسمية التوجيه في Mastra. يرسل Mastra بقية معرّف النموذج، وهو `venice-uncensored`، إلى Venice.

<Note>
  اضبط `url` على عنوان URL الأساسي للـ API الموضح أعلاه. لا تُلحق `/chat/completions`؛ فـ Mastra يضيف هذا المسار.
</Note>

سجّل الوكيل في نسخة Mastra الخاصة بك:

```typescript theme={"system"}
// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { veniceAgent } from './agents/venice-agent'

export const mastra = new Mastra({
  agents: { veniceAgent },
})
```

شغّل خادم التطوير وافتح عنوان URL الظاهر في الطرفية لاختبار الوكيل داخل Mastra Studio:

```bash theme={"system"}
npm run dev
```

## توليد استجابة

استرجع الوكيل المسجّل واستدعِ `generate()`:

```typescript theme={"system"}
import { mastra } from './src/mastra/index'

const agent = mastra.getAgentById('venice-agent')
const result = await agent.generate(
  'Explain why zero data retention matters in two sentences.',
)

console.log(result.text)
console.log(result.usage)
```

## بث استجابة

استخدم `stream()` عندما ترغب في عرض المخرجات لحظة وصولها:

```typescript theme={"system"}
const agent = mastra.getAgentById('venice-agent')
const result = await agent.stream(
  'Write a short poem about private AI inference.',
)

for await (const chunk of result.textStream) {
  process.stdout.write(chunk)
}
```

## إضافة الأدوات

تستخدم أدوات Mastra مخططات Zod للتحقق من مدخلاتها ومخرجاتها. استخدم نموذج Venice يدعم استدعاء الدوال عند إرفاق أدوات بوكيل.

```typescript theme={"system"}
// src/mastra/tools/model-info.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const modelInfoTool = createTool({
  id: 'model-info',
  description: 'Returns a short description of a Venice model',
  inputSchema: z.object({
    model: z.string().describe('A Venice model ID'),
  }),
  outputSchema: z.object({
    description: z.string(),
  }),
  execute: async ({ model }) => {
    const descriptions: Record<string, string> = {
      'venice-uncensored': 'A fast, uncensored general-purpose model.',
      'zai-org-glm-5-1': 'A private model for reasoning and tool use.',
    }

    return {
      description: descriptions[model] ?? `No description found for ${model}.`,
    }
  },
})
```

أرفق الأداة بوكيل:

```typescript theme={"system"}
// src/mastra/agents/model-guide-agent.ts
import { Agent } from '@mastra/core/agent'
import { modelInfoTool } from '../tools/model-info'

export const modelGuideAgent = new Agent({
  id: 'model-guide-agent',
  name: 'Venice Model Guide',
  instructions: 'Help users choose a Venice model. Use modelInfoTool when needed.',
  model: {
    id: 'venice/zai-org-glm-5-1',
    url: 'https://api.venice.ai/api/v1',
    apiKey: process.env.VENICE_API_KEY,
  },
  tools: { modelInfoTool },
})
```

## توليد مخرجات مهيكلة

مرّر مخطط Zod عبر `structuredOutput` لاستقبال بيانات موثّقة:

```typescript theme={"system"}
import { z } from 'zod'

const result = await veniceAgent.generate(
  'Compare private and data-retaining AI inference.',
  {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        privacyBenefits: z.array(z.string()),
        recommendation: z.string(),
      }),
    },
  },
)

console.log(result.object)
```

إذا كان النموذج المختار لا يدعم وضع المخرجات المهيكلة في الـ API، فاضبط `jsonPromptInjection: true` داخل `structuredOutput` ليقوم Mastra بإضافة المخطط إلى التوجيه (prompt) بدلًا من ذلك.

## تغيير النماذج

لاستخدام نموذج نصي آخر من Venice، حافظ على بادئة التوجيه `venice/` واستبدل بقية معرّف النموذج:

```typescript theme={"system"}
model: {
  id: 'venice/qwen3-5-9b',
  url: 'https://api.venice.ai/api/v1',
  apiKey: process.env.VENICE_API_KEY,
}
```

تصفّح [نماذج Venice المتاحة](/models/overview) وتحقق من قدراتها قبل اختيار نموذج لاستدعاء الأدوات أو الرؤية أو المخرجات المهيكلة.

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="الـ API يعيد 401 Unauthorized">
    تأكد من وجود `VENICE_API_KEY` في البيئة التي يعمل فيها Mastra، ثم أعِد تشغيل خادم التطوير بعد تعديل `.env`.
  </Accordion>

  <Accordion title="الـ API يُفيد بأن النموذج غير موجود">
    استخدم معرّف النموذج تمامًا كما هو معروض في [صفحة النماذج](/models/overview). في Mastra، أضف إليه البادئة `venice/`، مثل `venice/venice-uncensored`.
  </Accordion>

  <Accordion title="الطلبات تعيد 404 Not Found">
    اضبط عنوان URL للنموذج على `https://api.venice.ai/api/v1`. لا تستخدم نقطة النهاية الكاملة `/chat/completions`.
  </Accordion>

  <Accordion title="الوكيل لا يستدعي أداته">
    اختر نموذجًا يدعم استدعاء الدوال، ووضّح متى ينبغي للوكيل استخدام الأداة ضمن تعليماته، وعرّف الأداة باستخدام `createTool()`.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="وثائق Mastra" icon="book" href="https://mastra.ai/docs">
    تعرّف على المزيد حول وكلاء Mastra وأدواتها وسير العمل
  </Card>

  <Card title="نماذج Venice" icon="database" href="/models/overview">
    تصفّح النماذج والقدرات المدعومة
  </Card>
</CardGroup>