BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/evals.mdx
View on GitHub---
title: "بوابة تقييم CI"
description: "اكتب حالات اختبار *.eval.ts التي تقوم بتشغيل الوكيل الحقيقي مقابل المدخلات الثابتة، وسجل المخرجات باستخدام أدوات تسجيل قابلة للتركيب، وبوابة CI/النشر على عتبة."
---
# بوابة تقييم CI
تعد عمليات التقييم اختبارًا بدائيًا من الدرجة الأولى: فأنت تعلن عن الموجه بالإضافة إلى السلوك الذي تتوقعه، ويقوم العداء **في الواقع بتشغيل حلقة الوكيل** مقابل هذا الإدخال، ويسجل المخرجات باستخدام أدوات تسجيل قابلة للتركيب، ويخرج من الصفر إذا سجلت أي حالة أقل من العتبة. هذا الخروج غير الصفري يجعل `agent-native eval` بوابة نشر CI منسدلة.
هذا مكمل للتسجيل اللاحق في [Observability](/docs/observability):
- **تقييمات إمكانية الملاحظة** (`observability/evals.ts`) — _"كيف كان أداء هذا التشغيل الحقيقي؟"_ السلبي، الذي يتم أخذ العينات منه، ويعيش بجوار الآثار.
- **`*.eval.ts` (هذا البدائي)** — _"هل يفعل الوكيل الشيء الصحيح على هذا الإدخال الثابت؟"_ بوابة CI نشطة وحتمية يتم تشغيلها عبر CLI.
يقوم المشغل بحل محرك/نموذج غير موفر الخدمة من السجل الحالي - لا يوجد نموذج مضمن - لذلك تعمل المجموعة نفسها على أي محرك تم تكوين التطبيق من أجله.
<Diagram id="doc-block-1xedr0l" title={"من المدخلات الثابتة لنشر البوابة"} summary={"يقوم العداء فعليًا بتشغيل حلقة الوكيل في كل حالة، ويسجل المخرجات، ويخرج من الصفر إذا انخفض أي مسجل عن العتبة - مما يجعله بوابة CI قابلة للإسقاط."}>
```html
<div class="eval-flow">
<div class="diagram-node">
*.eval.ts<br /><small class="diagram-muted"
>prompt + expected behavior</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node">
تشغيل حلقة الوكيل<br /><small class="diagram-muted"
>real engine/model</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node">
Scorers<br /><small class="diagram-muted"
>every one must pass threshold</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-col">
<div class="diagram-box ok">exit 0 → deploy</div>
<div class="diagram-box warn">exit 1 → block</div>
</div>
</div>
```
```css
.eval-flow {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
.eval-flow .diagram-node {
display: flex;
flex-direction: column;
gap: 2px;
padding: 10px 14px;
}
.eval-flow .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
}
.eval-flow .diagram-arrow {
font-size: 22px;
line-height: 1;
}
```
</Diagram>
## كتابة التقييم {#writing}
أسقط ملف `*.eval.ts` في أي مكان في التطبيق (أو ملف `evals/*.ts`). كل ملف `export default defineEval(...)` (أو يصدر مجموعة منهم):
```ts
// evals/greeting.eval.ts
import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
export default defineEval({
name: "greets the user by name",
input: { prompt: "Say hi to Ada." },
threshold: 0.7, // per-scorer pass bar; default 0.5
scorers: [
contains("Ada"),
llmJudge({ criteria: "friendliness", rubric: "1.0 = warm greeting" }),
],
});
```
يتم تمرير التقييم فقط عندما يصل **كل** المسجل إلى الحد الأدنى. حقول `defineEval` الرئيسية:
| الحقل | اكتب | ملاحظات |
| ----------- | --------------------- | ----------------------------------------------------------------- |
| `name` | سلسلة | مطلوب. موضح في التقرير. |
| `input` | `{ prompt, history }` | مطلوب `prompt`؛ المنعطفات الاختيارية السابقة لـ `{ role, text }`. |
| `scorers` | `Scorer[]` | مطلوب، واحد على الأقل. |
| `threshold` | رقم `0..1` | شريط التمرير لكل هداف. الافتراضي `0.5`؛ يمكن تجاوزه من CLI. |
| `run` | الوظيفة | تجاوز اختياري للإعداد المخصص (بيانات أولية، متعددة المنعطفات). |
إن عملية تشغيل الوكيل التي يتم تسليمها إلى الهدافين صغيرة الحجم وغير ملائمة للنقل:
```ts
interface AgentRunOutput {
text: string; // concatenated assistant text
toolCalls: readonly string[]; // tool/action names, in call order
ok: boolean; // completed without a terminal error
error?: string;
runId: string;
durationMs: number;
}
```
## الهدافين المدمجين {#built-in}
مستورد من `@agent-native/core/eval`:
| هداف | النتيجة | النموذج؟ |
| ------------------------ | -------------------------------------------------------------------- | -------- |
| `exactMatch(expected)` | `1.0` إذا كان النص يساوي `expected` (مقتطع, غير حساس لحالة الأحرف) | لا |
| `contains(needles)` | جزء من السلاسل الفرعية المطلوبة موجودة (لذلك تظهر النتائج الجزئية) | لا |
| `usesTool(toolName)` | `1.0` إذا قام الوكيل باستدعاء تلك الأداة/الإجراء مرة واحدة على الأقل | لا |
| `llmJudge({ criteria })` | سجل LLM كحكم مقابل قواعد تقييم اللغة الطبيعية، → `0..1` | نعم |
يأخذ `exactMatch` و`contains` `{ caseSensitive }` اختياريًا. يأخذ `llmJudge` `{ criteria, rubric?, name?, scoreRange? }` - تتم تسوية مخرجاته إلى `[0, 1]`، ونموذج القاضي هو ما يحله العداء (ليس مزودًا مضمنًا على الإطلاق).
## الهدافون المخصصون: المسار المكون من 4 خطوات {#custom}
يبني `createScorer` هدافًا من أسلوب Mastra ذو 4 خطوات. مطلوب `generateScore` فقط:
<Diagram id="doc-block-aa66rm" title={"خط أنابيب الهداف ذو الأربع خطوات"} summary={"المعالجة المسبقة والتحليل الافتراضي للهوية؛ مطلوب فقط generatorScore. يمكن للتحليل تشغيل JS عادي أو استدعاء القاضي LLM عبر ctx."}>
```html
<div class="scorer">
<div class="diagram-card">
<span class="diagram-pill">preprocess(run)</span
><small class="diagram-muted"
>transform the run/output · optional</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card">
<span class="diagram-pill">analyze(x, ctx)</span
><small class="diagram-muted"
>plain JS or LLM judge · optional</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card">
<span class="diagram-pill accent">generateScore(a)</span
><small class="diagram-muted"
>→ 0..1 normalized · <strong>required</strong></small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-card">
<span class="diagram-pill">generateReason</span
><small class="diagram-muted">human-readable why · optional</small>
</div>
</div>
```
```css
.scorer {
display: flex;
align-items: center;
gap: 10px;
flex-wrap: wrap;
}
.scorer .diagram-card {
display: flex;
flex-direction: column;
gap: 2px;
padding: 8px 12px;
}
.scorer .diagram-arrow {
font-size: 20px;
line-height: 1;
}
```
</Diagram>
```text
preprocess(run) → x transform the run/output (optional)
analyze(x, ctx) → analysis plain JS OR an LLM judge (optional)
generateScore(a) → 0..1 REQUIRED, normalized
generateReason(...) → string human-readable why (optional)
```
`preprocess` و`analyze` الافتراضيان للهوية (يرى الهداف `AgentRunOutput` الخام). تتلقى خطوة `analyze` `ctx` مع مساعد `judge()` غير الموفر للتسجيل المدعوم من LLM:
```ts
import { createScorer, clamp01 } from "@agent-native/core/eval";
// A scorer that rewards short, tool-using answers.
const concise = createScorer({
name: "concise_with_tool",
analyze(run) {
return {
words: run.text.trim().split(/\s+/).length,
usedTool: run.toolCalls.length > 0,
};
},
generateScore({ words, usedTool }) {
if (!usedTool) return 0;
return clamp01(1 - Math.max(0, words - 40) / 200);
},
generateReason({ analysis }) {
return `${analysis.words} words, tool used: ${analysis.usedTool}`;
},
});
```
## تشغيل البوابة {#cli}
```bash
agent-native eval # run every *.eval.ts; non-zero exit on failure
agent-native eval billing # فقط الملفات التي يحتوي مسارها على "billing"
agent-native eval --json # machine-readable report (for CI)
agent-native eval --threshold 0.8 # override every eval's pass threshold (0..1)
```
يكتشف الأمر `**/*.eval.ts` و`evals/*.ts` ضمن التطبيق الحالي، ويقوم بتشغيل الوكيل لكل إدخال، ويسجله، ويطبع جدولًا قابلاً للقراءة (أو JSON)، و**يخرج من الصفر في حالة وجود أي درجات تقييم أقل من الحد الخاص به**.
رموز الخروج:
| الرمز | المعنى |
| ----- | ----------------------------------------------------------------------------------- |
| `0` | تم اجتياز جميع عمليات التقييم — _or_ لم يتم العثور على ملفات تقييم (متوافقة مع CI). |
| `1` | تم تسجيل تقييم واحد على الأقل أقل من الحد الأدنى، أو حدث خطأ في المجموعة. |
| `2` | وسيطات غير صالحة (على سبيل المثال، `--threshold` خارج `[0, 1]`). |
### تخطي التقييمات المحكومة {#skipping}
استخدم `skipReason` عندما تكون مجموعة التقييمات مخصصة عمدا للتشغيل اليدوي أو
الليلي أو المعتمد على الأسرار. لا تشغل التقييمات المتخطاة الوكيل أو أدوات
التسجيل، ولا تفشل المجموعة، وتظهر في JSON مع `status: "skipped"` و
`skipReason`. أبق التغطية الحتمية الرخيصة في CI العادي لطلبات السحب.
### كبوابة نشر CI {#ci}
قم بإضافته إلى المسار الذي يتم تشغيله قبل النشر:
```yaml
# .github/workflows/deploy.yml (excerpt)
- run: npx agent-native eval --json
```
الانحدار الذي يسقط أي مسجل أقل من الحد يفشل في الخطوة ويمنع النشر. يخرج التطبيق الذي لا يحتوي على ملفات تقييم من `0`، لذا فإن اعتماد التقييمات يعد اختيارًا لكل تطبيق.
## من أثر إنتاج {#from-trace}
عندما يفاجئك تشغيل حقيقي — نجح في العرض ثم فشل في الإنتاج، أو استدعى الأداة الخطأ — رقِّ ذلك الأثر المكتمل إلى حالة CI بدل اختراع موجّه.
```bash
agent-native eval promote <runId> --write evals/from-trace.eval.ts
```
يحفظ الأمر صف `EvalDataset` (نفس المساعد الذي يستخدمه لوحة المراقبة والإجراء `promote-trace-eval`) ويكتب تثبيت `defineEval` تكتشفه بوابة `agent-native eval` أصلًا. المقيّمون الافتراضيون هم `usesTool(...)` لكل أداة ناجحة مع `--must-contain` اختياري. التشغيل المقطوع أو الملغى أو بلا رسالة مستخدم يفشل مغلقًا.
الإجراء المستضاف و`POST /_agent-native/observability/traces/:runId/promote` لا يكتبان شجرة التطبيق. استخدم `--write` لبوابة CI. تفاصيل التتبع في لوحة Observability فيها **Promote to eval**.
## ما هي الخطوة التالية
- [**Observability**](/docs/observability) — التسجيل اللاحق لعمليات الإنتاج الحقيقية (الطبقة التكميلية)
- [**Actions**](/docs/actions-overview) — الأدوات/actions التي تظهر في `toolCalls`
- [**Agent Teams**](/docs/agent-teams) — الوكلاء الفرعيون الذين قد يمارسهم التقييم
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |