Claude Commerce Agents کے ساتھ شاپنگ اور مرچنٹ ایجنٹس بنائیں اور چلائیں

Claude Commerce Agents کیا فراہم کرتا ہے

Claude Commerce Agents، Claude پر بنائے گئے تجارت پر مرکوز دو AI ایجنٹس کا حوالہ جاتی نفاذ ہے۔ کوئی کاروبار شاپنگ ایجنٹ کو صارفین کے لیے بنائی گئی ایپلیکیشن میں شامل کر سکتا ہے، جبکہ عملہ بیک آفس کے ورک فلو چلانے کے لیے مرچنٹ ایجنٹ استعمال کر سکتا ہے۔

ہر ایجنٹ کی تعریف اس کے پرامپٹ، مہارتوں، ٹول معاہدوں اور حفاظتی مراحل کے ذریعے ایک بار کی جاتی ہے۔ یہی تعریفیں 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 key بھی درکار ہوگی۔

ریپوزٹری انسٹال کریں

پروجیکٹ کلون کریں، 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 کا نفاذ ریفرنس ٹرن لوپ ہے۔ ایک کنفیگریشن بنائیں، اپنا بیک اینڈ نفاذ فراہم کریں، رن ٹائم کو شاپنگ اسکلز کی طرف متوجہ کریں، اور ٹرن کے دوران پیدا ہونے والے ایونٹس کو اسٹریم کریں:

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 کے ذریعے میموری کا استخراج اسی رن ٹائم راستے تک محدود ہے۔ مثال کے میزبان X-Session-Id درخواست ہیڈر کے ذریعے سیشن شناخت کنندہ وصول کرتے ہیں۔

Agent SDK رن ٹائم استعمال کریں

Agent SDK ایجنٹ لوپ کا انتظام کرتے ہوئے وہی پرامپٹس، اسکلز، اور ٹولز چلاتا ہے۔ میزبان پہلے سے گراؤنڈنگ ریڈز حاصل کرتا ہے، اور ٹرن کے بعد کوئی کام نہیں چلتا۔

کنسول سے شاپنگ کی ایک درخواست چلائیں:

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 پلگ اِن آپ کے اسٹیک کے مطابق پروجیکٹ بنا سکتا ہے یا موجودہ ایجنٹ کا جائزہ لے سکتا ہے۔ ریپوزٹری مقامی طور پر کلون کرنے کے بعد پلگ اِن کو رجسٹر اور انسٹال کریں:

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

کمانڈ آپ کے ٹیکنالوجی اسٹیک کے بارے میں سوالات کرتی ہے، اپنا منصوبہ پیش کرتی ہے، اور پروجیکٹ بناتی ہے۔ /add-commerce-flow اور /author-commerce-evals کے ذریعے ترقی جاری رکھیں۔ پہلے سے موجود ایجنٹ سے آغاز کرتے وقت /review-commerce-agent استعمال کریں۔

ایجنٹس کو اپنے سسٹمز سے مربوط کریں

ریپوزٹری میں MCP کنیکٹرز شامل نہیں ہیں۔ اس کے بجائے، دونوں ایجنٹس بیک اینڈ انٹرفیسز کے ذریعے کاروباری سسٹمز تک پہنچتے ہیں۔ ہر بیک اینڈ طریقے کو موجودہ سیشن کے لیے میزبان کے پاس محفوظ اسناد استعمال کرتے ہوئے سرور کی جانب سے آپ کی سروس کو کال کرنی چاہیے۔ ماڈل کو صرف طریقے کا نتیجہ موصول ہوتا ہے۔

1. کردار منتخب کریں: صارفین کی شاپنگ کے لیے StorefrontBackend یا عملے کے آپریشنز کے لیے MerchantBackend نافذ کریں۔
2. ریڈ آپریشنز کی نقشہ بندی کریں: کیٹلاگ، پالیسیوں، تجزیات، انوینٹری، قیمتوں، یا دیگر معاون ریڈز کو اپنے اصل ماخذ کے سسٹمز سے مربوط کریں۔
3. ترتیب وار فلو برقرار رکھیں: اگر کسی ورک فلو کو مقررہ ترتیب کی پابندی کرنا ضروری ہو تو ماڈل پر انحصار کرنے کے بجائے یہ ترتیب بیک اینڈ میں نافذ کریں۔
4. تحریری تبدیلیوں کو کنٹرول کریں: مرچنٹ کی تبدیلیاں میزبان کی منظوری کی سطح سے اجازت ملنے تک عارضی رکھیں۔
5. چیک آؤٹ منتقل کریں: بیک اینڈ سے اپنا چیک آؤٹ URL واپس کریں اور میزبان کو اسے رینڈر کرنے دیں۔ ماڈل کو URL کبھی نظر نہیں آنا چاہیے۔

بیک اینڈ سرور کی جانب سے کامرس پلیٹ فارمز یا سرکاری کنیکٹرز کو کال کر سکتا ہے۔ پروجیکٹ میں مذکور ممکنہ انٹیگریشن اہداف میں تجزیاتی ڈیٹا ویئرہاؤسز، مالیاتی سسٹمز، اور ڈیلیوری ٹولز شامل ہیں۔ تحریری تبدیلیوں سے پہلے پروویننس گیٹس برقرار رہنے چاہییں، بشمول اس صورت کے جب Managed Agents کے ساتھ MCP سرورز استعمال کیے جائیں۔

صلاحیتوں اور شناخت کو حسب ضرورت بنائیں

سب سے کم مگر مفید سطح سے آغاز کریں۔ شاپنگ پائلٹ سرچ اور پروڈکٹ کی تفصیلات نافذ کر سکتا ہے جبکہ اسٹب کیے گئے طریقوں سے غیر دستیاب نتائج واپس کر سکتا ہے۔ مرچنٹ پائلٹ آٹھ ریڈ طریقے نافذ کر سکتا ہے اور تحریری تبدیلیوں سے انکار کر سکتا ہے، جس سے تحریری راستہ ظاہر کیے بغیر ڈائجسٹ اور میٹرکس کام کر سکتے ہیں۔

اگر کاروبار میں کوئی صلاحیت موجود نہیں ہے تو متعلقہ enable_* ترتیب بند کر دیں۔ اس سے ہر رن ٹائم راستے پر متعلقہ ٹولز، پرامپٹ کا مواد، اور گراؤنڈنگ قاعدہ ختم ہو جاتا ہے۔ ایسی فلو جن کا انحصار غیر دستیاب صلاحیت پر ہو، انہیں skills/_staged/ کے تحت رکھا جا سکتا ہے۔

موزوں skills/ ڈائریکٹری کے تحت SKILL.md پر مشتمل ڈائریکٹری شامل کر کے حسب ضرورت فلو بنائیں۔ ڈومین کے مخصوص UI کے لیے PresentationExtension استعمال کریں۔ brand_name، assistant_name، اور brand_voice ترتیبات کسی بھی ایجنٹ کی شناخت کو حسب ضرورت بناتی ہیں۔

حفاظت اور تعیناتی کی ذمہ داریاں

پروجیکٹ تینوں رن ٹائم راستوں میں ٹول کالز کے اندر فینسنگ، پروویننس گیٹس، حدود، میموری کی توثیق، اور مرچنٹ کی منظوریوں کو نافذ کرتا ہے۔ گراؤنڈنگ، تجزیاتی بجٹس، اور میموری کا استخراج رن ٹائم سطح کی خصوصیات ہیں۔

یہ کنٹرولز تعیناتی سے متعلق مخصوص سیکیورٹی کا متبادل نہیں ہیں۔ ان مثالوں میں توثیق شامل نہیں ہے، اور ان کے MCP سرورز صرف لوپ بیک سے منسلک ہوتے ہیں۔ آپ کا پروڈکشن ہوسٹ شناخت، اجازت، کاروباری قواعد، تعمیل، اسناد کے انتظام اور منظوری کی پالیسیوں کا ذمہ دار رہتا ہے۔ حقیقی سسٹمز سے منسلک ہونے سے پہلے حفاظتی رہنما کا جائزہ لیں۔

عمل درآمد کی تصدیق کریں

اگر آپ کو ٹیسٹ اور لِنٹ کے ٹولز درکار ہوں تو ڈیولپمنٹ کی ضروریات انسٹال کریں:

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

اعلیٰ درجے کی تجاویز

• کیش کے رویے کا جائزہ لیں: turn_complete ایونٹ یا رَن ٹائم ماڈل کال کے لاگز سے cache_read_input_tokens پڑھیں۔ دوسری باری میں صفر قدر اس بات کی نشاندہی کرتی ہے کہ پرامپٹ کا سابقہ تبدیل ہو گیا ہے۔
• مارکیٹ پلیسز کو سپورٹ کریں: فروخت کنندہ کو تلاش کے ایک بُعد کے طور پر برتیں اور مرچنٹ ایجنٹ کا دائرہ کار سیشن میں شناخت کیے گئے آپریٹر تک محدود رکھیں۔
• اکاؤنٹ کی قیمتوں کا احترام کریں: جب قیمت کسی اکاؤنٹ یا معاہدے پر منحصر ہو تو سیشن کے اکاؤنٹ پر لاگو قیمت واپس کریں۔
• چیک آؤٹ کو موافق بنائیں: اگر چیک آؤٹ آپ کے اختیار میں نہیں ہے تو کارٹ کو غیر فعال کریں یا ورک فلو کو کوٹ، پرچیز آرڈر یا ہوسٹڈ چیک آؤٹ صفحے پر منتقل کریں۔
• پلیٹ فارم کے مطابق کلائنٹس استعمال کریں: رَن ٹائمز client= کے ذریعے anthropic کلائنٹ قبول کرتے ہیں، جبکہ SDK رَن ٹائمز اپنی پلیٹ فارم کنفیگریشن CLI ماحول سے پڑھتے ہیں۔
• تعیناتی کے اختیارات کا جائزہ لیں: ریپوزٹری تعیناتی رہنما میں GCP Vertex AI، AWS Bedrock، Microsoft Foundry اور گیٹ وے کی تعیناتیوں کی دستاویز فراہم کرتی ہے۔
• بیک اینڈ میپنگ کا مطالعہ کریں: شناخت، اسناد، چیک آؤٹ، ترتیب دیے گئے فلو، پروڈکٹ کے اختیارات اور دستیاب نہ ہونے والے اعداد و شمار کا احاطہ بیک اینڈ رہنما میں کیا گیا ہے۔

نتیجہ

Claude Commerce Agents مشترکہ پرامپٹس، مہارتوں، معاہدوں اور حفاظتی کنٹرولز سے صارفین کے لیے خریداری کے معاونین اور منظوری سے مشروط مرچنٹ ٹولز بنانے کا ایک عملی آرکیٹیکچر فراہم کرتا ہے۔ قابلِ عمل ورٹیکل سے آغاز کریں، اپنے پلیٹ فارم کے لیے موزوں رَن ٹائم منتخب کریں، مناسب بیک اینڈ انٹرفیس نافذ کریں، غیر معاون صلاحیتوں کو غیر فعال کریں، اور پروڈکشن ڈیٹا یا تحریری کارروائیوں سے منسلک ہونے سے پہلے پورے سسٹم کی تصدیق کریں۔

ریپوزٹری Apache License 2.0 کے تحت لائسنس یافتہ ہے۔ یہ ایک حوالہ جاتی عمل درآمد ہے، اس کی دیکھ بھال نہیں کی جاتی، اور یہ شراکتیں قبول نہیں کرتی۔