وكلاء Claude المدارون: دليل تطبيقي (2026)

في 3 سبتمبر 2026، حصلت أداة سطر الأوامر ant من Anthropic على أمر فرعي جديد: ant apply. يقوم هذا الأمر بقراءة تعريفات العميل (agent)، والبيئة (environment)، والمهارة (skill)، ومخزن الذاكرة (memory store)، وتعريفات النشر (deployment) من ملفات في مستودعك ومزامنتها مع Claude API — وهو نفس سير عمل "التخطيط ثم التنفيذ" (plan-then-apply) الذي جعلته Terraform معياراً للبنية التحتية السحابية، ولكن هذه المرة موجه نحو موارد Claude Managed Agents بدلاً من الخوادم¹².

ملخص

يقوم الأمر ant apply <path> بإنشاء أو تحديث موارد Claude Managed Agents من ملفات Markdown أو YAML أو JSON، ويعرض لك خطة عمل، ثم يكتب ملف claude-lock.json عند الموافقة لضمان أن التشغيل التالي سيحدث نفس الموارد بدلاً من تكرارها. يتطلب الأمر إصدار CLI 1.30.0 أو أحدث، والذي تم إصداره في 3 سبتمبر 2026، ويعمل في بيئة CI باستخدام --yes أو --dry-run¹².

ما ستتعلمه

• كيفية التصريح عن Claude Managed Agent، وبيئة، ومخزن ذاكرة، ونشر مجدول كملفات في مستودع واحد، وتحويلها إلى موارد API حقيقية باستخدام ant apply
• كيف يحدد ant apply نوع الملف من خلال مساره، والطريقتين المختلفتين اللتين يتم بهما معاقبة الملف ذو الاسم الخاطئ — إحداهما بصمت، والأخرى بخطأ صريح
• ماذا يوجد داخل claude-lock.json، ولماذا يجب عليك رفعه (commit) بدلاً من تجاهله
• مشكلتان خفيتان في إرشادات CI الخاصة بـ Anthropic قد تؤديان بصمت إلى تعطل إعداد GitHub Actions المنسوخ
• كيفية مصادقة وظيفة CI مقابل Claude API باستخدام Workload Identity Federation بدلاً من مفتاح مخزن
• ما هي المعايير التي تم التحقق من أمثلة ملفات هذا البرنامج التعليمي بناءً عليها، نظراً لعدم توفر مفتاح API حي لتشغيلها فعلياً

أداتان لسطر الأوامر، يفصل بينهما حرف واحد

أداة ant ليست هي claude. أداة ant CLI هي عميل سطر الأوامر من Anthropic لـ Claude API نفسه — حيث يتم عرض كل مورد من موارد API، بما في ذلك Managed Agents، كأمر فرعي³. أما claude فهي أداة Claude Code CLI المنفصلة للبرمجة المعتمدة على الوكلاء (agentic coding) في الطرفية (terminal).

من المفترض أن تعمل الأداتان معاً. يمكن لـ Claude Code استدعاء ant مباشرة، وتحليل مخرجاته المهيكلة، والتعامل مع موارد API الخاصة بك دون أي كود تكامل مخصص، كما في حالة "سرد جلسات الوكيل الأخيرة وتلخيص الجلسات التي حدث بها خطأ"⁴.

هذا المنشور يتحدث عن ant، وتحديداً الأمر الفرعي apply.

المتطلبات الأساسية

• أداة ant CLI، الإصدار 1.30.0 أو أحدث. يتم التثبيت باستخدام brew install anthropics/tap/ant على macOS، أو مثبت curl الموثق لـ Linux و WSL، أو go install من المصدر³.
• استخدم ant --version للتأكد من أن إصدارك أعلى من 1.30.0. حتى وقت كتابة هذا البرنامج التعليمي، الإصدار الحالي هو 1.33.0 (15 سبتمبر 2026)، ولم يتغير أي شيء بين 1.30.0 و 1.33.0 في سلوك أو أعلام (flags) الأمر apply²⁵.

تطبيق أول عميل (Agent) لك

العميل (Agent) هو مصطلح Anthropic لتكوين قابل لإعادة الاستخدام وله إصدار محدد: يتكون من النموذج، ومطالبة النظام (system prompt)، والأدوات، والمهارات المجمعة معاً والتي يتم الرجوع إليها بواسطة معرف (ID) في كل مرة تبدأ فيها جلسة⁷. اكتب واحداً كملف Markdown تحت agents/، ثم قم بتطبيقه:

ant apply agents/summarizer.md

---
name: Summarizer
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful assistant that writes concise summaries.

تحتوي الـ frontmatter على حقول تكوين العميل — وهي نفس الحقول التي سترسلها إلى نقطة نهاية إنشاء العميل — ويصبح نص الجسم هو مطالبة النظام الخاصة به. يستنتج ant apply أن هذا الملف هو عميل لأنه موجود تحت agents/¹.

في طرفية (terminal) تفاعلية، يقوم ant apply بطباعة خطة وينتظر:

First apply  ./claude-lock.json does not exist yet and will be created

Resources will be created with
  credentials   API key (--api-key / ANTHROPIC_API_KEY)
  host          api.anthropic.com
  organization  1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f
  workspace     wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

Preview  ./claude-lock.json (new)

± Name                    Plan
+ ./agents/summarizer.md  create

Resources  + 1 to create

Apply these changes? (y)es / (n)o / (d)etails y

Apply  ./claude-lock.json

± Name                    Status
+ ./agents/summarizer.md  created    agent_011CYm1BLqPXpQRk5khsSXrs

Resources  + 1 created

State written to ./claude-lock.json

الإجابة بـ d تعرض التفاصيل الكاملة لكل حقل قبل أن تعتمدها. يقوم --dry-run بطباعة نفس الخطة التفصيلية ويخرج دون تغيير أي شيء أو كتابة ملف قفل (lockfile)¹.

ماذا يوجد داخل claude-lock.json

يقوم أول ant apply بكتابة ملف قفل في أي دليل قمت بتشغيله منه — قم بتشغيله من جذر المستودع (repository root). يسجل الملف أي ملف أنشأ أي مورد، وأين:

{
  "version": 1,
  "origin": {
    "base_url": "https://api.anthropic.com",
    "organization_id": "1b0c2a4d-6c1f-4f0e-9a57-2e8d1c3b4a5f",
    "workspace_id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
  },
  "resources": {
    "./agents/summarizer.md": {
      "kind": "agent",
      "id": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "version": "1",
      "hash": "d23251c8d99b3613a64f3f8d87f5fad4",
      "remote_hash": "1b771bee5bdbf600a5ad972fdac32d94"
    }
  }
}

قم بتثبيت (Commit) هذا الملف مع الكود الخاص بك. هذه هي الطريقة التي يجد بها التشغيل التالي — سواء كان تشغيلك أو تشغيل CI — نفس الموارد بدلاً من إنشاء موارد جديدة، وهو المكان الذي تقرأ منه المعرف الحقيقي للمورد بمجرد وجوده. تقوم البصمتان (hashes) بتحديد ما أرسله ملفك مؤخراً وما أعاده الـ API مؤخراً، وهو ما يسمح لتشغيل لاحق بالتمييز بين ملف تم تعديله ومورد قام شخص ما بتغييره خارج هذه الملفات تماماً¹.

تطويره إلى مشروع

توضح وثائق Anthropic ذلك من خلال إعداد مراجع لطلبات السحب (pull-request reviewer). وللحفاظ على هذا الأمر ملموساً وتجنب مجرد إعادة كتابة مثالهم، إليك نفس الآليات المطبقة على مشكلة مختلفة: فريق عملاء صغير يقوم بصياغة وتدقيق حقائق منشورات المدونة وفق جدول زمني — وبالمصادفة، هذا قريب من نوع خط الإنتاج الذي أنتج هذا المنشور. كل حقل أدناه هو حقل حقيقي وموثق؛ السيناريو فقط هو الأصلي.

يتخطى هذا المشروع النوع الخامس، المهارات (skills)، عن قصد: المهارة هي دليل يحتوي على SKILL.md في جذره، ويتم رفعه كحزمة واحدة، وليس ملف YAML أو JSON أو Markdown واحد مثل الأنواع الأربعة الأخرى — وهو مختلف ميكانيكياً بما يكفي ليستحق مثالاً خاصاً به بدلاً من مجرد إدخال رمزي هنا¹.

خمسة ملفات، أربعة أنواع:

agents/fact-checker.md
agents/writer.md
environments/sandbox.yaml
memory_stores/style-notes.yaml
deployments/nightly-draft.md

agents/fact-checker.md — عميل فرعي ليس لديه قائمة مهام خاصة به:

---
name: Fact Checker
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
description: Verifies claims in a draft against live sources before it ships.
---

Check every statistic, date, and named source in the draft you're given.
Flag anything you can't verify instead of guessing at it.

agents/writer.md — المنسق، الذي يفوض المهام إلى مدقق الحقائق عبر مسار نسبي:

---
name: Draft Writer
model:
  id: claude-opus-5
  effort: high
tools:
  - type: agent_toolset_20260401
multiagent:
  type: coordinator
  agents:
    - ./fact-checker.md
---

Draft a technical blog post about agentic AI, then hand the draft to your
fact-checker subagent before you finish.

قائمة multiagent.agents الخاصة بالمنسق هي بالضبط الطريقة التي تدرج بها العملاء الذين يمكنه التفويض إليهم، ويقوم ant apply بحل هذا المسار النسبي إلى المعرف الحقيقي لمدقق الحقائق بمجرد تطبيق كلا الملفين — بترتيب التبعية، بحيث يكون العميل الفرعي موجوداً قبل أن يشير إليه المنسق⁷⁸¹.

environments/sandbox.yaml — الساندبوكس السحابي الذي يعمل فيه كلا العميلين:

name: blog-pipeline-sandbox
config:
  type: cloud
  packages:
    pip:
      - pyyaml
  networking:
    type: limited
    allowed_hosts:
      - api.example-cms.com
    allow_package_managers: true

يعد allow_package_managers: true مطلوباً كلما تم تعيين packages في بيئة شبكة limited؛ حيث يؤدي تركه يؤدي إلى خطأ 400، حتى لو كان المضيف الخاص بسجل الحزم موجوداً في allowed_hosts⁹.

memory_stores/style-notes.yaml — ملاحظات مشتركة بين الجلسات يراجعها الكاتب قبل الصياغة:

name: House Style Notes
description: >-
  Corrections and fact-check findings from past drafts, for the writer
  agent to check before drafting a new one.

وصف description الخاص بمخزن الذاكرة هو ما يقرأه العميل لفهم الغرض من المخزن؛ فهو ليس تعليقاً للبشر¹⁰.

deployments/nightly-draft.md — مشغل cron، المرتبط بمخزن الذاكرة والذي يحمل سقف إنفاق لكل عملية تشغيل:

---
name: Nightly draft run
agent: ../agents/writer.md
environment_id: ../environments/sandbox.yaml
resources:
  - path: ../memory_stores/style-notes.yaml
    access: read_write
schedule:
  type: cron
  expression: "0 6 * * *"
  timezone: UTC
budget:
  type: limit
  max_list_cost:
    amount: "500"
    currency: USD
---

Draft tonight's post and hand it to the fact-checker before you finish.

العمليات المكتوبة بصيغة Markdown تعمل بشكل مختلف عن الأنواع الأخرى: لا يزال الـ frontmatter يحتوي على جسم الطلب، ولكن بدلاً من مصفوفة initial_events منفصلة، يتم استخدام نص Markdown نفسه كرسالة تفتح كل جلسة¹.

تقبل عمليات النشر موارد مخزن الذاكرة، والملفات، و GitHub من خلال نفس مصفوفة resources التي تستخدمها الجلسة، حيث يشير كل إدخال إلى ملف وفقاً لنفس قاعدة المسار النسبي الموضحة أعلاه. يستخدم هذا الإدخال read_write حتى تتمكن جلسة صياغة الكاتب من إضافة تصحيحاتها الخاصة إلى المخزن، وليس مجرد قراءة ما هو موجود بالفعل¹¹¹⁰.

يأخذ حقل budget نفس شكل ميزانية الجلسة ويتم نسخه في كل عملية تشغيل يبدأها النشر، لذا فهو يحدد سقف كل عملية تشغيل على حدة بدلاً من العمل كحد تراكمي عبر عملية النشر بأكملها. سقف "500" هنا يسمح بإنفاق ما يصل إلى حوالي 5 دولارات بتكاليف الأسعار العامة لأي عملية تشغيل ليلية واحدة، وليس 5 دولارات إجمالاً عبر جميع عمليات التشغيل¹¹.

قم بتطبيق المجلد بالكامل في أمر واحد:

ant apply .

يقوم ant apply بإنشاء البيئة، ومخزن الذاكرة، ومدقق الحقائق أولاً — حيث لا يشير أي من هذه الملفات الثلاثة إلى أي شيء آخر — ثم الكاتب، لأن ملفه يشير إلى مدقق الحقائق، وأخيراً عملية النشر، لأنها تشير إلى البيئة ومخزن الذاكرة والكاتب. ينتهي الأمر بـ claude-lock.json بخمسة إدخالات، إدخال واحد لكل ملف.

كيف يعمل استنتاج النوع فعلياً

يحدد ant apply ماهية الملف من خلال التحقق من ثلاثة أشياء، بهذا الترتيب الدقيق، والتوقف عند أول تطابق¹:

1. حقل type في المستوى الأعلى مكتوب مباشرة في الملف.
2. المجلد الذي يوجد فيه الملف: agents/، أو environments/، أو memory_stores/، أو deployments/.
3. اسم ملف يبدأ باسم النوع، مثل environment_staging.md الموجود خارج أي من تلك المجلدات.

ينتج عن هذا الترتيب نمطان من الفشل، ولا يتم التنبيه لأي منهما بشكل واضح. الملف الذي لا يطابق أياً من القواعد الثلاث يُفقد بصمت إذا كان بتنسيق Markdown — حيث تنص الوثائق صراحة على أن "ملف Markdown المسمى الذي لا يطابق أي قاعدة يتم التعامل معه كـ agent". قم بتغيير اسم agents/notes.md إلى docs/notes.md خارج أي دليل معروف ومرره بالاسم في سطر الأوامر، وسيحاول ant apply إنشاءه كـ agent بدلاً من إظهار خطأ.

حالة YAML و JSON هي العكس وأكثر وضوحاً: نفس الموقف لملف .yaml أو .json يؤدي إلى خطأ جسيم بدلاً من تصنيف خاطئ صامت¹. أما الملفات التي لا تطابق أياً من القواعد الثلاث ولم يتم تسميتها صراحة في سطر الأوامر — مثل ملفات README أو إعدادات CI — يتم تخطيها تماماً، وهو الخيار الافتراضي الآمن لكل ما ليس مقصوداً تطبيقه.

كشف الانحراف (Drift detection): عندما يربح الـ Console الجدال

إذا قام شخص ما بتعديل أو أرشفة أو حذف مورد خارج هذه الملفات — في Claude Console على سبيل المثال — فإن عملية ant apply التالية لهذا الملف لا تقوم بمسح التغيير بصمت. تنتهي الخطة بعبارة This plan cannot be applied: مع ذكر السبب المحدد، ثم يخرج الأمر بـ refusing to apply¹.

يقوم --force بمسح التعديل الذي تم خارج النطاق، أو إنشاء مورد بديل إذا تم حذف المورد الأصلي. وفي غياب --force، لا يمكن لـ ant apply تبني مورد موجود بالفعل ولكن لم يتم إنشاؤه من خلال هذه الملفات في المقام الأول — بما في ذلك أي شيء تم إنشاؤه عبر الـ Console أو ant beta:agents create مباشرة.

إذا وجهت ملفاً إلى إعدادات agent موجود بالفعل دون أن يكون هذا الـ agent في ملف القفل (lockfile)، فإن ant apply ينشئ agent ثانياً منفصلاً بدلاً من التعرف على الأول كطابق¹.

خداعان تخفيهما فقرة CI الخاصة بـ Anthropic

كلا هذين الأمر ينبعان مباشرة من قسم "Run ant apply in CI" في وثائق Anthropic — فهما ليسا حالات نادرة تم اكتشافها بالتجربة والخطأ، بل مجرد تفاصيل يسهل تخطيها عند القراءة الأولى¹.

الأمر ant apply --yes المجرد يتخطى الملفات الجديدة بصمت. نمط CI الموثق من Anthropic هو تسمية دليل المشروع دائماً — ant apply --yes . — تحديداً لأن ant apply --yes المجرد بدون وسيط للمسار "يقوم بتسوية الملفات التي يتتبعها ملف القفل بالفعل فقط ويتخطى أي ملف مضاف حديثاً".

أضف ملفاً سادساً إلى مشروع blog-pipeline أعلاه وانسَ تسمية الدليل في مهمة CI الخاصة بك، ولن يتم إنشاء هذا المورد الجديد أبداً — دون أي خطأ، لأن تخطي ملف غير متتبع لا يُعامل كفشل¹.

--dry-run يبلغ عن النجاح حتى عندما يرفض التطبيق الفعلي التنفيذ. خطة --dry-run "تخرج بالكود 0 حتى عندما تكون الخطة محظورة". طلب السحب (pull request) الذي تظهر خطوة --dry-run فيه عبارة This plan cannot be applied: بسبب تعارض في الانحراف لا يزال يجتاز الـ CI، لأن كود الخروج لا يعكس ذلك. قراءة نص الخطة المطبوع — وليس فقط كود الخروج — هي الطريقة الوحيدة التي يكتشف بها فحص الـ PR هذا الأمر قبل أن يقوم شخص ما بدمجه ويرفض التطبيق الفعلي التنفيذ¹.

تشغيله في CI باستخدام Workload Identity Federation

توصية Anthropic الخاصة بـ CI هي تخطي مفاتيح API المخزنة تماماً والمصادقة باستخدام Workload Identity Federation (WIF): حيث يقوم مزود CI الخاص بك بإصدار رمز OIDC قصير المدى، وتقوم Anthropic بالتحقق من صحته مقابل القواعد التي تقوم بتكوينها مرة واحدة في Console، وتستبدله برمز API لـ Claude يكون عادةً صالحاً لدقائق، وليس شهوراً، قبل أن تنتهي صلاحيته⁶¹.

نمط CI الموثق يتكون من ثلاثة أجزاء:

• عند طلبات السحب (pull requests): ant apply --dry-run .، لغرض إعلامي فقط، لإظهار الخطة للمراجعين.
• بعد الدمج في الفرع الافتراضي: ant apply --yes ..
• في نهاية المهمة، قم بعمل commit لملف claude-lock.json المحدث — حتى لو فشلت خطوة apply في منتصف الطريق، لأن الـ apply الجزئي لا يزال يسجل ما تم إنشاؤه بالفعل¹.

بالنسبة لـ GitHub Actions تحديداً، يأتي رمز الهوية من نقطة نهاية Actions OIDC دون وجود أي سر مخزن على الإطلاق. العمر الافتراضي لرمز WIF هو 3,600 ثانية (يمكن تكوينه من 60 إلى 86,400)، ونطاق OAuth الافتراضي الذي يمنحه — workspace:developer — هو نفس مستوى الوصول الخاص بمفتاح API لمساحة العمل⁶.

هناك خطأ شائع موثق ينطبق على أي عملية انتقال إلى WIF، وليس فقط CI: حيث يقع ANTHROPIC_API_KEY فوق طبقات federation في ترتيب حل الاعتمادات لكل SDK، لذا فإن أي مفتاح متبقٍ في البيئة سيفوز بصمت على federation بدلاً من إظهار خطأ. يقوم ant auth status بالإبلاغ عن مصدر الاعتمادات الذي فاز بالفعل⁶.

مرجع الأعلام (Flags)

المصدر: توثيق ant apply الخاص بـ Anthropic، محدث حتى تاريخ هذا المنشور¹.

ant apply مقابل البدائل

هذه مقارنة أصلية، وليست اقتباساً من أي مصدر واحد — كل عمود يعكس ما تم توثيقه مباشرة حول آليات سير العمل الخاصة به.

التحقق

لم يتم التقاط أي من مخرجات الأوامر أو أمثلة الملفات أعلاه من تشغيل حي لـ ant apply على مساحة عمل حقيقية — يتطلب ذلك ANTHROPIC_API_KEY مدفوع أو قاعدة Workload Identity Federation مهيأة ومنظمة Claude موجودة، ولم يكن أي منهما متاحاً أثناء كتابة هذا البرنامج التعليمي. لا ينبغي قراءة أي شيء هنا على أنه جلسة terminal مسجلة.

بدلاً من ذلك، تم التحقق من كل اسم حقل، وعلامة (flag)، وقاعدة تنسيق ملف، وجزء من مخرجات الأوامر مقابل وثائق Anthropic المنشورة لـ ant apply¹، وأدلة البدء السريع وسكربتات ant CLI³⁴، وصفحات المراجع الخاصة بـ agent و multiagent-orchestration و environment و memory store و scheduled-deployment^7891011، ودليل Workload Identity Federation⁶.

تم جلب كل ذلك مباشرة من platform.claude.com، معظمها في 2026-09-17 وأعيد التحقق منها عبر جلب جديد في 2026-09-18 للتأكد من عدم حدوث أي تغيير؛ تم جلب صفحة multiagent-orchestration فقط في المرة الثانية، تحديداً للتأكد بشكل مستقل من هيكل حقل المنسق (coordinator) مقابل مصدر يتجاوز المثال العملي الواحد. لم يتم إعادة بناء أي من ذلك من الذاكرة أو من كتابات ثانوية.

تم التحقق بشكل مستقل من تاريخ إصدار الـ CLI ورقم الإصدار مقابل ملاحظات الإصدار الخاصة بمستودع anthropic-cli GitHub للإصدار v1.30.0 والإصدار الحالي v1.33.0²⁵، والتي أكدت إضافيًا أنه لم يطرأ أي تغيير على أعلام (flags) أو سلوك apply في أي إصدار منذ 1.30.0. أما "الملاحظات الهامة" (gotchas) المذكورة أعلاه فهي اقتباسات مباشرة ومنسوبة لإرشادات CI الخاصة بشركة Anthropic، وليست استنتاجات.

تستخدم ملفات الأمثلة الخمسة في قسم "تطويره إلى مشروع" أسماء حقول تم تأكيدها في صفحات المراجع المذكورة؛ أما السيناريو الذي يربط بينها فهو من ابتكار هذا المنشور، وليس منسوخًا من مثال مراجع الـ PR الخاص بـ Anthropic. كل كتلة YAML و Markdown-frontmatter في هذا المنشور، بما في ذلك ملف JSON الخاص بـ claude-lock.json، تم تحليلها باستخدام محلل YAML/JSON حقيقي (وحدات pyyaml و json في Python) للتأكد من أنها صالحة من الناحية النحوية — وليس مجرد أنها تبدو صحيحة بصريًا.

الخلاصة

يوفر ant apply سير عمل "التخطيط ثم التطبيق" لموارد Claude Managed Agents: قم بوصف وكيل، أو بيئة، أو مخزن ذاكرة، أو عملية نشر كملف، وعاين التغيير بدقة، واترك ملف القفل المُثبت يحافظ على ثبات العمليات (idempotent).

حتى وقت كتابة هذا المنشور، مر عليه حوالي أسبوعين. السلوكان الأكثر احتمالاً للتسبب في مشاكل عند استخدام إعداد منسوخ — وهو استخدام ant apply --yes الذي يتجاهل الملفات الجديدة، واستخدام --dry-run الذي يبلغ عن النجاح حتى لو كانت الخطة محظورة — كلاهما مذكور بوضوح في وثائق Anthropic نفسها، لكن من السهل إغفالهما في القراءة الأولى.

قراءات ذات صلة

• دليل تخزين الذاكرة لـ Claude Managed Agents (2026)
• Claude Managed Agents: الأحلام، النتائج، والتنسيق
• التحكم في تكلفة وكلاء الذكاء الاصطناعي: التحول إلى حدود إنفاق الجلسة في 2026