الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
مرّر للـ agent zod schema في الخيار output، فيصبح الرد النهائي object typed وصالحًا وفق الـ schema: result.object. يستطيع الـ agent إجراء tool calls أولًا كالمعتاد؛ والإجابة النهائية وحدها يجب أن تطابق الـ schema. بادئة vendor/ في اسم الـ model هي التي تحدد الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثال: openrouter/openai/gpt-4o-mini).
نوع result.object هو z.output<typeof schema>، فيطبّق zod عليه الـ defaults والـ transforms. أما result.text فيحتفظ بنص JSON الخام الذي كتبه الـ model. يمكن أن يكون الـ schema من zod 3 أو zod 4: يتحوّل إلى JSON Schema بـz.toJSONSchema في zod 4 وبمحوّل ai SDK في zod 3، ويجري الـ validation في الحالتين بـsafeParse الخاصة بالـ schema نفسه. نوع output هو Standard Schema، مثل defineTool({ input })، فيستنتج TypeScript نوع result.object دون cast سواء كان الـ schema من zod 3، أو zod 4 (zod/v4 على zod 3.25، أو zod 4 نفسه)، أو أي Standard Schema آخر يستطيع إنتاج JSON Schema:

الـ schemas التي تعكس tool له أثر جانبي

عندما يعكس الـ output schema الـ payload الخاص بـ tool له أثر جانبي (مثلًا مصفوفة comments[] في output بجانب tool اسمه post_comment)، فإن كثيرًا من الـ models تضع البيانات في الـ object النهائي ولا تستدعي الـ tool أبدًا، أو تفعل الأمرين معًا. لا تعتمد على الـ model ليختار واحدًا منهما. إما أن تنفّذ الأثر الجانبي في كودك أنت من result.object بعد الـ validation، أو لا تعكس الـ payload أصلًا: اجعل الـ tool يأخذ البيانات، واترك output لملخص أو حالة.
في نمط “استخرج، ثم وافق، ثم نفّذ”، افصل الخطوات الثلاث بعضها عن بعض. الـ agent يستخرج فقط إلى output (بلا tool له أثر جانبي). وكودك يعرض الـ object بعد الـ validation على شخص، ولا ينفّذ إلا عندما يوافق، مع idempotency key مأخوذ من البيانات (رقم المطالبة)، لأن إعادة تشغيل الـ flow كله تستخرج من جديد:
وإذا كان يجب أن يستدعي الـ model الـ tool بنفسه، فاربطه بـneedsApproval، وراجع Approvals لإيقاف الـ run عند الرفض.

Sessions

agent.session() على agent له output يُرجع session تحمل فيها نتيجة send() (وكذلك result في stream()) الـobject typed لكل turn. لا يوجد output مختلف لكل نداء: الـ schema هو schema الـ agent.

Sub-agents

الـ sub-agent الذي له output schema خاص يرد على الـ lead بالـ object بعد الـ validation. نتيجة الـ tool task (وكذلك result في agent_await لمهمة تعمل في الخلفية) هي الـ object كـ JSON، بعده سطر فارغ ثم الـ footer المعتاد [sub-agent '<name>': ... taskId '<id>']، فالـ lead model يقرأ الـ object نفسه بدل صياغة نثرية عنه. وإذا ظل رد الـ sub-agent غير صالح بعد خطوة الإصلاح، يفشل نداء task بخطأ tool منظم (kind: 'execution' ورسالة تذكر مشاكل الـ schema)، ويستطيع الـ lead إجراء retry أو تغيير طريقته. والـ sub-agent الذي تنفد خطواته ثم يعطي object صالحًا في النداء الأخير الإجباري (عند نفاد الخطوات) يرد على الـ lead بذلك الـ object، مثل sub-agent أنهى عمله بشكل عادي؛ والـ footer يعرض سبب الانتهاء 'max-steps'، ويليه سطر يذكر أن الخطوات نفدت. الـ sub-agent لا يرث output الخاص بالـ lead: مخرجات كل agent خاصة به، والـ sub-agent بلا output يُرجع نصًا كالمعتاد. وإذا كان للـ agent المنشور خلف remoteAgent() output schema، فإنه يُرجع الـ object البعيد بالطريقة نفسها (JSON ثم الـ footer)، مقروء من object في حدث run.done في الـ stream البعيد.

الحقول الاختيارية

الحقول الاختيارية تعمل على الـ endpoints الصارمة للـ structured output (OpenAI و OpenRouter)، التي تشترط أن تكون كل خاصية مذكورة في required. في الـ JSON Schema المرسل للـ model، كل خاصية اختيارية (.optional()، .default()) تصبح required و nullable بدلًا من ذلك، وعلى كل المستويات: الـ objects المتداخلة، وعناصر المصفوفات، وفروع الـ unions. والـ null الذي يُرجعه الـ model لحقل كهذا يُحذف قبل الـ validation، فالـ schema الذي كتبته أنت يظل يقبله، وresult.object لا يحتوي مفتاحًا له. أما الحقل الذي يقبل null بنفسه (.nullable()، .nullish()) فيحتفظ بالـ null.

كيف يعمل

  1. الـ system prompt يأخذ قسم ## Output format يطلب الإجابة النهائية كـ JSON object فقط يطابق الـ schema، معروض كـ JSON Schema.
  2. نداءات الـ model التي لا تعرض tools تحمل responseFormat: { type: 'json', schema } في GenerateOptions: كل نداءات agent بلا tools، ونداء “أجب الآن” عندما تنفد الخطوات (انظر أدناه)، وخطوة الإصلاح. هو مجرد hint: الـ providers المدمجة المبنية على ai-SDK تفعّل JSON mode في الـ model (مع الـ schema في الـ models التي تدعم structured outputs؛ و OpenRouter والـ provider pi يرسلان response format صارم من نوع json_schema)، والـ custom provider يستطيع استخدامه أو تجاهله. النداء الذي يعرض tools يجري بدونه، ويجيب الـ model من الـ schema الموجود في الـ prompt: لأنه مع response format صارم بجانب الـ tools، تظل بعض الـ models (openai/gpt-4o-mini عبر OpenRouter) تستدعي tools حتى maxSteps بدلًا من أن تجيب. وtoolChoice: 'none' يُحسب كأنه لا tools معروضة. ولإرساله على كل نداء رغم ذلك، مرّر output: { schema, responseFormat: 'always' }.
  3. عندما يرد الـ model بلا tool calls، يُحلَّل الرد كـ JSON (ووجود code fence ```json حوله مسموح) ثم يجري عليه validation بالـ schema. والرد القريب من الصحيح يُقرأ دون نداء إصلاح: عندما لا يكون الرد كله JSON، تُحذف كتل <think>…</think>، ويُستخدم أول fenced block، أو أول {…} / […] متوازن، يُحلَّل وينجح في الـ validation. أي أن المقدمة النثرية، أو النثر بعد fenced block، أو كتلة reasoning قبل الـ JSON، كلها لا تكلّف شيئًا إضافيًا. وresult.text يحتفظ بالرد كما كتبه الـ model.
  4. إذا كان غير صالح، يأخذ الـ model خطوة إصلاح واحدة: رسالة user تبدأ بـ[output-invalid] وتعدّد المشاكل، مثلًا 1 issue (tempC: Expected number, received string). وعندما يكون الرد هو الـ JSON Schema نفسه (بعض الـ models المحلية تكرره)، تذكر الرسالة ذلك وتعرض بدلًا منه مثال object بالشكل الصحيح. خطوة الإصلاح تُحسب من maxSteps، ولا توجد خطوة إذا نفدت الميزانية. ولا توجد خطوة أيضًا إذا انقطع الرد عند حد maxTokens (كان finishReason الخاص بالـ model هو 'length'): سينقطع الإصلاح بالطريقة نفسها، فينتهي الـ run فورًا مع outputError.kind: 'truncated' ورسالة تطلب رفع modelSettings.maxTokens. رسالة الإصلاح والرد الذي رفضته تُرسلان لذلك النداء الواحد فقط: ليستا في result.messages ولا في transcript الـ session، فالـ turn اللاحق لا يراهما أبدًا.
  5. وإذا ظل غير صالح، يجري للـ run resolve (لا reject) مع finishReason: 'output-invalid'، دون object، ومع outputError: { kind, message, issues: [{ path, message }] }، حيث kind هو 'invalid' أو 'truncated'.

عند نفاد الخطوات

عندما يكون الـ model ما زال يستدعي tools وتنفد maxSteps، فإن الـ run الذي فيه output لا يستسلم: يُجري نداء model أخيرًا بلا tools معروضة (“أجب الآن”) ويُجري validation على ذلك الرد بالطريقة نفسها. الإجابة الصالحة تنهي الـ run بـfinishReason: 'max-steps' مع object؛ وغير الصالحة تنهيه بـ'output-invalid' مع outputError. لا يحدث النداء الإضافي إذا كان حد آخر من الميزانية (الـ tokens، التكلفة، المدة) قد استُنفد أصلًا. وlimits.maxSteps عندما ينفد يحصل على النداء نفسه؛ لكن ذلك الـ run يظل ينتهي بـ'budget-exceeded' مع result.budget، ومعه object إذا نجحت الإجابة في الـ validation. ومثل رسالة الإصلاح، prompt “أجب الآن” يُرسل لذلك النداء فقط ولا يُحفظ في result.messages ولا في transcript الـ session.

الـ schema في الـ prompt

الخطوتان 1 و 2 ترسلان الـ schema مرتين في النداء بلا tools: مرة داخل كتلة ## Output format في الـ system prompt، ومرة في responseFormat. عندما يفرض الـ provider responseFormat (structured outputs في OpenAI، و OpenRouter، والـ provider pi) تصبح نسخة الـ prompt زائدة؛ ومع schema كبير تكلّف حوالي ألف token في كل نداء. مرّر output بصيغة { schema, promptSchema: false } لتترك الـ schema خارج الـ prompt؛ طلب “JSON فقط” يبقى، وبما أن responseFormat يصبح النسخة الوحيدة من الـ schema، فهو يُرسل في كل نداء، بما فيها النداءات التي تعرض tools (قيمة responseFormat الافتراضية هنا 'always'؛ اضبطها على 'final' لإبعاده عن تلك النداءات):
أبقِ الافتراضي (promptSchema: true، أو output: schema مباشرة) عندما يتعامل الـ provider - أو الـ model - مع responseFormat كـ hint لـ JSON mode فقط (الـ providers المدمجة المبنية على ai-SDK تحذف الـ schema للـ models التي لا تدعم structured outputs؛ والـ custom provider قد يتجاهله كليًا). في هذه الحالة نسخة الـ prompt هي المكان الوحيد الذي يرى فيه الـ model الشكل المطلوب للإجابة. وأبقِه أيضًا لـ agent لديه tools: نداءاته التي تعرض tools لا تحمل responseFormat افتراضيًا، فنسخة الـ prompt هي ما تجيب منه.

المخرجات المُصلَحة وقواعد العمل

عندما يأتي object من خطوة الإصلاح، تحتوي النتيجة outputRepaired: true. الإصلاح يعالج المشاكل التي تُعرض عليه، فقد يغيّر القيم حتى تنجح في الـ validation. إذا كان الـ schema يرمّز قاعدة عمل، مثل refinement يشترط أن total يساوي subtotal + tax، فالـ model المطلوب منه إصلاح فاتورة إجماليها المطبوع يخالف القاعدة قد يعيد كتابة الإجمالي حتى يمر الـ object. اجعل الـ schema مقتصرًا على بنية المستند، وتحقّق من قواعد العمل على result.object بعد الاستخراج، حيث الفشل مسؤوليتك أنت للإبلاغ عنه:

حدود الـ schema

الـ endpoints الصارمة للـ structured output (OpenAI و Anthropic و OpenRouter أمامهما) ترفض بعض أشكال JSON Schema بخطأ 400، و Claude أجاب على record بـ{}. الـ schema المرسل للـ model يُعاد كتابته بأشكال تقبلها، ورد الـ model يُرجَع إلى شكل الـ schema الخاص بك قبل الـ validation، فيكون لـ result.object دائمًا النوع الذي كتبته. فقط result.text (الرد الخام) يُظهر الشكل المُعاد كتابته. والرد الذي يأتي بشكل الـ schema الخاص بك نفسه (من model لا يفرض الـ schema) ينجح في الـ validation أيضًا.
  • لا z.date(). JSON ليس فيه نوع للتاريخ، فحقل z.date() في zod 4 لن ينجح في الـ validation أبدًا. createAgent() يرمي ConfigurationError يذكر اسم الحقل. استخدم z.iso.date() أو z.iso.datetime() لنص ISO، أو z.iso.datetime().pipe(z.coerce.date()) لتحصل على Date في result.object.

Streaming

agent.stream() يعمل بالطريقة نفسها: يجري لـ run.result resolve ومعه object، والحدث الأخير run.done يحمل object (مرمّزًا كـ JSON) إذا كان الرد صالحًا. خطوة الإصلاح تظهر كزوج إضافي من step.start / step.done. راجع Streaming. أثناء بث الرد، كل text.delta يغيّر الرد المحلَّل يتبعه حدث object.delta، وobject فيه هو الـ object الجزئي حتى الآن: قيمة النص غير المكتملة تُقطع عند آخر النص، والمفتاح أو الرقم غير المكتمل يُترك، والـ objects والمصفوفات المفتوحة تُغلق. لا يجري عليه validation وفق الـ schema (قد يكون حقل ما زال ناقصًا)؛ استخدمه لعرض التقدّم، وresult.object للإجابة. والـ UI bindings تحتفظ به باسم partialObject.

متقدم: executor API

AgentExecutor.execute() وAgentExecutor.stream() تأخذان خيار output نفسه. هناك نوع result.object هو unknown؛ حلّله مرة أخرى بالـ schema، أو استخدم createAgent() إذا أردت النوع المستنتج.

Testing

مع mockModel، جهّز مسبقًا نص JSON الذي سيكتبه الـ model:

انظر أيضًا

  • Decisions: decide() يجيب على أسئلة من نوع predicate / choice / score حول input واحد، على endpoint سريع مخصص لذلك؛ وهو الخيار الصحيح عندما تحتاج تصنيفًا أو درجة ثقة، لا object.