
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
claudeClaude Code-এর ভেতরে একটি শপিং অ্যাসিস্ট্যান্টের স্ক্যাফোল্ড চেয়ে নিন:
/scaffold-commerce-agent a shopping assistant for our storeকমান্ডটি আপনার প্রযুক্তি স্ট্যাক সম্পর্কে জানতে চায়, তার পরিকল্পনা উপস্থাপন করে এবং প্রজেক্ট তৈরি করে। /add-commerce-flow এবং /author-commerce-evals দিয়ে উন্নয়ন চালিয়ে যান। ইতিমধ্যে বিদ্যমান কোনো এজেন্ট দিয়ে শুরু করলে /review-commerce-agent ব্যবহার করুন।
এজেন্টগুলোকে আপনার সিস্টেমের সঙ্গে সংযুক্ত করুন
রিপোজিটরিতে MCP কানেক্টর সরবরাহ করা হয়নি। এর পরিবর্তে, উভয় এজেন্টই ব্যাকএন্ড ইন্টারফেসের মাধ্যমে ব্যবসায়িক সিস্টেমে পৌঁছায়। প্রতিটি ব্যাকএন্ড মেথডের সার্ভার পাশে, বর্তমান সেশনের জন্য হোস্টের কাছে থাকা ক্রেডেনশিয়াল ব্যবহার করে আপনার সার্ভিসে কল করা উচিত। মডেল কেবল মেথডের ফলাফল পায়।
- ভূমিকা নির্বাচন করুন: গ্রাহক শপিংয়ের জন্য
StorefrontBackendঅথবা কর্মীদের কার্যক্রমের জন্যMerchantBackendবাস্তবায়ন করুন। - রিড অপারেশন ম্যাপ করুন: ক্যাটালগ, নীতি, অ্যানালিটিক্স, ইনভেন্টরি, মূল্য নির্ধারণ বা অন্যান্য সমর্থিত রিড আপনার তথ্যের মূল উৎস সিস্টেমের সঙ্গে সংযুক্ত করুন।
- ক্রমনির্ভর ফ্লো বজায় রাখুন: কোনো ওয়ার্কফ্লোকে নির্দিষ্ট ক্রম অনুসরণ করতে হলে মডেলের ওপর নির্ভর না করে ব্যাকএন্ডে সেই ক্রম প্রয়োগ করুন।
- রাইট নিয়ন্ত্রণ করুন: হোস্টের অনুমোদন ব্যবস্থা অনুমোদন না দেওয়া পর্যন্ত মার্চেন্টের পরিবর্তনগুলো ধাপভিত্তিক অবস্থায় রাখুন।
- চেকআউটে হস্তান্তর করুন: ব্যাকএন্ড থেকে আপনার চেকআউট URL ফেরত দিন এবং হোস্টকে সেটি রেন্ডার করতে দিন। মডেলের কখনোই URL দেখা উচিত নয়।
ব্যাকএন্ড সার্ভার পাশে কমার্স প্ল্যাটফর্ম বা অফিসিয়াল কানেক্টরে কল করতে পারে। প্রজেক্টে উল্লেখিত সম্ভাব্য ইন্টিগ্রেশন লক্ষ্যগুলোর মধ্যে রয়েছে অ্যানালিটিক্স ডেটা গুদাম, অর্থব্যবস্থা সিস্টেম এবং ডেলিভারি টুল। MCP সার্ভার Managed Agents-এর সঙ্গে ব্যবহার করা হলেও রাইট অপারেশনের সামনে প্রোভেন্যান্স গেট রাখা উচিত।
সক্ষমতা ও পরিচয় কাস্টমাইজ করুন
সবচেয়ে ছোট কার্যকর সারফেস দিয়ে শুরু করুন। একটি শপিং পাইলটে সার্চ ও পণ্যের বিবরণ বাস্তবায়ন করা যায়, আর স্টাব করা মেথড থেকে অনুপলব্ধ ফলাফল ফেরত দেওয়া যায়। একটি মার্চেন্ট পাইলটে আটটি রিড মেথড বাস্তবায়ন করে রাইট প্রত্যাখ্যান করা যায়, ফলে রাইট পাথ উন্মুক্ত না করেই ডাইজেস্ট ও মেট্রিক্স কাজ করতে পারে।
ব্যবসায় কোনো সক্ষমতা না থাকলে সংশ্লিষ্ট 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 key প্রদান করে চালান:
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-এর অধীনে লাইসেন্সপ্রাপ্ত। এটি একটি রেফারেন্স ইমপ্লিমেন্টেশন, রক্ষণাবেক্ষণ করা হয় না এবং অবদান গ্রহণ করে না।
