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 لملخص أو حالة.
output (بلا tool له أثر جانبي). وكودك يعرض الـ object بعد الـ validation على شخص، ولا ينفّذ إلا عندما يوافق، مع idempotency key مأخوذ من البيانات (رقم المطالبة)، لأن إعادة تشغيل الـ flow كله تستخرج من جديد:
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.
كيف يعمل
- الـ system prompt يأخذ قسم
## Output formatيطلب الإجابة النهائية كـ JSON object فقط يطابق الـ schema، معروض كـ JSON Schema. - نداءات الـ model التي لا تعرض tools تحمل
responseFormat: { type: 'json', schema }فيGenerateOptions: كل نداءات agent بلا tools، ونداء “أجب الآن” عندما تنفد الخطوات (انظر أدناه)، وخطوة الإصلاح. هو مجرد hint: الـ providers المدمجة المبنية علىai-SDK تفعّل JSON mode في الـ model (مع الـ schema في الـ models التي تدعم structured outputs؛ و OpenRouter والـ providerpiيرسلان 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' }. - عندما يرد الـ model بلا tool calls، يُحلَّل الرد كـ JSON (ووجود code fence
```jsonحوله مسموح) ثم يجري عليه validation بالـ schema. والرد القريب من الصحيح يُقرأ دون نداء إصلاح: عندما لا يكون الرد كله JSON، تُحذف كتل<think>…</think>، ويُستخدم أول fenced block، أو أول{…}/[…]متوازن، يُحلَّل وينجح في الـ validation. أي أن المقدمة النثرية، أو النثر بعد fenced block، أو كتلة reasoning قبل الـ JSON، كلها لا تكلّف شيئًا إضافيًا. وresult.textيحتفظ بالرد كما كتبه الـ model. - إذا كان غير صالح، يأخذ الـ 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 اللاحق لا يراهما أبدًا. - وإذا ظل غير صالح، يجري للـ 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.