Xây dựng và chạy tác nhân mua sắm và thương nhân với Claude Commerce Agents

Claude Commerce Agents cung cấp những gì

Claude Commerce Agents là một triển khai tham chiếu gồm hai tác nhân AI tập trung vào thương mại, được xây dựng trên Claude. Doanh nghiệp có thể tích hợp tác nhân mua sắm vào ứng dụng hướng đến khách hàng, trong khi nhân viên có thể sử dụng tác nhân người bán để vận hành các quy trình hậu cần.

Mỗi tác nhân được định nghĩa một lần thông qua prompt, kỹ năng, hợp đồng công cụ và các lớp kiểm soát an toàn. Các định nghĩa này có thể chạy thông qua Messages API, Claude Agent SDK hoặc Managed Agents. Bốn ngành dọc có thể chạy được minh họa cho kiến trúc này trong các lĩnh vực bán lẻ, du lịch, viễn thông và giải trí.

Tất cả công ty, sản phẩm, thương hiệu và con người trong repository đều là hư cấu. Các ví dụ không đặt hàng, tính phí thẻ hoặc cập nhật danh sách đang hoạt động. Việc thanh toán được bàn giao cho máy chủ lưu trữ, còn các thay đổi của người bán vẫn ở trạng thái chờ cho đến khi có người phê duyệt.

Tìm hiểu hai vai trò của tác nhân

Tác nhân mua sắm

Tác nhân mua sắm hỗ trợ các tác vụ hướng đến khách hàng như tìm kiếm và so sánh sản phẩm, lập kế hoạch mua sắm, thêm sản phẩm vào giỏ hàng, trả lời câu hỏi về đơn hàng và chính sách, cũng như ghi nhớ thông tin do khách hàng cung cấp.

Năm luồng của tác nhân nằm trong shopping-agent/skills/. Để sử dụng tác nhân với các hệ thống thực, bản triển khai của bạn cần hiện thực StorefrontBackend trên các dịch vụ danh mục, giỏ hàng, đơn hàng và chính sách tương ứng.

Tác nhân người bán

Tác nhân người bán giúp nhân viên nắm bắt hiệu suất, duy trì danh sách sản phẩm, phản hồi cảnh báo về hàng tồn kho và đơn hàng, điều chỉnh giá và khuyến mãi, cũng như soạn thảo chiến dịch. Năm luồng của tác nhân nằm trong merchant-agent/skills/.

Bản triển khai kết nối tác nhân với các hệ thống phân tích, danh mục, hàng tồn kho, định giá và chiến dịch bằng cách hiện thực MerchantBackend. Mọi thao tác ghi đều được đưa vào trạng thái chờ thay vì áp dụng ngay; ứng dụng máy chủ lưu trữ phải hiển thị và phê duyệt thay đổi được đề xuất.

Kiến trúc và tính năng chính

• Nền tảng dùng chung: commerce-common/ chứa cấu hình, cơ chế fencing, bộ nhớ, xử lý kỹ năng, grounding, trình bày, sự kiện và khung thực thi được cả hai vai trò sử dụng.
• Nhiều runtime: cùng một bộ prompt, kỹ năng và hợp đồng công cụ hoạt động với Messages API, Agent SDK và Managed Agents.
• Trừu tượng hóa backend: các công cụ của tác nhân gọi đến các giao diện backend, cho phép máy chủ của bạn lưu giữ thông tin xác thực và điều phối quyền truy cập vào các hệ thống nghiệp vụ.
• Thay đổi người bán ở trạng thái chờ: các thao tác ghi của người bán phải được phê duyệt thông qua giao diện phê duyệt của ứng dụng máy chủ lưu trữ.
• Khả năng cấu hình: có thể tắt các tính năng không được hỗ trợ để loại bỏ công cụ, dòng prompt và quy tắc grounding tương ứng.
• Trình bày có thể mở rộng: có thể thêm các giao diện dành riêng cho từng lĩnh vực thông qua PresentationExtension.
• Ví dụ có thể chạy: tám ứng dụng web cung cấp storefront và cổng người bán cho từng ngành trong bốn ngành dọc.

Điều kiện tiên quyết

Cài đặt Python 3.11 trở lên và Node.js 22. Bạn cũng cần khóa API Anthropic để chạy các tương tác trực tiếp với mô hình.

Cài đặt repository

Sao chép dự án, tạo môi trường ảo Python, cài đặt các dependency Python đã được ghim phiên bản, tạo tệp môi trường và cài đặt workspace JavaScript dùng chung:

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)

Mở .env và thêm ANTHROPIC_API_KEY của bạn. Duy trì môi trường ảo ở trạng thái kích hoạt khi chạy các tập lệnh Python.

Chạy bản demo đầu tiên

Khởi động storefront bán lẻ và API của storefront bằng lệnh:

python scripts/run_demo.py retail

API bán lẻ chạy trên cổng 8000, còn storefront chạy trên cổng 3000. Để khởi động cổng người bán thay cho storefront, thêm --merchant:

python scripts/run_demo.py retail --merchant

Sử dụng --all để khởi động cả hai giao diện:

python scripts/run_demo.py retail --all

Các ngành dọc và cổng web khả dụng:

• Bán lẻ: storefront 3000, cổng người bán 3100.
• Du lịch: storefront 3001, cổng người bán 3101.
• Viễn thông: storefront 3002, cổng người bán 3102.
• Giải trí: storefront 3003, cổng người bán 3103.

Mỗi thư mục ví dụ có một README chứa các prompt được đề xuất và mô tả về nội dung một câu trả lời tốt nên bao gồm.

Khám phá các ngành dọc trong ví dụ

Bán lẻ

Ví dụ bán lẻ ACME minh họa việc tìm kiếm sản phẩm, so sánh, lập kế hoạch, giỏ hàng, bàn giao thanh toán và bộ nhớ. Cổng người bán bao gồm các bản tổng hợp hiệu suất, bổ sung hàng tồn kho ở trạng thái chờ, sửa lỗi danh sách và một ủy quyền phân tích trên một chế độ xem SQL.

Du lịch

ACME Travel bổ sung hàng tồn kho theo ngày và một extension present_itinerary. Phía người bán bao gồm lịch công suất và các thay đổi giá theo khoảng ngày.

Viễn thông

ACME Mobile minh họa ngữ cảnh tài khoản, ma trận gói cước và thông tin công khai về phí do máy chủ tạo. Các quy trình của người bán bao quát cơ cấu gói cước và thay đổi giá, đồng thời bảo vệ các khoản phí chịu quy định.

Giải trí

ACME Tickets bao gồm giữ chỗ có thời hạn, danh sách chờ, chuyển vé, sơ đồ địa điểm và thông tin công khai về tổng phí. Các công cụ dành cho người bán bao quát nhịp độ sự kiện, giải phóng lượt giữ chỗ tạo ra công suất và thay đổi giá không làm ảnh hưởng đến phí.

Sử dụng runtime Messages API

Triển khai Messages API là vòng lặp lượt tham chiếu. Hãy tạo cấu hình, cung cấp triển khai backend của bạn, trỏ runtime đến các kỹ năng mua sắm và stream các sự kiện được tạo trong một lượt:

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)

Luồng sự kiện có thể bao gồm text_delta, tool_call, ui, cart_update và turn_complete. Ở phía người bán, các thao tác ghi theo giai đoạn được biểu diễn bằng các sự kiện change_update.

Việc trích xuất bộ nhớ thông qua update_memory chỉ dành riêng cho đường dẫn runtime này. Các máy chủ mẫu nhận mã nhận diện phiên qua header yêu cầu X-Session-Id.

Sử dụng runtime Agent SDK

Agent SDK chạy cùng các prompt, kỹ năng và công cụ, đồng thời quản lý vòng lặp agent. Máy chủ thực hiện trước các thao tác đọc để cung cấp dữ liệu nền và không có công việc nào chạy sau lượt đó.

Chạy một yêu cầu mua sắm từ bảng điều khiển:

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

Khởi động bảng điều khiển người bán bằng:

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

Bảng điều khiển người bán yêu cầu phê duyệt y/N trước khi áp dụng các thay đổi theo giai đoạn.

Triển khai qua Managed Agents

Managed Agents lưu trữ agent đồng thời sử dụng cùng các kỹ năng và hợp đồng. Agent gọi máy chủ MCP của bạn để truy cập hệ thống. Chạy thử triển khai bằng:

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

Sử dụng đường dẫn tương đương bên dưới merchant-agent/managed-agents/ cho vai trò người bán. Chỉ thêm --live khi bạn thực sự muốn tiến hành triển khai chính thức.

Tạo khung agent thương mại của riêng bạn

Plugin Claude Code đi kèm có thể tạo một dự án phù hợp với ngăn xếp công nghệ của bạn hoặc xem xét một agent hiện có. Sau khi sao chép repository về máy cục bộ, hãy đăng ký và cài đặt plugin:

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

Trong Claude Code, hãy yêu cầu tạo khung trợ lý mua sắm:

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

Lệnh này hỏi về ngăn xếp công nghệ của bạn, trình bày kế hoạch rồi xây dựng dự án. Tiếp tục phát triển bằng /add-commerce-flow và /author-commerce-evals. Sử dụng /review-commerce-agent khi bắt đầu từ một agent đã tồn tại.

Kết nối agent với hệ thống của bạn

Repository không tích hợp sẵn các connector MCP. Thay vào đó, cả hai agent truy cập hệ thống nghiệp vụ thông qua các interface backend. Mỗi phương thức backend nên gọi dịch vụ của bạn ở phía máy chủ bằng thông tin xác thực mà máy chủ lưu giữ cho phiên hiện tại. Model chỉ nhận kết quả của phương thức.

1. Chọn vai trò: triển khai StorefrontBackend cho hoạt động mua sắm của khách hàng hoặc MerchantBackend cho các thao tác của nhân viên.
2. Ánh xạ các thao tác đọc: kết nối danh mục, chính sách, phân tích, tồn kho, định giá hoặc các thao tác đọc được hỗ trợ khác với hệ thống nguồn dữ liệu chuẩn của bạn.
3. Duy trì quy trình theo thứ tự: nếu một quy trình phải tuân theo trình tự cố định, hãy thực thi trình tự đó trong backend thay vì dựa vào model.
4. Kiểm soát thao tác ghi: giữ các thay đổi của người bán ở trạng thái theo giai đoạn cho đến khi giao diện phê duyệt của máy chủ cho phép áp dụng.
5. Bàn giao thanh toán: trả về URL thanh toán của bạn từ backend và để máy chủ hiển thị URL đó. Model không bao giờ được nhìn thấy URL.

Backend có thể gọi các nền tảng thương mại hoặc connector chính thức ở phía máy chủ. Các đích tích hợp tiềm năng được dự án đề cập bao gồm kho dữ liệu phân tích, hệ thống tài chính và công cụ giao hàng. Các lớp kiểm tra nguồn gốc dữ liệu phải tiếp tục được đặt trước các thao tác ghi, kể cả khi máy chủ MCP được sử dụng với Managed Agents.

Tùy chỉnh khả năng và danh tính

Hãy bắt đầu với bề mặt chức năng nhỏ nhất nhưng hữu ích. Một bản thử nghiệm mua sắm có thể triển khai chức năng tìm kiếm và thông tin sản phẩm, đồng thời trả về kết quả không khả dụng từ các phương thức giả lập. Một bản thử nghiệm cho người bán có thể triển khai tám phương thức đọc và từ chối các thao tác ghi, cho phép digest và chỉ số hoạt động mà không mở ra đường dẫn ghi.

Nếu doanh nghiệp thiếu một khả năng, hãy tắt cài đặt enable_* tương ứng. Thao tác này loại bỏ các công cụ, nội dung prompt và quy tắc cung cấp dữ liệu nền liên quan trên mọi đường dẫn runtime. Các quy trình phụ thuộc vào khả năng không khả dụng có thể được đặt dưới skills/_staged/.

Tạo một quy trình tùy chỉnh bằng cách thêm một thư mục chứa SKILL.md vào thư mục skills/ thích hợp. Sử dụng PresentationExtension cho giao diện người dùng dành riêng cho từng miền. Các cài đặt brand_name, assistant_name và brand_voice tùy chỉnh danh tính của một trong hai agent.

Trách nhiệm về an toàn và triển khai

Dự án thực thi các cơ chế ngăn cách, lớp kiểm tra nguồn gốc dữ liệu, giới hạn, xác thực bộ nhớ và phê duyệt của người bán bên trong các lệnh gọi công cụ trên cả ba đường dẫn runtime. Việc cung cấp dữ liệu nền, ngân sách phân tích và trích xuất bộ nhớ là các tính năng ở cấp runtime.

Các control này không thay thế cho bảo mật riêng của từng môi trường triển khai. Các ví dụ không có cơ chế xác thực và máy chủ MCP của chúng chỉ liên kết với loopback. Máy chủ production của bạn vẫn chịu trách nhiệm về danh tính, quyền hạn, quy tắc nghiệp vụ, tuân thủ, xử lý thông tin xác thực và chính sách phê duyệt. Hãy xem hướng dẫn an toàn trước khi kết nối các hệ thống thực.

Xác minh việc triển khai

Cài đặt các yêu cầu phát triển nếu bạn cần các công cụ kiểm thử và lint:

pip install -r requirements-dev.txt

Chạy kiểm tra định dạng, lint, kiểm thử và các bước kiểm tra của repository:

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

Chạy toàn bộ quy trình xác minh, bao gồm chạy thử triển khai và build web:

python scripts/verify_all.py

Để chạy thử một cuộc hội thoại trực tiếp, cung cấp API key rồi chạy:

python scripts/smoke_chat.py --vertical travel

Mẹo nâng cao

• Kiểm tra hoạt động của bộ nhớ đệm: đọc cache_read_input_tokens từ sự kiện turn_complete hoặc từ nhật ký gọi model lúc runtime. Giá trị bằng 0 ở lượt thứ hai cho biết tiền tố prompt đã thay đổi.
• Hỗ trợ các sàn giao dịch: xem người bán là một chiều tìm kiếm và giới hạn phạm vi của merchant agent vào đơn vị vận hành được xác định trong phiên.
• Tôn trọng mức giá theo tài khoản: khi giá phụ thuộc vào tài khoản hoặc hợp đồng, hãy trả về mức giá áp dụng cho tài khoản của phiên.
• Điều chỉnh quy trình thanh toán: nếu bạn không sở hữu quy trình thanh toán, hãy tắt giỏ hàng hoặc chuyển quy trình sang trang báo giá, đơn đặt hàng hoặc thanh toán lưu trữ.
• Sử dụng client riêng cho từng nền tảng: các runtime chấp nhận client anthropic thông qua client=, trong khi các runtime SDK đọc cấu hình nền tảng từ môi trường CLI.
• Xem xét các tùy chọn triển khai: repository ghi lại các hình thức triển khai GCP Vertex AI, AWS Bedrock, Microsoft Foundry và gateway trong hướng dẫn triển khai.
• Nghiên cứu ánh xạ backend: danh tính, thông tin xác thực, thanh toán, các luồng theo thứ tự, tùy chọn sản phẩm và các số liệu không khả dụng được đề cập trong hướng dẫn backend.

Kết luận

Claude Commerce Agents cung cấp một kiến trúc thực tiễn để xây dựng trợ lý mua sắm hướng đến khách hàng và các công cụ merchant yêu cầu phê duyệt, dựa trên prompt, skill, contract và cơ chế kiểm soát an toàn dùng chung. Hãy bắt đầu với một vertical có thể chạy được, chọn runtime phù hợp với nền tảng của bạn, triển khai interface backend thích hợp, tắt các tính năng không được hỗ trợ và xác minh toàn bộ hệ thống trước khi kết nối dữ liệu production hoặc các thao tác ghi.

Repository được cấp phép theo Apache License 2.0. Đây là một bản triển khai tham khảo, không được duy trì và không tiếp nhận đóng góp.