Як створювати комерційних ШІ-агентів: Розбір репозиторію Anthropic Commerce Agents

2 вересня 2026 року Anthropic виклала на GitHub blueprint, як має бути влаштований комерційний ШІ-агент. Компанія прямо пов'язує момент публікації із сезоном святкових розпродажів: у рітейлерів і маркетплейсів лишаються лічені тижні, щоб встигнути розгорнути агента до Black Friday. За словами Anthropic, у клієнтів, які вже запустили шопінг-агентів на Claude, кошик у середньому зростає до 35%, а ймовірність довести покупку до кінця — на 60%.

Репозиторій anthropics/commerce-agents — офіційний референсний проєкт, а не готовий продукт. Anthropic не забирає собі екран оплати: модель веде розмову й приймає рішення, а гроші, замовлення й авторизацію контролює бекенд бізнесу. Репозиторій лише показує, як розмежувати ці зони відповідальності. Нижче — розбір архітектури і практичний путівник, з чого почати.

Два агенти, одна архітектура

Замість універсального асистента-на-все Anthropic розділяє агентів за аудиторією та рівнем довіри:
Shopping Agent — живе у вашому застосунку чи на сайті. Шукає товари, порівнює їх, планує мультитоварні покупки ("намет, спальник і пальник на вихідні з двома дітьми"), веде кошик, пам'ятає вподобання клієнта між сесіями та відповідає на питання про статус замовлення й політику магазину. Працює поверх інтерфейсу StorefrontBackend.

Merchant Agent — інструмент для бек-офісу. Пояснює показники продажів, підтримує лістинги, реагує на сповіщення про запаси й проблемні замовлення, пропонує зміни цін і чернетки маркетингових кампаній. Ключове обмеження: кожен запис агента — це відкладена зміна (staged change), яка лежить у черзі, поки людина не підтвердить її через панель керування. Працює поверх інтерфейсу MerchantBackend.

Обидва агенти визначені один раз (промпт, навички, контракти інструментів, бар'єри) і однаково запускаються трьома різними способами — Messages API, Claude Agent SDK та Managed Agents (наразі в бета-статусі).

Анатомія репозиторію

Швидкий старт: демо за п'ять команд

Потрібні Python 3.11+ і Node 22. Команди нижче йдуть послідовно: клонують репозиторій, створюють ізольоване Python-оточення, ставлять сім пакетів блупринта разом із залежностями, копіюють приклад конфігурації (туди вписуєте свій ANTHROPIC_API_KEY), підтягують залежності восьми веб-застосунків у examples/ і нарешті запускають демо для вертикалі retail — ця остання команда одразу піднімає і бекенд-API, і вебсторінку сторфронту.

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                  # додайте ANTHROPIC_API_KEY
(cd examples && npm ci)               # вісім веб-застосунків в одному workspace
python scripts/run_demo.py retail     # API :8000 + сторфронт :3000

Прапорець --merchant запускає портал замість сторфронту, --all — обидва одразу. Порти по вертикалях: retail (:3000, портал :3100), travel (:3001, :3101), telecom (:3002, :3102), entertainment (:3003, :3103).

Три способи запустити агента

1. 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):
    ...  # text_delta, tool_call, ui, cart_update (на боці мерчанта — change_update), turn_complete

await agent.update_memory(messages, session)  # витяг пам'яті — лише для цього шляху запуску

update_memory() існує тільки в циклі Messages API — на Agent SDK і Managed Agents після ходу додатково нічого не виконується.

2. Agent SDK — той самий промпт, навички й інструменти, але цикл веде сам SDK; хост наперед підвантажує grounding-дані:

python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"
python merchant-agent/runtime-agent-sdk/main.py          # підтвердження staged changes через y/N у консолі

3. Managed Agents — агент хоститься на боці Anthropic і звертається до вашої MCP-інфраструктури:

scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent   # або merchant-agent/...; --live для продакшн-деплою

Для розгортання поза Anthropic-хостингом runtime приймає будь-який anthropic-клієнт як client=, а SDK-варіанти беруть платформу з CLI-оточення — docs/deployment.md описує варіанти для GCP Vertex AI, AWS Bedrock і Microsoft Foundry.

Як зібрати власного агента через Claude Code

Плагін commerce-builder перетворює скафолдинг на діалог у консолі:

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent a shopping assistant for our store

Команда розпитує про ваш стек, проговорює план назад і генерує проєкт. Далі в тому самому плагіні є ще три команди: /add-commerce-flow — додати новий бізнес-процес до вже зібраного агента, /author-commerce-evals — написати для нього тести-оцінки, і /review-commerce-agent — провести рев'ю агента, який ви вже маєте (навіть не написаного цим плагіном). Усі команди також запускаються автоматично, коли ваш запит їм відповідає за змістом — набирати назву руками не обов'язково.

Бекенд: єдина точка інтеграції з вашими системами

Агенти ніколи не торкаються ваших баз даних чи API напряму — лише через абстрактний клас, який ви наслідуєте і реалізуєте методами, що звертаються до ваших сервісів на сервері. Модель бачить лише результат виклику, ніколи — токен доступу.

#StorefrontBackend

• Каталог: search_products(session, query, filters, limit) — найближчі текстові збіги; get_product_details(session, product_id) — повна картка товару чи його варіанта.

• Кошик: get_cart(session), add_to_cart(session, product_id, quantity), update_cart_item(session, product_id, quantity), remove_from_cart(session, product_id).

• Контекст клієнта: get_preferences(session); опційно checkout_handoff (посилання на оплату) і get_account_context (тарифні чи контрактні дані).

• Замовлення й політики: get_orders(session, limit=5), get_order(session, order_id), search_policies(session, query).

• Опційно: get_disclosure (обов'язкові розкриття платежів) і get_fulfillment_options (варіанти доставки).
  

#MerchantBackend

• Показники: get_business_snapshot(session, period), query_metrics(session, metric, period, granularity, segment), get_campaign_performance(session, campaign_id).

• Каталог: search_listings, get_listing.

• Стан складу й замовлень: get_inventory_alerts, get_order_issues.

• Ціноутворення: get_pricing_context.

• Відкладені записи (цикл propose → preview → approve → apply): stage_listing_update, stage_price_update, stage_inventory_action, stage_promotion, stage_campaign, а також get_pending_changes, apply_change і discard_change. Реальний запис у вашу систему відбувається лише всередині apply_change — і лише для зміни, яка на той момент дійсно перебуває в статусі "відкладена".

• Опційно: execute_analysis_query + get_analysis_schema для SQL-аналітики в реальному часі, get_merchant_context.

Жоден з цих класів не прив'язаний до конкретної ERP чи іншої системи — Anthropic описує лише набір систем, які потрібно покрити (аналітика, каталог, інвентар, замовлення, ціни, кампанії), а яку саме платформу ви за ними ховаєте — вирішуєте ви.

Кожен бізнес-процес — це окремий каталог у skills/ з файлом SKILL.md усередині, де людською мовою описано логіку, послідовність викликів інструментів і критерії успіху. Claude парсить ці файли перед сесією і використовує як декларативний план дій. У базовій конфігурації в кожного агента вже є по п'ять таких навичок; додати свою можна вручну або командою /add-commerce-flow.

Філософія безпеки: чотири бар'єри

Fencing (commerce-common). Усе, що повертають методи бекенду, доходить до моделі як позначені "дані", а не інструкції — це унеможливлює ситуацію, коли опис товару чи текст політики магазину непомітно "командує" моделлю.

Provenance gates (shopping-agent/core, merchant-agent/core). Модель не може діяти щодо товару, варіанта чи замовлення, id якого вона сама не бачила раніше в цій-таки сесії — жодних вигаданих ідентифікаторів. Ті самі gates тримають ліміти кількості в кошику.

Staged changes для Merchant Agent. Коли менеджер каже "знизити ціну на 10%", агент викликає stage_price_update і отримує об'єкт StagedChange — запис лежить у черзі get_pending_changes, і жодна цифра не потрапляє у вашу live-систему, доки людина не натисне "підтвердити" в консолі чи порталі.

Checkout hand-off. Shopping Agent ніколи не бачить номер картки і не завершує транзакцію сам. Бекенд повертає посилання на ваш власний checkout або на hosted-checkout URL платформи (окреме посилання на кожного продавця, якщо це маркетплейс) — модель отримує лише готову картку для показу клієнту, сам URL до неї не потрапляє.

Чотири вертикалі як референс

retail — ACME. Сторфронт: пошук, порівняння, мультитоварні плани, кошик, checkout, пам'ять. Портал: дайджест, відкладені поповнення складу й правки лістингів, аналітичний делегат поверх SQL-подання.

travel — ACME Travel. Сторфронт: інвентар, прив'язаний до дат, розширення present_itinerary. Портал: календар завантаженості й зміна тарифів на вікна дат.

telecom — ACME Mobile. Сторфронт: контекст акаунту, матриця тарифних планів, розкриття платежів від сервера. Портал: мікс тарифів, зміни цін із зазначенням, кого вони торкнуться, захищені регуляторні збори.

entertainment — ACME Tickets. Сторфронт: тимчасові холди на квитки, списки очікування, передача квитків, карта залу, розкриття всіх комісій. Портал: темп продажів подій, звільнення холдів із реальним поповненням місткості, зміни цін, що зберігають комісії.

З чого починати: мінімальний життєздатний агент

Для Shopping Agent: реалізуйте лише search_products і get_product_details, а всі інші методи (кошик, checkout) тимчасово хай повертають статус "недоступно" — це не ламає промпт і не потребує жодних змін у конфігурації, лише повністю безпечний консультант по каталогу без ризику помилкового замовлення.

Для Merchant Agent є симетричний шлях: реалізуйте вісім read-методів (показники, каталог, склад, замовлення, ціни), а всі stage_*-методи хай відмовляють — дайджести й аналітика вже працюватимуть, а шлях запису з'явиться пізніше.

Функцію, якої у вашому бізнесі просто немає (наприклад, немає онлайн-кошика), не потрібно імітувати — вимикається прапорцем enable_* у конфігурації, і відповідні інструменти, рядки промпту й правило grounding зникають з усіх трьох шляхів запуску одночасно.

Що варто знати перед стартом

1. Це референсна реалізація, а не підтримуваний продукт. Anthropic прямо зазначає в ліцензії: репозиторій не супроводжується і не приймає зовнішніх контрибуцій. Форкати можна й потрібно, розраховувати на апдейти від Anthropic — ні.

2. Усі бренди у демо вигадані. Єдина "компанія" в прикладах — ACME (і її варіації для інших вертикалей). Жоден метод демо не оформлює реальне замовлення, не списує гроші й не змінює живий лістинг.

3. Managed Agents — у бета-статусі. Якщо потрібен максимально стабільний варіант просто зараз, безпечніше стартувати з Messages API або Agent SDK.

4. Готових MCP-конекторів до сторонніх систем репозиторій не постачає. Обидва агенти дістаються до ваших систем виключно через StorefrontBackend/MerchantBackend. Якщо у вас уже є офіційний MCP-сервер платформи (каталог, кошик, checkout), його викликають із методу бекенду на сервері — а не напряму з моделі.

Головний принцип цього репозиторію: логіка агента й бізнес-логіка застосунку живуть окремо. Модель веде розмову й вирішує, що робити; бекенд і його інтерфейси відповідають за те, щоб кожне рішення пройшло крізь правила безпеки, авторизації і транзакцій вашого бізнесу.