بني وشغّل وكلاء التسوّق والتجّار مع Claude Commerce Agents

شنو كيوفّر Claude Commerce Agents

Claude Commerce Agents هو تطبيق مرجعي فيه جوج ديال الوكلاء ديال الذكاء الاصطناعي الموجّهين للتجارة، ومبنيين على Claude. تقدر الشركة تدمج وكيل التسوّق فالتطبيق اللي كيتعامل مع الزبناء، وفنفس الوقت يقدرو الموظفين يستعملو وكيل التاجر باش يسيّرو العمليات ديال الإدارة الخلفية.

كل وكيل كيتعرّف مرة وحدة من خلال البرومبت ديالو، والمهارات، وعقود الأدوات، وحواجز السلامة. نفس التعريفات تقدر تخدم عبر Messages API، أو Claude Agent SDK، أو Managed Agents. كاينين أربعة ديال التطبيقات العمودية القابلة للتشغيل كيبينو هاد المعمارية فمجالات البيع بالتقسيط، والسفر، والاتصالات، والترفيه.

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

فهم الدورين ديال الوكلاء

وكيل التسوّق

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

التدفقات الخمسة ديالو كاينة فـ shopping-agent/skills/. باش تستعمل الوكيل مع أنظمة حقيقية، خاص النشر ديالك يطبّق StorefrontBackend فوق خدمات الكتالوج والسلة والطلبات والسياسات المعنية.

وكيل التاجر

وكيل التاجر كيساعد الموظفين يفهمو الأداء، ويحافظو على العروض المنشورة، ويردّو على تنبيهات المخزون والطلبات، ويعدّلو الأثمنة والعروض الترويجية، ويحضّرو مسودات الحملات. التدفقات الخمسة ديالو كاينة فـ merchant-agent/skills/.

النشر كيربطو بأنظمة التحليلات والكتالوج والمخزون والأثمنة والحملات، من خلال تطبيق MerchantBackend. كل تغيير كيتم وضعو فمرحلة الإعداد وما كيتطبّقش فالحين؛ خاص التطبيق المضيف يعرض التغيير المقترح ويوافق عليه.

المعمارية والخصائص الرئيسية

• الأساسات المشتركة: commerce-common/ فيه الإعدادات، والحماية، والذاكرة، ومعالجة المهارات، والإسناد للمصادر، والعرض، والأحداث، وإطار التنفيذ المستعمل من طرف الدورين.
• أوقات تشغيل متعددة: نفس البرومبتات والمهارات وعقود الأدوات خدامة مع Messages API وAgent SDK وManaged Agents.
• تجريد الواجهة الخلفية: أدوات الوكلاء كتنادي على واجهات الواجهة الخلفية، وهاد الشي كيخلّي الخادم ديالك يحتافظ ببيانات الدخول ويتوسّط فالوصول لأنظمة الأعمال.
• تغييرات التاجر المرحلية: تغييرات التاجر خاصها الموافقة من خلال واجهة الموافقة ديال التطبيق المضيف.
• قدرات قابلة للإعداد: الخصائص اللي ما مدعماش تقدر تعطّلها، باش تتحيّد الأدوات ديالها، والأسطر ديال البرومبت، وقواعد الإسناد للمصادر.
• عرض قابل للتوسيع: تقدر تزيد واجهات خاصة بالمجال من خلال PresentationExtension.
• أمثلة قابلة للتشغيل: ثمانية تطبيقات ويب كيوفّرو واجهة متجر وبوابة تاجر لكل واحد من المجالات الأربعة.

المتطلبات المسبقة

ثبّت Python 3.11 أو أحدث وNode.js 22. خاصك حتى مفتاح Anthropic API باش تشغّل التفاعلات الحية مع النموذج.

ثبّت المستودع

نسخ المشروع، وأنشئ بيئة افتراضية ديال Python، وثبّت اعتماديات Python المحددة بالإصدارات، وأنشئ ملف البيئة، وثبّت مساحة العمل المشتركة ديال JavaScript:

git clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
(cd examples && npm ci)

حلّ .env وزيد فيه ANTHROPIC_API_KEY ديالك. خلّي البيئة الافتراضية مفعّلة وانت كتشغّل سكريبتات Python.

شغّل أول عرض تجريبي

بدا متجر البيع بالتقسيط وواجهة API ديالو بهاد الأمر:

python scripts/run_demo.py retail

واجهة API ديال البيع بالتقسيط كتخدم فالبورت 8000، والمتجر كيتشغّل فالبورت 3000. باش تبدا بوابة التاجر بلاصة المتجر، زيد --merchant:

python scripts/run_demo.py retail --merchant

استعمل --all باش تشغّل الواجهتين بجوج:

python scripts/run_demo.py retail --all

المجالات المتاحة وبورتات الويب ديالها هي:

• البيع بالتقسيط: المتجر 3000، بوابة التاجر 3100.
• السفر: المتجر 3001، بوابة التاجر 3101.
• الاتصالات: المتجر 3002، بوابة التاجر 3102.
• الترفيه: المتجر 3003، بوابة التاجر 3103.

كل مجلد ديال مثال فيه README فيه برومبتات مقترحة ووصف ديال شنو خاص يكون فالجواب المزيان.

استكشف المجالات النموذجية

البيع بالتقسيط

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

السفر

ACME Travel كيزيد مخزون مرتبط بالتواريخ وامتداد present_itinerary. فالجانب ديال التاجر كاين تقويم للإشغال وتغييرات فالأثمنة حسب نوافذ التواريخ.

الاتصالات

ACME Mobile كيبين سياق الحساب، ومصفوفة الباقات، وكشف الرسوم اللي كيكتبو الخادم. تدفقات التاجر كتهتم بمزيج الباقات وتغييرات الأثمنة، مع حماية الرسوم الخاضعة للتنظيم.

الترفيه

ACME Tickets فيه حجوزات مؤقتة، ولوائح انتظار، وتحويلات، وخرائط القاعات، وكشف شامل للرسوم. أدوات التاجر ديالو كتهتم بوتيرة الفعاليات، وتحرير الحجوزات المؤقتة اللي كيوفّر السعة، وتغييرات الأثمنة اللي كتحافظ على الرسوم.

استعمل بيئة تشغيل Messages API

تنفيذ Messages API هو الحلقة المرجعية ديال الدوران. صايب إعدادات، عطِ التنفيذ ديال الـ backend ديالك، وجّه الـ runtime لمهارات التسوّق، وبثّ الأحداث اللي كتتولّد خلال الدوران:

from pathlib import Path

from shopping_agent import ShoppingAgentConfig
from shopping_agent_runtime import ShoppingAgent

agent = ShoppingAgent(
    backend=your_backend,
    skills_dir=Path("shopping-agent/skills"),
    config=ShoppingAgentConfig(brand_name="Your Store"),
)

async for event in agent.stream_turn(messages, session, state):
    ...

await agent.update_memory(messages, session)

مجرى الأحداث يقدر يتضمّن text_delta وtool_call وui وcart_update وturn_complete. من جهة التاجر، الكتابات المرحلية كتمثّلها أحداث change_update.

استخراج الذاكرة عبر update_memory خاص بمسار الـ runtime هذا. الأمثلة المستضيفة كتوصل معرّف الجلسة عبر ترويسة الطلب X-Session-Id.

استعمل runtime ديال Agent SDK

Agent SDK كيشغّل نفس الـ prompts والمهارات والأدوات، وكيهتم بحلقة الوكيل. المضيف كيسبق وكيجيب قراءات الإسناد، وما كيبقى حتى عمل من بعد الدوران.

شغّل طلب تسوّق واحد من الكونسول:

python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"

بدا كونسول التاجر بهاد الأمر:

python merchant-agent/runtime-agent-sdk/main.py

كونسول التاجر كيطلب موافقة y/N قبل ما يطبّق التغييرات المرحلية.

نشر عبر Managed Agents

Managed Agents كيستضيف الوكيل مع استعمال نفس المهارات والعقود. الوكيل كيتاصل بسيرفر MCP ديالك باش يوصل للأنظمة. دير تجربة نشر بلا تنفيذ بهاد الأمر:

scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent

استعمل المسار المكافئ تحت merchant-agent/managed-agents/ لدور التاجر. زِد --live غير ملي تكون ناوي تدير نشر فعلي.

بني وكيل التجارة ديالك

إضافة Claude Code المرفقة تقدر تنشئ مشروع متوافق مع الـ stack ديالك أو تراجع وكيل موجود. من بعد ما تنسخ المستودع محلياً، سجّل وثبّت الإضافة:

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude

داخل Claude Code، طلب إنشاء هيكل مساعد للتسوّق:

/scaffold-commerce-agent a shopping assistant for our store

الأمر كيسولك على الـ stack التكنولوجي ديالك، كيقدّم الخطة ديالو، وكيبني المشروع. كمّل التطوير باستعمال /add-commerce-flow و/author-commerce-evals. استعمل /review-commerce-agent إلا بديتي من وكيل موجود من قبل.

ربط الوكلاء بالأنظمة ديالك

المستودع ما كيجيش بموصلات MCP. عوض ذلك، الوكيلان بجوج كيوصلو للأنظمة التجارية عبر واجهات backend. كل دالة فـ backend خاصها تعيط للخدمة ديالك من جهة السيرفر باستعمال بيانات الاعتماد اللي محتافظ بها المضيف للجلسة الحالية. النموذج كيتوصل غير بنتيجة الدالة.

1. اختار الدور: نفّذ StorefrontBackend لتسوّق الزبناء أو MerchantBackend لعمليات الموظفين.
2. ربط عمليات القراءة: وصل الكاتالوغ والسياسات والتحليلات والمخزون والتسعير أو أي قراءات أخرى مدعومة بأنظمة المصدر الرسمي ديالك.
3. حافظ على المسارات المرتّبة: إلا كان سير العمل خاصو يتبع تسلسلاً ثابتاً، فرض هاد التسلسل فـ backend عوض الاعتماد على النموذج.
4. تحكّم فالكتابات: خلّي تغييرات التاجر مرحلية حتى يرخّص سطح موافقة المضيف بتطبيقها.
5. حوّل للدفع: رجّع رابط الدفع ديالك من backend وخلي المضيف يعرضو. النموذج خاصو ما يشوفش الرابط.

الـ backend يقدر يعيط لمنصات التجارة أو للموصلات الرسمية من جهة السيرفر. الأهداف المحتملة للتكامل اللي كيذكرها المشروع كتشمل مستودعات التحليلات، وأنظمة المالية، وأدوات التوصيل. خاص بوابات مصدر البيانات تبقى قبل الكتابات، حتى ملي كتستعمل خوادم MCP مع Managed Agents.

خصّص القدرات والهوية

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

إلا ما كاناش عند الشركة قدرة معيّنة، طفي إعداد enable_* الموافق ليها. هاد الشي كيحيد الأدوات المرتبطة بها، ومحتوى الـ prompt، وقاعدة الإسناد فكل مسارات الـ runtime. المسارات اللي كتعتمد على قدرة غير متاحة تقدر تحطّها تحت skills/_staged/.

صايب مسار مخصّص بإضافة مجلد فيه SKILL.md تحت مجلد skills/ المناسب. استعمل PresentationExtension لواجهة مستخدم خاصة بالمجال. الإعدادات brand_name وassistant_name وbrand_voice كتخصّص هوية أي واحد من الوكيلين.

مسؤوليات السلامة والنشر

المشروع كيفرض العزل، وبوابات مصدر البيانات، والحدود القصوى، والتحقق من الذاكرة، وموافقات التاجر داخل استدعاءات الأدوات فمسارات الـ runtime الثلاثة كاملين. الإسناد، وميزانيات التحليل، واستخراج الذاكرة هي ميزات على مستوى الـ runtime.

هاد التحكّمات ما كتعوّضش الأمان الخاص بكل عملية نشر. الأمثلة ما فيهاش المصادقة، وسيرفرات MCP ديالها كترتبط غير بـ loopback. المضيف ديالك فالإنتاج هو المسؤول على الهوية، والتخويل، وقواعد العمل، والامتثال، والتعامل مع بيانات الاعتماد، وسياسات الموافقة. راجع دليل الأمان قبل ما تربط الأنظمة الحقيقية.

تحقّق من التنفيذ

ثبّت متطلبات التطوير إلا كنت محتاج أدوات الاختبار والتحقّق من التنسيق:

pip install -r requirements-dev.txt

شغّل التحقّق من التنسيق، والتحليل الساكن، والاختبارات، وفحوصات المستودع:

ruff check . && ruff format --check . && pytest && python scripts/check.py

شغّل مسار التحقّق الكامل، بما فيه تجارب النشر الجافة وبناء الويب:

python scripts/verify_all.py

باش تجرّب محادثة مباشرة وحدة، وفّر مفتاح API وشغّل:

python scripts/smoke_chat.py --vertical travel

نصائح متقدّمة

• راقب سلوك التخزين المؤقّت: قرا cache_read_input_tokens من حدث turn_complete ولا من سجلات استدعاءات النموذج أثناء التشغيل. إلا كانت القيمة صفر فالدورة الثانية، فهذا كيعني باللي بادئة الطلب تبدّلات.
• دعّم الأسواق المتعدّدة: اعتبر البائع بُعداً من أبعاد البحث، وحصر وكيل التاجر فالمشغّل اللي حدّداتو الجلسة.
• احترم تسعيرة الحساب: إلا كان الثمن كيعتمد على حساب ولا عقد، رجّع الثمن اللي مناسب لحساب الجلسة.
• كيّف عملية الأداء: إلا ما كنتش مالك عملية الأداء، عطّل السلة ولا حوّل المسار لصفحة ديال عرض ثمن، ولا أمر شراء، ولا أداء مستضاف.
• استعمل عملاء خاصّين بالمنصّة: أوقات التشغيل كتقبل عميل anthropic عبر client=، بينما أوقات تشغيل SDK كتقرا إعدادات المنصّة ديالها من بيئة CLI.
• راجع اختيارات النشر: المستودع كيوثّق عمليات النشر عبر GCP Vertex AI وAWS Bedrock وMicrosoft Foundry والبوابات فـ دليل النشر.
• درس الربط مع الواجهة الخلفية: الهوية، وبيانات الاعتماد، والأداء، والمسارات المرتّبة، واختيارات المنتجات، والأرقام غير المتاحة مغطّاة فـ دليل الواجهة الخلفية.

الخلاصة

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

المستودع مرخّص بموجب Apache License 2.0. هو تنفيذ مرجعي، وما كيتصانش، وما كيقبلش المساهمات.