Как встроить автономных ИИ-агентов в экосистему ecommerce: от умного поиска товаров до автоматической обработки возвратов и предиктивной аналитики продаж.
Ядро ecommerce-агента — это мультитуловая система, способная взаимодействовать с API магазина, базой товаров, CRM и платёжными шлюзами. Агент получает запрос пользователя на естественном языке, определяет интент (поиск товара, оформление заказа, возврат, вопрос о доставке), вызывает нужные инструменты и возвращает структурированный ответ. Ключевое отличие от обычного чат-бота — способность к многошаговым рассуждениям (ReAct-паттерн) и автономному выполнению действий.
# Архитектура агента интернет-магазина from dataclasses import dataclass from typing import List, Optional, Callable, Dict @dataclass class Tool: """Инструмент, доступный агенту""" name: str description: str parameters: Dict handler: Callable @dataclass class EcommerceAgent: """Основной класс агента магазина""" llm: object # OpenAI / Anthropic клиент tools: List[Tool] # Доступные инструменты memory: object # Векторная БД для контекста max_steps: int = 10 # Макс. шагов ReAct-цикла
Первый и самый важный инструмент — семантический поиск по каталогу. Вместо жёсткого поиска по ключевым словам мы используем эмбеддинги товаров (название + описание + характеристики), сохраняя их в векторную базу. Это позволяет агенту находить товары по размытым запросам вроде «что-то лёгкое для бега летом».
import json import numpy as np from openai import OpenAI client = OpenAI() # Загрузка каталога и индексация в векторную БД def index_products_to_chroma(products: list, collection): """Индексирует товары: название + описание → embedding → ChromaDB""" for i, product in enumerate(products): text = f"{product['name']}. {product['description']}. {product['category']}" embedding = get_embedding(text) collection.add( ids=[f"prod_{i}"], embeddings=[embedding], metadatas=[{"name": product["name"], "price": product["price"]}], documents=[text] ) def semantic_search(query: str, collection, top_k=5) -> list: """Семантический поиск: запрос → embedding → ближайшие товары""" query_emb = get_embedding(query) results = collection.query(query_embeddings=[query_emb], n_results=top_k) return [ {"name": m["name"], "price": m["price"], "score": round(1-d, 3)} for m, d in zip(results["metadatas"][0], results["distances"][0]) ] def get_embedding(text: str) -> list: resp = client.embeddings.create(model="text-embedding-3-small", input=text) return resp.data[0].embedding
Паттерн ReAct (Reasoning + Acting) позволяет агенту чередовать размышления и вызовы инструментов. На каждом шаге агент анализирует контекст, решает, какой инструмент вызвать, и интерпретирует результат. Цикл продолжается до получения финального ответа или исчерпания лимита шагов.
def react_loop(agent, user_message: str) -> str: """ReAct-цикл: думаем → действуем → наблюдаем → ... → отвечаем""" messages = [ {"role": "system", "content": build_system_prompt(agent.tools)}, {"role": "user", "content": user_message} ] for step in range(agent.max_steps): response = agent.llm.chat.completions.create( model="gpt-4o", messages=messages, tools=format_tools(agent.tools), tool_choice="auto" ) msg = response.choices[0].message # Если финальный ответ — возвращаем if not msg.tool_calls: return msg.content # Иначе выполняем вызов инструмента messages.append(msg) for tc in msg.tool_calls: result = execute_tool(agent.tools, tc) messages.append({ "role": "tool", "tool_call_id": tc.id, "content": json.dumps(result) }) return "Извините, запрос слишком сложный. Уточните, пожалуйста."
Агент должен уметь не только искать, но и оформлять заказы. Инструмент create_order принимает ID товара, количество и адрес доставки, вызывает API магазина (например, WooCommerce REST API или Shopify Admin API), создаёт заказ и возвращает его статус с трек-номером.
import requests from requests.auth import HTTPBasicAuth # WooCommerce REST API конфигурация WC_URL = "https://myshop.com/wp-json/wc/v3" WC_KEY = "ck_xxxx" WC_SECRET = "cs_xxxx" def create_order(product_id: int, quantity: int, address: str) -> dict: """Создаёт заказ через WooCommerce REST API""" payload = { "payment_method": "bacs", "billing": {"address_1": address}, "line_items": [{"product_id": product_id, "quantity": quantity}] } resp = requests.post( f"{WC_URL}/orders", auth=HTTPBasicAuth(WC_KEY, WC_SECRET), json=payload, timeout=15 ) resp.raise_for_status() order = resp.json() return { "order_id": order["id"], "status": order["status"], "total": order["total"], "currency": order["currency"] } # Пример использования: create_order(product_id=142, quantity=2, address="ул. Ленина 10") # Вывод: {"order_id": 10583, "status": "processing", "total": "4990.00", "currency": "RUB"}
ИИ-агент использует историю покупок и просмотров пользователя для генерации персонализированных рекомендаций. Данные о поведении сохраняются в ChromaDB, и при каждом визите агент извлекает релевантный контекст. На основе этого LLM генерирует рекомендации с объяснением, почему конкретный товар подходит пользователю.
def get_personalized_recommendations(user_id: str, collection, llm) -> str: """Генерирует персонализированные рекомендации на основе истории""" # Извлекаем историю пользователя из ChromaDB user_history = collection.get( where={ "user_id": user_id }, limit=20 ) purchased = [m["name"] for m in user_history.get("metadatas", [])] # Формируем промпт для LLM prompt = f"""Пользователь ранее покупал: {', '.join(purchased)}. Предложи 3 товара, которые могут его заинтересовать. Для каждого объясни причину рекомендации в 1 предложении. Формат: 📦 Название — Цена — Причина""" resp = llm.chat.completions.create( model="gpt-4o", temperature=0.7, messages=[{"role": "user", "content": prompt}] ) return resp.choices[0].message.content # Пример вывода: # 📦 Кроссовки Nike Air Max — 12 990 ₽ — Вы покупали похожие беговые модели # 📦 Спортивные носки 3 пары — 890 ₽ — Часто покупают вместе с кроссовками # 📦 Фитнес-браслет Xiaomi — 4 490 ₽ — Дополнит вашу коллекцию спортивных товаров
Агент обрабатывает запросы на возврат: находит заказ по номеру, проверяет сроки возврата (обычно 14 дней), создаёт заявку в CRM и генерирует трек-номер для отправки. При эскалации — передаёт оператору с полным контекстом диалога.
from datetime import datetime, timedelta def process_return(order_id: int, reason: str, crm_client) -> dict: """Обрабатывает запрос на возврат товара""" # 1. Получаем заказ order = crm_client.get_order(order_id) if not order: return {"error": "Заказ не найден"} # 2. Проверяем сроки (14 дней с доставки) delivered = datetime.fromisoformat(order["delivered_at"]) if datetime.now() - delivered > timedelta(days=14): return {"status": "rejected", "reason": "Срок возврата истёк (14 дней)"} # 3. Создаём заявку на возврат в CRM rma = crm_client.create_rma( order_id=order_id, reason=reason, refund_amount=float(order["total"]) ) # 4. Генерируем трек-номер для отправки track_number = f"RMA-{order_id}-{datetime.now().strftime('%Y%m%d')}" return { "status": "approved", "rma_id": rma["id"], "track_number": track_number, "refund": order["total"], "instructions": "Упакуйте товар и отправьте по адресу склада с трек-номером" }
Агент может прогнозировать спрос и предупреждать о необходимости пополнения склада. Используя исторические данные продаж, он строит скользящее среднее и сигнализирует, когда остаток товара опускается ниже порога, рассчитанного на основе среднего дневного спроса и времени поставки.
def predict_stockout(product_id: int, sales_history: list, lead_time_days=7) -> dict: """Прогнозирует дефицит товара на основе истории продаж""" if len(sales_history) < 7: return {"warning": "Недостаточно данных для прогноза"} # Скользящее среднее за последние 7 дней recent = sales_history[-7:] avg_daily = sum(recent) / len(recent) trend = (recent[-1] - recent[0]) / len(recent) # дневной тренд # Прогноз спроса на период поставки predicted_demand = (avg_daily + trend * lead_time_days/2) * lead_time_days safety_stock = avg_daily * 3 # страховой запас на 3 дня reorder_point = int(predicted_demand + safety_stock) current_stock = get_stock(product_id) return { "product_id": product_id, "current_stock": current_stock, "reorder_point": reorder_point, "action": "🟡 ПОПОЛНИТЬ" if current_stock < reorder_point else "🟢 Достаточно", "suggested_order": max(0, reorder_point * 2 - current_stock) } # Вывод: {'product_id': 142, 'current_stock': 15, 'reorder_point': 42, # 'action': '🟡 ПОПОЛНИТЬ', 'suggested_order': 69}
Финальный шаг — развернуть агента как микросервис. Используем FastAPI для HTTP-эндпоинта, подключаем вебхук Telegram для приёма сообщений из магазинного чата, и добавляем мониторинг через логирование вызовов инструментов.
from fastapi import FastAPI, Request from contextlib import asynccontextmanager import uvicorn app = FastAPI() agent: EcommerceAgent = None @asynccontextmanager async def lifespan(app: FastAPI): global agent agent = EcommerceAgent( llm=OpenAI(), tools=load_tools(), memory=init_chromadb() ) yield @app.post("/webhook/telegram") async def telegram_webhook(request: Request): data = await request.json() message = data.get("message", {}).get("text", "") user_id = str(data["message"]["from"]["id"]) reply = agent.react_loop(user_id, message) return {"text": reply} if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=8080)
Мы построили полноценного ИИ-агента для интернет-магазина. Агент умеет: выполнять семантический поиск товаров через векторную БД, оформлять заказы через WooCommerce/Shopify API, генерировать персонализированные рекомендации на основе истории покупок, обрабатывать возвраты с автоматической проверкой сроков и созданием RMA-заявок, а также прогнозировать дефицит товаров на складе. Решение развёрнуто на FastAPI с вебхуком Telegram — клиенты общаются с агентом прямо в мессенджере. Следующий шаг — подключить платёжный шлюз (Stripe/YooKassa) для полной автоматизации оплаты и добавить A/B-тестирование рекомендаций для повышения конверсии.