كيفية إنشاء واستخدام الوكلاء الفرعيين في Claude Code - دليل عملي

CometAPI
AnnaOct 22, 2025
كيفية إنشاء واستخدام الوكلاء الفرعيين في Claude Code - دليل عملي

يُعدّ الوكلاء الفرعيون من أكثر الإضافات فائدةً في نظام Claude Code / Claude Agent: فهم يُمكّنونك من تقسيم سير العمل المُعقّد إلى "زملاء" ذكاء اصطناعي أصغر ومتخصص، والحفاظ على سياق السلسلة الرئيسية، وتقييد الوصول إلى الأدوات بأمان. تشرح هذه المقالة ما هي العوامل الفرعية, كيفية إنشائها واستدعائها (CLI ونظام الملفات ومجموعة أدوات التطوير البرمجية)، مبادئ التصميم يجب عليك اتباعها عند بنائها، و رمز العينة الملموس يمكنك النسخ والتكيف.

ما هي العوامل الفرعية؟

A وكيل فرعي هو مساعد ذكاء اصطناعي مُهيأ مسبقًا وذو نطاق ضيق، يمكن لـ Claude Code (أو مجموعة أدوات Claude Agent SDK) تفويض المهام إليه. كل وكيل فرعي:

  • لديه اسم فريد ووصف واضح للغرض.
  • يعمل في نافذة السياق الخاصة منفصلة عن المحادثة الرئيسية (حتى لا تلوث سلاسل التفاصيل الطويلة سياق المنسق).
  • يمكن تكوينه بمجموعة محدودة من أدوات (قراءة/كتابة الملفات، bash، grep، أدوات MCP، وما إلى ذلك)، مع اختيار نموذج محدد.
  • يحتوي على موجه النظام (شخصية العميل الفرعي والتعليمات) الذي يوجه السلوك والقيود.

تجعل هذه الخصائص الوكلاء الفرعيين مثاليين للمهام التي تعتمد بشكل كبير على الرموز (البحث، والبحث في السجلات الكبيرة)، أو الحساسة للأمان (أدوات المسح أو الأدوات المدمرة المحتملة)، أو المتكررة والمحددة جيدًا (التحقق من الأسلوب، وتشغيل الاختبار).

لقد كان Anthropic يتكرر بسرعة: تم إعادة تصميم Claude Code CLI وAgent SDK وتم توسيعهما إلى مجموعة أدوات تطوير البرامج الخاصة بوكيل كلودتم تقديم دعم المكونات الإضافية لوكلاء التجميع والتخصيصات ذات الصلة (أوامر slash، وخوادم MCP، والخطافات)، و مهاراتي توفير طريقة لتجميع سير عمل النطاق لإعادة الاستخدام عبر Claude.ai وClaude Code ومجموعة أدوات تطوير البرامج للوكيل. تُسهّل هذه التحديثات المشاركة والتثبيت والإصدار الوكلاء الفرعيون عبر الفرق والمشاريع. إذا كنت تخطط لبناء سير عمل إنتاجية، فعليك تقييم حزم الإضافات/المهارات وأنماط النشر القائمة على حزمة تطوير البرامج (SDK).

لماذا تعتبر العوامل الفرعية مهمة

ثلاثة أسباب تجعلها مفيدة على الفور:

  1. الحفاظ على السياق — عمليات البحث الطويلة أو المُشَوَّشة، أو الاختبارات، أو عمليات المسح، تُجرى داخل وكيل فرعي بدلاً من إرهاق السياق الرئيسي. هذا يُقلل من هدر الرموز ويُسهِّل فهم النتائج.
  2. الخبرة المتخصصة - يمكنك ترميز معرفة المجال والسلوك في موجه النظام المخصص للمهمة (على سبيل المثال، security-auditor (التي تركز على الأسرار، وقضايا التبعية، واستخدام shell غير الآمن).
  3. أذونات أكثر أمانًا - يؤدي تحديد الأدوات لكل وكيل فرعي إلى تقليل نصف قطر الانفجار (قد يكون لدى مراجع المستندات أدوات للقراءة فقط؛ وقد يكون لدى مشغل الاختبار أدوات للقراءة فقط) Bash لكن لا Edit).
  4. الموازاة: يمكنك تشغيل العديد من الوكلاء الفرعيين لتشغيلهم في وقت واحد (على سبيل المثال: style-checker, security-scanner, test-runner) ثم جمع نتائجهم المختصرة - وهو فوز كبير لعمليات التحقق المستقلة باهظة الثمن.

المتطلبات الأساسية لاستخدام العوامل الفرعية في Claude Code

قبل البدء في بناء الوكلاء الفرعيين، تأكد من توفر العناصر التالية:

1) تم تثبيت Claude Code والمصادقة عليه

قم بتثبيت Claude Code CLI أو استخدم تكاملات الويب/IDE. مستندات البدء السريع والإعداد لـ CometAPI قم بإدراج طرق التثبيت المدعومة (حزمة npm العالمية أو المثبتات الأصلية) وإظهار كيفية التحقق من التثبيت باستخدام claude --version / claude doctor. ستحتاج أيضًا إلى أ كوميت ايه بي اي (يعتبر استخدام مفتاح CometAPI للوصول إلى كود Claude أرخص وأكثر ملاءمة من النموذج الرسمي.) كما هو موضح في Quickstart.

2) العقدة/البيئة (لبعض مسارات التثبيت) وأدوات shell الأساسية

إذا ثبّتتَ عبر حزمة npm، فيجب أن يكون لديك Node.js (Node 18+ شائع في الأمثلة). إذا كنت تنوي استخدام حزمة تطوير البرامج للوكيل (JavaScript/TypeScript أو Python)، فستحتاج إلى مشروع مُثبّت عليه تبعية حزمة التطوير. تفترض العديد من الدروس التعليمية استخدام أدوات المطور القياسية (git، bash، اختياري). gh (CLI لسير عمل GitHub).

3) تخطيط المشروع و CLAUDE.md

أفضل ممارسة هي الاحتفاظ بوثائق المساعدة على مستوى المستودع (CLAUDE.md) ووضع وكلاء نطاق المشروع في .claude/agents/ لذا يرثها زملاء الفريق. تُسحب ملفات CLAUDE.md إلى سياق Claude تلقائيًا، وتساعد في توجيه السلوك باستمرار عبر الجلسات. كل وكيل فرعي هو ملف Markdown مع واجهة YAML. مثال بسيط:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.

Return results in JSON with fields: summary, issues.
  • name هو معرف بأحرف صغيرة.
  • description يرشد الاستدعاء التلقائي والمطابقة.
  • tools يقيد الوصول إلى الأداة (يتجنب وراثة كل شيء).
  • model يمكن أن يكون sonnet, opus, haiku أو inherit.

4) الأذونات وخوادم MCP (اختياري ولكن شائع)

إذا كانت سير عملك تستخدم خوادم بروتوكول سياق النموذج (MCP) أو أدوات خارجية (مثل Puppeteer وSentry وأدوات REST مخصصة)، فتأكد من تهيئة خوادم MCP وإمكانية الوصول إليها. بالنسبة للعمليات الحساسة (مثل الكتابة، والتعديلات على bash، وgit commit)، انتبه جيدًا لقائمة السماح والمعاملات لكل وكيل. tools تحديد النطاق.

كيفية إنشاء وكلاء فرعيين في Claude Code

يمكنك إنشاء وكلاء فرعيين بثلاث طرق رئيسية: عبر واجهة سطر الأوامر التفاعلية (/agentsكملفات ترميز نظام الملفات، أو برمجيًا عبر حزمة تطوير برامج الوكيل. فيما يلي الخيارات خطوة بخطوة:

يدعم Claude Code ثلاث طرق عملية لإنشاء وكلاء فرعيين:

  1. تفاعلي CLI /agents UI - الأسرع لإنشاء تكراري داخل جلسة.
  2. يعتمد على نظام الملفات — إنشاء ملفات Markdown باستخدام YAML frontmatter في .claude/agents/ (على مستوى المشروع) أو ~/.claude/agents/ (على مستوى المستخدم). يتمتع وكلاء المشروع بأولوية أعلى.
  3. برمجيًا (مجموعة أدوات تطوير البرامج للوكيل) - قم بتعريف الوكلاء الفرعيين في الكود عبر agents المعلمة عند الاتصال query()يُنصح به للتطبيقات التي تعتمد على SDK. يُعد هذا النهج مثاليًا عند الحاجة إلى إنشاء وكلاء فرعيين ديناميكيًا أو تضمينهم في تطبيق.

تدفق تفاعلي سريع (الخطوة الأولى الموصى بها)

  1. ابدأ تشغيل Claude Code في محطتك الطرفية أو افتح لوحة الأوامر في VS Code.
  2. قم بتشغيل واجهة الوكلاء الفرعيين باستخدام الأمر المائل:
/agents
  1. اختار إنشاء وكيل جديداختر نطاقًا على مستوى المشروع أو مستوى المستخدم، وأدخل الاسم/الوصف/الأدوات/مطالبة النظام، ثم احفظ. يمكنك إنشاء مسودة باستخدام كلود ثم تحسينها. بعد الحفظ، يصبح الوكيل متاحًا في /agents ويمكن استدعاؤها صراحةً أو تلقائيًا.

وكلاء فرعيون يعتمدون على نظام الملفات (Markdown + YAML frontmatter)

تُخزَّن العناصر الفرعية كملفات Markdown مع YAML frontmatter. ضعها في:

  • نطاق المشروع: .claude/agents/*.md (أعلى أولوية)
  • نطاق المستخدم: ~/.claude/agents/*.md

هيكل الملف الأساسي:

---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash  # optional; omit to inherit

model: sonnet  # optional; or 'inherit'

---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet

بعض ملاحظات التنفيذ:

  • name يجب أن تكون الأحرف صغيرة مع الواصلات.
  • إغفال tools سيسمح للوكيل الفرعي بتوارث جميع أدوات الخيط الرئيسي؛ حيث يؤدي إدراج الأدوات بشكل صريح إلى فرض نموذج الحد الأدنى من الامتيازات.
  • استعمل model: 'inherit' للحصول على سلوك متسق مع الخيط الرئيسي، أو تحديد اسم مستعار للنموذج (على سبيل المثال، sonnet, opus, haiku).

تعريف CLI JSON (استخدام خاص/جلسة)

يمكنك تحديد وكلاء فرعيين مؤقتين بشكل مضمن عند تشغيل جلسة:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer. Focus on security and best practices.",
    "tools": ,
    "model": "sonnet"
  }
}'

تُعد الوكلاء المُعرفون بواسطة واجهة سطر الأوامر (CLI) مفيدين في عمليات التشغيل النصية أو التجارب؛ حيث يتمتعون بأولوية أقل من وكلاء المشروع ولكن أعلى من وكلاء المستخدم.

التعريف البرمجي (مجموعة أدوات تطوير البرامج للوكيل — الموصى بها للتطبيقات)

إذا كنت تقوم ببناء تطبيق أو أتمتة، فقم بتحديد الوكلاء الفرعيين برمجيًا عبر مجموعة أدوات تطوير البرامج الخاصة بالوكيل agents المعلمة (هذا هو الخيار الأكثر تكاملاً). مثال (TypeScript):

import { query } from '@anthropic-ai/claude-agent-sdk';

async function runReview() {
  const result = await query({
    prompt: "Assess the authentication module for security issues",
    options: {
      agents: {
        "code-reviewer": {
          description: "Expert code review specialist",
          prompt: `You are a code review specialist...`,
          tools: ,
          model: "sonnet"
        },
        "test-runner": {
          description: "Runs the test suite and analyzes failures",
          prompt: `You run tests and summarize failures...`,
          tools: ,
          model: "sonnet"
        }
      }
    }
  });

  console.log(result);
}

تقبل مجموعة أدوات تطوير البرامج أيضًا وكلاء يعتمدون على نظام الملفات (سيتم تحميلها .claude/agents/ الملفات) إذا كنت تفضل هذا النمط. تُعد الوكلاء البرمجيون فعالين في سير العمل الديناميكي وتكامل CI.

بالنسبة لبايثون، claude-agent-sdk تدعم الحزمة أنماطًا مماثلة: يمكنك استخدام query() or ClaudeSDKClient وتكوين الخيارات والأدوات وخوادم MCP برمجيًا. راجع مستودع Python SDK للحصول على نماذج للبدء السريع.

كيفية استدعاء الوكلاء الفرعيين

التفويض التلقائي

كلود كود يستطيع تلقائيا اختر وكيلًا فرعيًا عندما يتوافق مُوجّه المستخدم مع غرضه. يُعدّ هذا مفيدًا للتنسيق الخلفي، حيث يُوجّه الوكيل الرئيسي المهام إلى المختص المناسب تلقائيًا. اعتمد على أوصاف واضحة للوكلاء الفرعيين ومُوجّهات نظام مُركّزة لتحسين دقة الاختيار التلقائي.

الاستدعاء الصريح (موصى به من أجل الوضوح)

يمكنك استدعاء وكيل صراحةً في المحادثة:

> Use the code-reviewer subagent to check my recent changes

يعد الاستدعاء الصريح أمرًا حتميًا ويوصى به لتدفقات الإنتاج حيث تريد تجنب التفويض غير المتوقع.

أنماط منظم SDK

الأنماط الشائعة في تطبيقات SDK:

  • شوكة + جمع:قم بتشغيل العديد من الوكلاء الفرعيين بالتوازي، وجمع إجابة موجزة لكل وكيل، ثم قم بتلخيص/دمج النتائج في الوكيل الرئيسي.
  • حلقة المشرف:يقوم المنظم بتعيين المهام للوكلاء الفرعيين، وفحص النتائج، ثم قبولها أو طلب إعادة الحساب/التوضيح.
  • تنفيذ معزول:إعطاء قدرات خطيرة محتملة (نشر، تشغيل البرامج النصية) إلى وكيل مقيد بشدة ويتطلب موافقة بشرية صريحة قبل التنفيذ.

تتوافق هذه الأنماط مع التنفيذات العملية باستخدام إدارة الجلسة وأدوات MCP وHooks الخاصة بـ Agent SDK.

كيفية إنشاء وكلاء فرعيين مفيدين وآمنين وقابلين للتكوين

1) مسؤولية واحدة وتوجيهات واضحة

يجب أن يكون لكل وكيل فرعي غرض واضح وموجه نظام يحدد الحدود ومعايير النجاح وتنسيق المخرجات. إذا كان المخرج المطلوب مُهيكلًا (JSON، قائمة نقطية، تصحيح برمجي)، فأعطِ الوكيل الفرعي تعليمات دقيقة لتقليل أخطاء التحليل.

2) أقل امتياز للأدوات

امنح فقط الأدوات التي يحتاجها الوكيل الفرعي. على سبيل المثال، لا يحتاج مُراجع المستندات إلى Write or Bash. اجعل الإعداد الافتراضي للقراءة فقط عند الإمكان، وقم بتصعيد أذونات الأداة صراحةً عند الحاجة. هذا يقلل المخاطر ويُبسّط عملية التدقيق.

3) إرجاع مخرجات مضغوطة ومنظمة

ينبغي على الوكلاء الفرعيين العودة إجابات موجزة ونهائية بدلاً من تتبع الأفكار طويلة الأمد. النمط الشائع هو: القيام بعمل مكثف ضمن سياق الوكيل الفرعي، ثم إرسال ملخص قصير مع المرفقات (التصحيحات، مراجع الملفات، JSON). هذا يُعزز كفاءة السياق للمنسق.

4) إمكانية الاختبار والإصدارات

خزّن ملفات الوكلاء الفرعيين في نظام التحكم بالإصدارات، وأنشئ اختبارات تكامل مستمر تُجري عمليات تشغيل حقيقية على مُدخلات صغيرة، وثبت النماذج/مجموعات الأدوات. إذا كنت تعتمد على المهارات والمكونات الإضافية، فاستخدم سوق المكونات الإضافية/أنماط إصداراتها لإدارة الترقيات والتراجعات.

5) خطافات التدقيق ونقاط التفتيش البشرية في الحلقة

استخدم خطافات SDK لاعتراض استدعاءات الأدوات (خطافات PreToolUse) واطلب موافقة المستخدم على الإجراءات التدميرية. سجّل جميع استدعاءات الأدوات لإجراء عمليات تدقيق قابلة للتكرار. توفر SDK آلية خطافات وأذونات لدعم هذا النمط.

عينة تطبيق - خط أنابيب صغير يشبه خط الإنتاج

فيما يلي مثال مضغوط يوضح الأجزاء النموذجية: وكيل نظام الملفات، واستدعاء SDK الذي يستخدم وكيلين (واحد للمراجعة، وواحد للاختبارات)، وتنسيق بسيط.

1) وكيل نظام الملفات: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
  "summary": "one-line summary",
  "issues": ,
  "recommended_changes": 
}

2) التنسيق البرمجي (Node.js)

import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';

async function runPipeline() {
  const result = query({
    prompt: 'Run PR checks: security review then unit tests.',
    options: {
      agents: {
        'code-reviewer': {
          description: 'Use PROACTIVELY after code changes; output JSON with issues.',
          prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
          tools: ,
          model: 'sonnet'
        },
        'test-runner': {
          description: 'Run test suite and summarize failing tests.',
          prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
          tools: 
        }
      }
    }
  });

  for await (const message of result) {
    // Implement streaming logic: messages may include subagent outputs
    console.log(message);
  }
}

runPipeline().catch(console.error);

ملاحظة: القادم code-reviewer يتم تخزينها في المستودع لإعادة استخدامها من قبل الفريق؛ توضح مكالمة SDK أن الوكلاء البرمجيين يأخذون الأولوية و tools يمنع تحديد النطاق الكتابة غير المقصودة.

المواضيع والأنماط المتقدمة

تكوين الوكيل الديناميكي

إنشاء مصانع وكلاء ذات معلمات تختار النموذج ومجموعات الأدوات حسب البيئة (التطوير مقابل الإنتاج) أو مستويات الخطورة (على سبيل المثال، strict vs balanced تُظهر أمثلة SDK كيفية إنشاء تعريفات الوكيل في وقت التشغيل.

التوازي

فصل عدة وكلاء تحليل للقراءة فقط بالتوازي (الأسلوب، الأمان، تغطية الاختبار) وتجميع مخرجات JSON الخاصة بهم في السلسلة الرئيسية. هذا يُقلل بشكل كبير من وقت العمل في المستودعات الكبيرة.

الوكلاء المزودون بالمكون الإضافي

يمكن للمكونات الإضافية توفير وكلاء فرعيين مجمعين مع بيان المكون الإضافي؛ حيث يظهرون في /agents إلى جانب الوكلاء المخصصين، ويمكن استدعاؤهم صراحةً. استخدم هذا لتوزيع الوكلاء الموحدين على الفرق.

أين يُنصح باستخدام Claude code cli؟

يسعدنا أن نعلن أن CometAPI يدعم الآن واجهة سطر الأوامر القوية Claude Code بشكل كامل. كل ما عليك فعله هو تثبيت Claude Code والمصادقة باستخدام مفتاح Comet API وعنوان الأساس الذي تم الحصول عليه لاستخدام نموذج Comet API على Claude Code.

لماذا استخدام كود كلود من خلال CometAPI؟

أهم ميزات الذكاء الاصطناعي: إنشاء التعليمات البرمجية وتصحيح أخطائها وتحسينها بسهولة باستخدام النماذج المصممة خصيصًا للمطورين.

  • اختيار النموذج المرن: تتيح لك مجموعتنا الشاملة من النماذج التطوير بشكل أكثر سلاسة.
  • تكامل سلس: واجهات برمجة التطبيقات (APIs) متاحة دائمًا. تكامل Claude Code مباشرةً مع سير عملك الحالي في دقائق.
  • سيؤدي استخدام Claude Code عبر CometAPI إلى توفير المزيد من التكاليفيقدم Claude API المقدم من CometAPI خصمًا بنسبة 20% من السعر الرسمي ويتم تحديثه بالطراز الأحدث من قبل المسؤول.

هل أنت مستعد لاستخدام Claude Code cli؟ راجع دليل واجهة برمجة التطبيقات للحصول على تعليمات مفصلة.

إذا كنت تريد معرفة المزيد من النصائح والإرشادات والأخبار حول الذكاء الاصطناعي، فتابعنا على VK, X و ديسكورد!

انظر أيضا كيفية تثبيت وتشغيل Claude Code عبر CometAPI؟

الأفكار النهائية

تعامل مع العوامل الفرعية على أنها شخصيات مصغرة قابلة لإعادة الاستخدام ومُنسَّقة. ابدأ صغيرًا: اصنع doc-reviewer و test-runner بالنسبة للمستودع، تحقق منها .claude/agents/وأتمتتها في CI باستخدام headless claude -pكرر مطالباتك وأضف مخرجات منظمة وشدد أذونات الأدوات.

النموذج الذهني الأنسب: تخيّل كلود مدير مشروع، والوكلاء الفرعيين متخصصين في الفريق. يُفوّض المدير مهامًا واضحة الصياغة، ويُجمّع مخرجات المتخصصين، ويكتب التقرير النهائي. مع مرور الوقت، ستلاحظ تحسّنًا في الموثوقية وقابلية الاختبار، وقدرة على أتمتة أجزاء كبيرة من سير عمل المطورين.

اقرأ المزيد

500+ نموذج في واجهة برمجة تطبيقات واحدة

خصم يصل إلى 20%