بناء أتمتة فعالة للوكلاء

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

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

احصل على الكود

التنفيذ المرجعي هو هنا. للحصول على شرح تفاعلي، شغّل الأمر أدناه في Claude Code. The claude-api يمكن لهذه المهارة أن تساعد في إعداد الوكيل وفقًا للإرشادات الواردة في هذه المقالة:

/claude-api managed-agents-onboard https://claude.dev/blog/building-effective-agent-automations/

بالنسبة إلى هذا التنفيذ المرجعي، تحتاج إلى تطبيق Slack (أنشئه من ملف manifest) و رمز GitHub. الملفات المقدمة (المعروضة أدناه) هي إعدادات موارد واجهة برمجة التطبيقات Claude API، بما في ذلك الوكيل وبيئته ومخازن الذاكرة والخزنة والنشر.

daily-brief/
├── agent.md                        model, tools, instructions
├── deployment.md                   schedule, time zone, budget, input message
├── environment.yaml                network allowlist
├── memory_store_preferences.yaml   user preferences
├── memory_store_state.yaml         the agent's bookmarks, ledger, notes, and run records
├── vault.yaml                      the vault that holds the credentials
├── claude-lock.json                resource IDs, written by ant apply
└── slack/manifest.yaml             one bot app

ant apply، وهو أمر في واجهة ant CLI، يقرأ هذه الملفات، وينشئ الموارد في مساحة عمل Claude API الخاصة بك (حيث تخزن المنصة هذه الموارد وتشغّلها)، ويسجّل المعرّفات في claude-lock.json.

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

نظرة عامة

الوكيل الذي سنبنيه يتكوّن من ستة مكوّنات، سنغطيها بهذا الترتيب:

• المصادر - قائمة مسماة بالأماكن للقراءة
• الوجهة - مكان واحد يمكن للوكيل الكتابة فيه
• Agent - النموذج والأدوات وخطوات التشغيل في agent.md
• Schedule - جدول زمني لـ cron
• الذاكرة - تفضيلاتك وذاكرة الوكيل الخاصة
• ضمانات الحماية - وصول للقراءة فقط أينما كان الوكيل يقرأ فقط، وسقف إنفاق لكل تشغيل

المصادر

يقرأ الوكيل مصدرين افتراضيين: قنوات Slack وطلبات السحب في GitHub. القنوات والمستودعات مدرجة في preferences ملف. يمكن توسيع القالب لاستخدام مصادر أخرى.

امنح الوكيل بيانات اعتماد خاصة به محدودة النطاق

مع Managed Agents، توجد بيانات الاعتماد داخل خزائن (vaults). يمكن للوكيل الإشارة إلى بيانات الاعتماد هذه لكن القيم الحقيقية تبقى في الخزينة، خارج بيئة العمل المعزولة حيث يعمل كود Claude (انظر هنا و هنا):

• خوادم MCP (GitHub). يستدعي الوكيل أدوات MCP عبر وكيل وسيط (proxy) يعمل خارج بيئة العمل المعزولة. يجد الوسيط بيانات اعتماد الخزينة التي يتطابق عنوان URL الخاص بها مع عنوان الخادم.

• الصدفة (shell) (Slack). يستدعي الوكيل واجهة Slack API باستخدام curl عبر أداة bash داخل بيئة العمل المعزولة. لا تحتوي البيئة المعزولة سوى على عنصر نائب غير قابل للقراءة، $SLACK_BOT_TOKEN. وعند مغادرة الطلب للبيئة المعزولة، يستبدل النظام الرمز الحقيقي للمضيفين الذين تسمح بهم.

أنشئ الخزينة باستخدام ant CLI وملف القالب في المستودع:

ant apply vault.yaml

يؤدي هذا إلى إنشاء الخزينة في مساحة عمل Claude API الخاصة بك، حيث يخزنها النظام، ويسجل معرّفها في claude-lock.json. ثم أضف كل بيانة اعتماد إلى الخزينة باستخدام TypeScript SDK. فيما يلي مثال يوضح إضافة بيانات اعتماد Slack:

const vaultId = process.env.VAULT_ID!; // the vault's ID, from claude-lock.json

await client.beta.vaults.credentials.create(vaultId, {
  display_name: "SLACK_BOT_TOKEN",
  auth: {
    type: "environment_variable",
    secret_name: "SLACK_BOT_TOKEN",
    secret_value: process.env.SLACK_BOT_TOKEN!,
    networking: { type: "limited", allowed_hosts: ["slack.com"] },
    injection_location: { header: true },
  },
});

بعد إنشاء الخزينة وإضافة كل بيانة اعتماد، اربط الخزينة بالنشر. انسخ معرّف الخزينة من claude-lock.json إلى vault_ids في ملف النشر، deployment.md.

اقرأ من حيث توقفت

الخطأ الشائع هو مطالبة الوكيل بقراءة نافذة ثابتة مثل "آخر 24 ساعة." فالتشغيل المتأخر يترك فجوة والتشغيل المبكر يكرر العناصر. بدلاً من ذلك، امنح الوكيل إشارة مرجعية لكل مصدر. في نهاية كل تشغيل، يكتب الوكيل الطابع الزمني لأحدث عنصر قرأه من كل مصدر في ملف واحد bookmarks.json، مع إدخال لكل مصدر: "slack": "2026-09-14T13:02:11Z".

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

لا تخلط بين فشل القراءة ويوم هادئ

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

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

DESTINATION

قالبنا ينشر في قناة Slack واحدة، مع منشور مؤرّخ في كل مرة يعمل فيها.

ينشر الوكيل في Slack باستخدام أداة bash في بيئة sandbox الخاصة به، مستخدماً نفس الرمز المميز للبوت الذي يقرأ به.

لا شيء يضطر إلى الموافقة على المنشور. يرسله الوكيل بأمر bash، وأداة bash المدمجة تعمل دون طلب موافقة افتراضياً. slack.com مدرجة أيضاً في القائمة المسموحة لـ البيئةالخاصة بالوكيل، أي بيئة sandbox التي يعمل فيها. المنشور طلب واحد:

curl -s https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"channel": "C0123456789", "text": "Daily brief, Tue Sep 15 ..."}'

أكّد وصول المنشور قبل تسجيله

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

ثلاث قواعد في agent.md تمنع ذلك. أولاً، يبحث الوكيل عن عنوان اليوم في الرسائل الأخيرة للقناة ولا ينشر إذا كانت النسخة موجودة هناك بالفعل. ثانياً، لا يُعد المنشور مُرسَلاً إلا إذا أعاد Slack "ok": true وطابعاً زمنياً للرسالة ts. ثالثاً، لا يحدّث الوكيل السجل والإشارات المرجعية إلا بعد ذلك التأكيد. إذا كانت النتيجة غير واضحة، يعلّم التشغيل بـ"ربما نُشر" ولا يغيّر شيئاً آخر، فلا يُفقد شيء.

يحتفظ الوكيل بسجل تشغيل في مخزن ذاكرته (runs/<date>.md). يعلّم التشغيل بـ"جارٍ النشر" قبل المنشور، ثم "نُشر" مع معرّف الرسالة، أو "ربما نُشر".

AGENT

في Claude Managed Agents، وكيل agent هو تكوين مُدار بالإصدارات: نموذج، وموجّه نظام (system prompt)، وأدوات. كل تشغيل يتبع خطوات تشغيله ثم يتوقف.

في تطبيقنا المرجعي، يكون تكوين الوكيل agent.md:

---
name: Daily brief
model: claude-sonnet-5-5
mcp_servers:
  - type: url
    name: github
    url: https://api.githubcopilot.com/mcp/
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_search
        enabled: false
      - name: web_fetch
        enabled: false
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
---

[Eight numbered run steps; the full text is in agent.md in the repo.]

يوفر الجزء الأمامي (frontmatter) اسم الوكيل والنموذج والأدوات وخوادم MCP. أما متن الملف فيقدم تعليمات الوكيل. أدوات MCP تطلب الموافقة افتراضيًا ولا يوجد أحد ليمنحها، لذا تُضبط مجموعة أدوات GitHub على always_allow ويكون رمز GitHub المميز (token) هو read-only.

اجعل الملخص قصيرًا

agent.md يوجّه Claude نحو الإيجاز:

4. Decide. An item earns a line when the reader would act on it today, or it changes a decision they are about to make. When unsure, leave it out. Most days that is a few items, sometimes none. A count ("12 open reviews") is not an item; link the ones that are blocked. An item already in the ledger and still open is carried as one marked line ("still waiting, day 3"), not re-reported; a closed item is dropped without comment. Do not bring back a topic the preferences file has retired.

أعد التحقق من أي شيء ما زال مفتوحًا قبل النشر مباشرة

قد تتغير العناصر بين لحظة قراءة الوكيل للمصادر ولحظة نشره. قبل النشر مباشرة، agent.md يوجّه الوكيل إلى إعادة التحقق من الحالة الفعلية لكل عنصر:

5. Verify. The world moved while you read. For every item you will report, re-check its live source just before posting: resolved since you read it, drop it; still open but changed, fix the line; cannot confirm, drop it and list it in the run record's cuts. One stale "still waiting on you" costs more trust than ten missing items, so never hedge an item's status: assert it or drop it. Every link is copied from the source's own link field (a pull request's html_url, a Slack permalink), never assembled by hand.

SCHEDULE

مع Claude Managed Agents، يكون الوكيل مجرد ملف تكوين؛ ووحدة deployment هي التي تشغّله. تحدد وحدة النشر اسم الوكيل والبيئة والرسالة الأولى لكل تشغيل، كما تحتوي على الجدول الزمني والخزنة ومخازن الذاكرة والميزانية. في كل مرة يعمل فيها الجدول الزمني، تبدأ المنصة جلسة session.

جديدة للوكيل. في قالبنا، تُحفظ وحدة النشر في deployment.md، مع الرسالة الأولى كمتن لها:

---
name: Daily brief
agent: ./agent.md
environment_id: ./environment.yaml
schedule:
  type: cron
  expression: "32 7 * * 1-5"
  timezone: America/New_York
vault_ids: [vlt_...]   # the vault you create under Sources
resources:
  - path: ./memory_store_preferences.yaml
    access: read_only
    instructions: The reader's preferences. Re-read them every run. Never write here.
  - path: ./memory_store_state.yaml
    access: read_write
    instructions: Your state. Bookmarks, ledger, notes, proposals, and run records.

---

Write today's brief.
The reader's time zone is America/New_York. Work out every date in that zone.

Follow your run steps in order. Today's edition is titled "Daily brief, <weekday> <month> <day>".

هذا ينشئ وحدة النشر بالوكيل والبيئة ومخازن الذاكرة التي تسمّيها حسب المسار.

ant apply deployment.md

ولاختباره دون انتظار الجدول الزمني، ابدأ تشغيلًا يدويًا باستخدام ant beta:deployments run --deployment-id <id>، مع استخدام المعرّف من claude-lock.json.

احسب التواريخ في منطقتك الزمنية

خطأ شائع هو أن الوكيل يسمي صباح اليوم "أمس" لأنه يحسب التواريخ وفق المنطقة الزمنية للخادم. في deployment.md, timezone تُضبط مجموعة الحقول عند تشغيل التنفيذ، ويخبر السطر الثاني من المتن الوكيل بالمنطقة الزمنية التي يجب استخدامها للتواريخ.

الذاكرة

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

يحتفظ قالبنا باثنين ذاكرة التخزين`، والمجلدات المُحمَّلة تحت /mnt/memory/ (انظر المصادر):`

• التفضيلات (خاصة بك، للقراءة فقط بالنسبة للوكيل): أي قنوات ومستودعات يقرأ، ما يتركه جانباً، الحد الأقصى للطول، الوجهة، ومتى يتوقف.

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

ant apply deployment.md ينشئ مخزن التفضيلات، لكن ليس الملف بداخله. قبل أول تشغيل، اكتب ملف preferences.md الخاص بك هناك باستخدام scripts/seed-preferences.sh.

أعد قراءة تفضيلاتك في بداية كل تشغيل

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

احتفظ بسجل لما أبلغت عنه بالفعل، وأبلغ عن التغيير

يحتفظ الوكيل بسجل، ledger.mdلكل عنصر أبلغ عنه، حتى لا يكرر نفسه الملخص. يسجل كل سطر متى تم الإبلاغ عن العنصر، ومن أين جاء، ومعرفاً لا يتغير (طابع زمني لرسالة Slack أو رقم طلب سحب)، وآخر حالة معروفة له:

2026-09-09 slack:C0123456789 1788963600.000100 refund thread: customer waiting on a decision
2026-09-11 github 481 review blocked, day 2 (still waiting)
2026-09-11 slack:C0234567891 1789117333.000300 enterprise escalation: owner named, in progress

ضوابط الحماية

بما أن الأتمتة لدينا تعمل في "الخلفية" وفق جدول زمني، وضعنا حدوداً على ما يمكن للوكيل فعله وعلى ما يمكنه إنفاقه.

حدود على ما يمكنه فعله

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

Slack هو الاستثناء: الرمز نفسه ينشر، لذا ادعُ الروبوت فقط حيث يحتاج إلى القراءة أو النشر.

حدّد سقف الإنفاق من تشغيلات حقيقية

يحميك سقف الإنفاق من التكاليف الجامحة. ابدأ بثلاثة إلى خمسة أضعاف تكلفة التشغيل العادي، ثم شدّده عندما ترى أرقاماً حقيقية. التشغيل الذي يصل إلى سقفه يتوقف مؤقتاً بدلاً من أن يفشل، لذا فإن السقف المنخفض جداً يبدو وكأنه ملخص صمت. السقف هو budget في deployment.md. يحصل كل تشغيل على المبلغ الكامل، والتشغيل الذي يصل إليه يتوقف مؤقتاً بسبب budget_reached إيقاف:

budget:
  type: limit
  max_list_cost:
    amount: "500" # a string, in cents: "500" is $5.00
    currency: USD

البدء

تتلخص التنفيذية المرجعية لدينا في ست قواعد:

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

يمكن لـ Claude Code أن يرشدك خلال الإرشادات الواردة في هذا المقال. أولًا، قم بالتحديث:

claude update

ثم، استخدم مهارة claude-api:

/claude-api managed-agents-onboard https://claude.dev/blog/building-effective-agent-automations/

تقرأ مهارة claude-api هذا المنشور، وتقترح إعدادًا، وتكتب الملفات إلى مجلد agents/ في مشروعك، وتنشئ الموارد باستخدام ant apply. تعامل مع هذا كنقطة بداية، وخصّص الوكيل وفق مصادرك أو وجهتك أو تفضيلاتك للذاكرة.