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/processors.mdx
View on GitHub---
title: "المعالجات داخل الحلقة"
description: "حلقة المراقبة الداخلية/خطافات الدرابزين التي تراقب مخرجات النموذج المتدفقة واستدعاءات الأداة في منتصف التشغيل ويمكن أن تلغيها - خط التماس لحواجز الحماية في الوقت الفعلي وبوابات إثبات التنفيذ."
---
# المعالجات داخل الحلقة
`Processor` عبارة عن حلقة داخلية **مراقب/حاجز حماية** لتشغيل الوكيل. فهو يراقب إخراج النموذج المتدفق وتستدعيه الأداة طلبات _مع تقدم التشغيل_، ويحتفظ بحالة التسويد الخاصة به، ويمكنه **إجهاض** التشغيل قبل المطالبة بـ "تم". هذا هو الشرط الهيكلي الأساسي لحواجز الحماية في الوقت الفعلي (حظر الإخراج غير المسموح به في منتصف الدفق) وبوابة إثبات التنفيذ/التغطية (فحص ما على وشك القيام به النموذج وإيقافه).
<Diagram id="doc-block-18d4lyv" title={"حيث تطلق الخطافات الثلاثة أثناء الركض"} summary={"يراقب processOutputStream كل قطعة، وتستدعي أداة البوابات processOutputStep كل استجابة، ويسجل processOutputResult حكمًا في النهاية. يمكن إحباط أي خطاف باستخدام TripWire."}>
```html
<div class="diagram-proc">
<div class="diagram-node" data-rough>
stream chunks<br /><small class="diagram-muted">processOutputStream</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node" data-rough>
per model response<br /><small class="diagram-muted"
>processOutputStep — يضبط استدعاءات الأدوات</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-node" data-rough>
run end<br /><small class="diagram-muted"
>processOutputResult — الحكم</small
>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">↓</div>
<div class="diagram-pill warn">
abort() → TripWire → tripwire event
</div>
</div>
```
```css
.diagram-proc {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
}
.diagram-proc .diagram-arrow {
font-size: 22px;
line-height: 1;
}
.diagram-proc .diagram-pill {
flex-basis: 100%;
}
```
</Diagram>
<Callout id="doc-block-proc1cfg" tone="warning">
المعالج هو **تكوين**، وليس أداة، وليس إجراءً، وليس تأليفًا DSL. تقوم المعالجات فقط بمراقبة وتعديل حالة نطاق الدفق الخاصة بها و`abort()`. ولا تحدد أبدًا سلوك التطبيق، أو تستبدل actions, أو تظهر للنموذج. تنتمي عمليات التطبيق إلى [actions](/docs/actions-overview).
</Callout>
## الخطافات {#hooks}
ينفذ المعالج أي مجموعة فرعية من ثلاثة خطافات دورة حياة اختيارية (الشكل مستعار من معالجات إخراج Mastra):
| خطاف | الحرائق... | استخدمه من أجل... |
| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
| `processOutputStream` | لكل جزء متدفق (دلتا النص/التفكير) أثناء إنشاء النموذج | رد على الإخراج قبل أن يهبط المنعطف الكامل |
| `processOutputStep` | مرة واحدة لكل استجابة نموذج، أثناء تنفيذ الأداة | فحص استدعاءات الأداة للنموذج الذي على وشك التشغيل؛ بوابة لهم |
| `processOutputResult` | مرة واحدة عند نهاية التشغيل، مع النص المساعد الأخير | سجل حكمًا/إثباتًا للإجابة المكتملة |
يحصل كل معالج على كائن `state` القابل للتغيير ونطاق التشغيل والذي يستمر عبر كل واحد من استدعاءات الخطاف الخاصة به في عملية تشغيل واحدة و**معزول\*\*** عن حالة المعالجات الأخرى.
```ts
import type { Processor } from "@agent-native/core";
const noSecretsInOutput: Processor = {
name: "no-secrets",
processOutputStream({ part, abort }) {
if (part.type === "text" && /sk-live_/.test(part.text)) {
abort("Model attempted to emit a live secret token.", {
kind: "secret-leak",
});
}
},
};
const coverageGate: Processor = {
name: "proof-of-done",
processOutputStep({ toolCalls, state }) {
// Track what the model has actually done this run...
for (const call of toolCalls) {
(state.ran ??= new Set<string>()).add(call.name);
}
},
processOutputResult({ text, state }) {
// ...and record a verdict over the final answer.
const ran = state.ran as Set<string> | undefined;
state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
},
};
```
## الإجهاض باستخدام `TripWire` {#tripwire}
يقوم الخطاف بإيقاف التشغيل عن طريق استدعاء `abort(reason, meta?)`، مما يؤدي إلى ظهور **`TripWire`**. تلتقطه الحلقة، وترسل **حدث `tripwire`** واحدًا، وتتوقف بشكل واضح، وتظهر السبب كرسالة مساعدة نهائية.
```ts
import { TripWire } from "@agent-native/core";
```
يحتوي الحدث `tripwire` على:
| الحقل | اكتب | ملاحظات |
| ----------- | -------- | ----------------------------------------------------------- |
| `reason` | `string` | تم تمرير السبب الذي يمكن قراءته بواسطة الإنسان إلى `abort`. |
| `processor` | `string` | اسم المعالج الذي تم إحباطه عندما أعلن عن `name`. |
يحمل `TripWire` أيضًا `meta` المنظم الاختياري واسم `processor` الأصلي للمستهلكين الآليين الذين يتحقق منهم `instanceof`. نظرًا لأن التوقف أمر سهل، فإن `processOutputResult` يستمر في تشغيل النص النهائي (المتوقف) حتى يتمكن معالج إثبات التنفيذ من تسجيل حكمه حتى عند إلغاء التشغيل.
## معالجات الأسلاك {#wiring}
يتم تكوين المعالجات في التعليمات البرمجية عبر مصفوفة `processors` على `runAgentLoop`:
```ts
await runAgentLoop({
engine,
model,
systemPrompt,
tools,
messages,
actions,
send,
signal,
processors: [noSecretsInOutput, coverageGate],
});
```
**الحمل الصفري عند عدم الاستخدام.** تقوم الحلقة ببناء سلسلة المعالج فقط عند توفير معالج واحد على الأقل؛ عند حذف `processors` أو تركه فارغًا، لن يتم تشغيل أي من أكواد التماس وتكون الحلقة بدون تغيير بايت مقابل بايت. تعمل الخطافات بترتيب التسجيل وقد تكون متزامنة أو غير متزامنة.
<Callout id="doc-block-proc1note" tone="info">
يعتبر التماس على مستوى الحلقة هو ما يمكن تسليمه اليوم ويمكن استدعاؤه مباشرة بواسطة الوكلاء الفرعيين، A2A، MCP، والاختبارات. يعد ربط `processors` من خلال معالج الدردشة HTTP (بحيث يمكن لمحلل كل طلب تهيئتها دون الاتصال بـ `runAgentLoop` مباشرة) بمثابة توصيلات ملائمة لم يتم توصيلها بعد - قم بتكوين المعالجات في موقع الاتصال `runAgentLoop` في الوقت الحالي.
</Callout>
## ما التالي
- [**Durable Resume**](/docs/durable-resume) — كيف تتغلب الحلقة على الانقطاعات دون إعادة تشغيل التأثيرات الجانبية المكتملة.
- [**Custom Agents & Teams**](/docs/agent-teams) — يقوم الوكلاء الفرعيون بتشغيل نفس الحلقة ويمكنهم حمل المعالجات الخاصة بهم.
- [**Observability**](/docs/observability) — تسجيل قرارات المعالج جنبًا إلى جنب مع آثار التشغيل.
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 |