المزوّدون

import { resolveProvider, LLMProviderRegistry } from '@lousho/build-ai-agent';

// The convenient way — reads the credential from the environment
const openai = resolveProvider('openai/gpt-4o-mini');       // OPENAI_API_KEY
const anthropic = resolveProvider('anthropic/claude-sonnet-5'); // ANTHROPIC_API_KEY
const openrouter = resolveProvider('openrouter/openai/gpt-4o-mini'); // OPENROUTER_API_KEY
const ollama = resolveProvider('ollama/llama3.1');           // OLLAMA_BASE_URL

// Or construct a provider directly via the registry
const custom = LLMProviderRegistry.create('openai', {
  apiKey: process.env.OPENAI_API_KEY,
  defaultModel: 'gpt-4o-mini',
});

​

اختيار المزوّد في createAgent()

1. model: 'provider/model' - يُحلّ بواسطة resolveProvider()؛ ويأتي المفتاح من متغير البيئة المتعارف عليه للمزوّد (انظر بيانات اعتماد المزوّدين).
2. provider: <LLMProvider> - مزوّدك الخاص، أو مزوّد مدمج مضبوط، أو مزوّد وهمي. يمكنك أيضًا تمرير model (معرّف مجرد مثل 'gpt-4o'): فيصبح نموذج هذا الوكيل، ويتقدّم على النموذج الافتراضي للمزوّد.
3. لا هذا ولا ذاك - يُحلّ من البيئة: LOUSHO_MODEL (سلسلة provider/model) إن كان مضبوطًا، وإلا فأول الموجود من OPENAI_API_KEY وANTHROPIC_API_KEY وOPENROUTER_API_KEY وOLLAMA_BASE_URL. وإذا لم يكن أي منها مضبوطًا رمى خطأً يسرد الحلول.

import { createAgent, createMockProvider, resolveProvider } from '@lousho/build-ai-agent';

const fromString = createAgent({ model: 'anthropic/claude-sonnet-5' });
const fromInstance = createAgent({ provider: resolveProvider('openai/gpt-4o-mini'), model: 'gpt-4o' });
const offline = createAgent({ provider: createMockProvider({ responses: ['Hi! How can I help?'] }) });

​

إعادة المحاولة والنماذج الاحتياطية

import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  retry: { maxRetries: 3 }, // or false
  fallbackModels: ['anthropic/claude-3-5-haiku-latest', 'openrouter/meta-llama/llama-3.1-70b-instruct'],
});

​

أي نموذج يعمل؟

​

الإدخال متعدد الوسائط

import { readFileSync } from 'node:fs';
import { AgentBuilder, AgentExecutor, createAgent, resolveProvider, textOf, type Message } from '@lousho/build-ai-agent';

const agent = AgentBuilder.create().setName('vision').setPrompt('Describe images briefly.').build();
const input: Message[] = [
  {
    role: 'user',
    content: [
      { type: 'text', text: 'What is in these pictures?' },
      { type: 'image', image: 'https://example.com/cat.png' },
      { type: 'image', image: new Uint8Array(readFileSync('dog.png')), mimeType: 'image/png' },
    ],
  },
];

const result = await AgentExecutor.execute({ agent, input, provider: resolveProvider('openai/gpt-4o-mini') });
console.log(textOf(input[0]), '->', result.text); // textOf(): the text parts of a message

// The same through the public API: parts become one user message.
const answer = await createAgent({ prompt: 'Describe images briefly.', model: 'openai/gpt-4o-mini' }).send([
  { type: 'text', text: 'What is in this picture?' },
  { type: 'image', image: 'https://example.com/cat.png' },
]);
console.log(answer.text);

• الصور تصل إلى النموذج ضمن رسائل user مع كل المزوّدين المدمجين (مع Anthropic وOllama تنزّل حزمة ai الصورة من عنوانها أولًا). اختر نموذجًا يدعم الرؤية: Ollama يتجاهل الصور مع نموذج نصي فقط، وOpenRouter يرفضها معه.
• الملفات لا يرسلها المزوّدون المدمجون، على أي إصدار رئيسي من ai: يُرسَل جزء الملف كملاحظة نصية ([file report.pdf (application/pdf) not sent]) ويحذّر المزوّد مرة واحدة. الصنف الفرعي من مزوّد يقبل نموذجه الملفات يضبط protected readonly acceptsFileParts = true ليرسلها كأجزاء ملفات بصيغة ai v4.
• رسائل system وassistant وtool تُرسَل بأجزائها النصية.
• كل ما يقرأ نص الرسائل يستخدم textOf(): estimateTokens() (يُحتسب كل جزء صورة أو ملف 1,000 رمز ثابتة)، وضغط السياق، وأشرطة تسجيل recordReplay() (التي تخزّن النص وبصمة كل صورة أو ملف، أو عنوانه) وmockModel(). يحفظ FileSessionStore البايتات بترميز base64 ({ "$bytes": "..." }) ويعيد تحميلها على هيئة Uint8Array؛ ويفعل SqliteStore (للجلسات ونقاط الحفظ) الشيء نفسه.

​

أصناف المزوّدين

​

إصدارات Vercel AI SDK

• تتحوّل الرسائل إلى كائنات ModelMessage: وسائط استدعاء الأداة تصبح input الخاص به، ونتيجة الأداة تصبح output (json أو text، وerror-json أو error-text حين تفشل الأداة)، وmimeType في جزء الصورة أو الملف يصبح mediaType. تبقى رسائل النظام في مواضعها (allowSystemInMessages).
• يُرسَل maxTokens باسم maxOutputTokens، والخطوة الواحدة بالشكل stopWhen: stepCountIs(1)، والأدوات باسم inputSchema (مخطط zod كما هو، ومخطط JSON Schema عبر jsonSchema()) دون execute، وresponseFormat على هيئة output بوضع JSON لا يمسّ نص الرد.
• يأتي الاستهلاك من inputTokens / outputTokens / totalTokens، مع cachedInputTokens من inputTokenDetails.cacheReadTokens وreasoningTokens من outputTokenDetails.reasoningTokens.
• يقرأ stream() المجرى fullStream الخاص بـ AI SDK على أي من الإصدارين الرئيسيين ويحوّله إلى القطع (chunks) نفسها: text-delta (في v6/v7 الحقل text، وفي v4 الحقل textDelta)، وtool-call (الاستدعاء الكامل الذي يرسله v6/v7 بعد tool-input-start/-delta/-end، أو استدعاء يُجمَّع من ذلك الإدخال حين لا يرسل النموذج استدعاءً كاملًا)، وfinish مع سبب الانتهاء الذي تعطيه AI SDK والاستهلاك المذكور أعلاه (في v6/v7 الحقل totalUsage). جزء error يجعل المجرى يُرفض بخطئه، على v4 أيضًا (كان v4 ينهي مجرى كهذا بسبب الانتهاء error)، وجزء abort يرفضه بسبب الإشارة. تغيّرات الاستدلال الجزئية (deltas) يُبلَّغ عنها قطعًا من النوع reasoning-delta وتظهر أحداثًا reasoning.* (انظر الاستدلال).

​

أين يعمل كل مزوّد