microdao-daarion/docs/greenfood/greenfood_agents.md

GREENFOOD Crew - Документація

Версія: 1.0.0
Дата: 2025-11-18
Статус: Ready for Development

---

Огляд

GREENFOOD Crew — це команда з 13 спеціалізованих AI-агентів для управління ERP-системою крафтових виробників продуктів харчування. Система забезпечує повний цикл від onboarding виробника до доставки товару покупцю та фінансових розрахунків.

---

Архітектура

Головний оркестратор

GREENFOOD Assistant — єдина точка входу для всіх користувачів системи. Розпізнає роль користувача, виявляє намір та делегує завдання відповідним доменним агентам.

12 доменних агентів

Агенти організовані за функціональними доменами:

🏭 Операційні агенти (Operations)

1. Product & Catalog Agent - Каталог товарів
2. Batch & Quality Agent - Партії та контроль якості
3. Warehouse Agent - Управління складами
4. Logistics & Delivery Agent - Логістика та доставка

💼 Продажі та підтримка (Sales & Support)

5. Seller Agent - Менеджер з продажу
6. Customer Care Agent - Служба підтримки

💰 Фінанси (Finance)

7. Finance & Pricing Agent - Бухгалтерія та ціноутворення

📢 Маркетинг (Marketing)

8. SMM & Campaigns Agent - Соціальні мережі та кампанії
9. SEO & Web Experience Agent - SEO та веб-досвід

📊 Аналітика та governance (Analytics & Governance)

10. Analytics & BI Agent - Аналітика даних
11. Compliance & Audit Agent - Аудит та compliance

🚀 Успіх клієнтів (Success)

12. Vendor Success Agent - Менеджер успіху комітентів

---

Ролі та відповідальність агентів

1. GREENFOOD Assistant

Роль: Фронтовий оркестратор
Мета: Розуміти користувача, виявляти намір, делегувати завдання
Ключові функції:

• Ідентифікація ролі користувача (комітент, складський, логіст, бухгалтер, маркетолог, покупець)
• Перетворення запиту на чітку дію
• Координація роботи доменних агентів
• Формування зрозумілих результатів для користувача

Делегування: Так (може делегувати іншим агентам)

---

2. Product & Catalog Agent

Роль: Менеджер каталогу товарів
Мета: Підтримувати чистий, структурований каталог без дублів
Ключові функції:

• Створення та редагування карточок товарів
• Перевірка дублікатів
• Управління атрибутами (вага, склад, алергени, строк придатності)
• Управління медіа (фото, відео)

Інструменти (TODO):

• ProductCatalogAPI
• ImageUploadTool
• DuplicateDetectorTool

---

3. Batch & Quality Agent

Роль: Менеджер партій та якості
Мета: Забезпечити трасованість партій та контроль якості
Ключові функції:

• Створення та відстеження партій товарів
• Контроль строків придатності
• Управління статусами партій (на складі, в дорозі, реалізована, прострочена)
• Фіксація інцидентів якості та рекламацій

Інструменти (TODO):

• BatchTrackingAPI
• QualityCheckTool
• ExpiryAlertTool

---

4. Vendor Success Agent

Роль: Менеджер успіху комітентів
Мета: Швидкий запуск та зростання виробників
Ключові функції:

• Onboarding нових комітентів (чеклісти, документи)
• Виявлення слабких місць (порожній каталог, відсутні фото)
• Проактивні рекомендації для покращення
• Моніторинг метрик успіху

Інструменти (TODO):

• VendorOnboardingAPI
• ChecklistTool
• RecommendationEngine

---

5. Warehouse Agent

Роль: Начальник складу
Мета: Коректні та актуальні залишки товарів
Ключові функції:

• Управління залишками товарів
• Фіксація руху товарів (прихід, переміщення, відвантаження)
• Структурування складу (зони, стелажі, температурні зони)
• Сигналізація про критичні залишки

Інструменти (TODO):

• WarehouseAPI
• InventoryTool
• StockMovementTool
• ZoneManagementTool

---

6. Logistics & Delivery Agent

Роль: Логіст і диспетчер
Мета: Мінімальні затримки та витрати на доставку
Ключові функції:

• Створення маршрутів доставки
• Управління статусами доставок
• Інтеграція з перевізниками (API)
• Формування трек-номерів

Інструменти (TODO):

• LogisticsAPI
• DeliveryTrackerTool
• CourierIntegrationTool

---

7. Seller Agent

Роль: Менеджер з продажу
Мета: Допомога в оформленні замовлень та підборі товарів
Ключові функції:

• Формування кошика замовлення
• Пропозиції альтернатив, апсели, крос-сели
• Перевірка можливості виконання замовлення
• Розуміння контексту клієнта (роздріб/опт, новий/постійний)

Інструменти (TODO):

• SalesAPI
• BasketTool
• RecommendationEngine
• PricingTool

---

8. Customer Care Agent

Роль: Служба підтримки
Мета: Швидко вирішувати проблеми клієнтів
Ключові функції:

• Ідентифікація клієнта та його замовлення
• Відповіді на питання (статус, доставка, повернення)
• Фіксація рекламацій та причин повернень
• Пропозиція наступних кроків

Інструменти (TODO):

• SupportAPI
• OrderLookupTool
• ComplaintTool
• TicketingTool

---

9. Finance & Pricing Agent

Роль: Бухгалтер і фінансовий стратег
Мета: Прозорі взаєморозрахунки та здорова економіка
Ключові функції:

• Ведення балансів учасників
• Моделі ціноутворення (опт, роздріб, акції, промокоди)
• Розрахунок комісій та виплат
• Робота з токенами (DAAR/DAARION) та фіатом

Інструменти (TODO):

• FinanceAPI
• PricingEngine
• BalanceTool
• PayoutCalculator

---

10. SMM & Campaigns Agent

Роль: Маркетолог та контент-агент
Мета: Просування товарів через цифрові канали
Ключові функції:

• Створення контенту для соцмереж, розсилок, банерів
• Перевірка наявності товарів перед промо
• Планування кампаній з чіткою метою
• Честна комунікація без маніпуляцій

Інструменти (TODO):

• ContentGeneratorTool
• CampaignAPI
• SocialMediaTool
• ImageGeneratorTool

---

11. SEO & Web Experience Agent

Роль: SEO-оптимізатор
Мета: Видимість в пошуку та зрозумілість для користувачів
Ключові функції:

• Оптимізація заголовків, описів, метаданих
• Покращення структури контенту
• Використання реальних даних про товари
• Блоки довіри, FAQ, structured data

Інструменти (TODO):

• SEOAnalyzerTool
• MetaGeneratorTool
• ContentStructureTool

---

12. Analytics & BI Agent

Роль: Аналітик даних
Мета: Перетворення даних на actionable insights
Ключові функції:

• Формування зрозумілих звітів
• Виявлення трендів, сезонності, аномалій
• Пропозиції варіантів дій із вказанням ризиків
• Роз'яснення в простих термінах

Інструменти (TODO):

• AnalyticsAPI
• ReportGeneratorTool
• TrendAnalyzerTool
• ForecastingTool

---

13. Compliance & Audit Agent

Роль: Внутрішній аудитор
Мета: Відповідність політикам та здоровій бізнес-логіці
Ключові функції:

• Аналіз логів подій (зміни цін, списання, повернення)
• Виявлення ризикових операцій
• Формування попереджень та рекомендацій
• Нейтральний, фактичний стиль

Інструменти (TODO):

• AuditLogTool
• RiskDetectorTool
• ComplianceCheckerTool

---

Команди (Crews) для бізнес-сценаріїв

1. Onboard Vendor Crew

Мета: Запуск нового комітента (виробника)
Агенти: GREENFOOD Assistant, Vendor Success, Product & Catalog, Warehouse, Finance & Pricing
Етапи:

1. Привітання та збір інформації
2. Створення карточок товарів
3. Налаштування складу та партій
4. Налаштування фінансів та ціноутворення
5. Чекліст успішного запуску

Виклик:

from services.greenfood.crew.greenfood_crews import GREENFOOD_CREWS, GREENFOOD_TASK_CREATORS

vendor_data = {
    "name": "Еко Мед Карпати",
    "products": ["Гірський мед", "Мед з липи", "Мед з акації"],
    "contact": "...",
}

tasks = GREENFOOD_TASK_CREATORS["onboard_vendor"](vendor_data)
crew = GREENFOOD_CREWS["onboard_vendor"]
crew.tasks = tasks
result = crew.kickoff()

---

2. Fulfill Order Crew

Мета: Виконання замовлення від прийняття до доставки
Агенти: GREENFOOD Assistant, Seller, Warehouse, Logistics, Customer Care, Finance & Pricing
Етапи:

1. Прийняття замовлення
2. Формування та підтвердження кошика
3. Резервація товарів на складі
4. Створення маршруту доставки
5. Фінансові проводки
6. Повідомлення клієнта

Виклик:

order_data = {
    "customer_name": "Іван Петренко",
    "items": [{"product_id": "123", "quantity": 2}],
    "delivery_address": "м. Львів, вул. Шевченка 1",
}

tasks = GREENFOOD_TASK_CREATORS["fulfill_order"](order_data)
crew = GREENFOOD_CREWS["fulfill_order"]
crew.tasks = tasks
result = crew.kickoff()

---

3. Monthly Settlement Crew

Мета: Місячні звіряння та розрахунки
Агенти: GREENFOOD Assistant, Finance & Pricing, Analytics & BI, Compliance & Audit, Vendor Success
Етапи:

1. Ініціація процесу звіряння
2. Формування аналітичних звітів
3. Розрахунок фінансових показників та актів звіряння
4. Audit та виявлення ризиків
5. Персоналізовані рекомендації комітентам

Виклик:

period_data = {
    "period": "2025-11",
    "vendors": ["vendor_1", "vendor_2"],
}

tasks = GREENFOOD_TASK_CREATORS["monthly_settlement"](period_data)
crew = GREENFOOD_CREWS["monthly_settlement"]
crew.tasks = tasks
result = crew.kickoff()

---

4. Marketing Campaign Crew (додатковий)

Мета: Запуск маркетингової кампанії
Агенти: GREENFOOD Assistant, Warehouse, SMM & Campaigns, SEO & Web, Finance & Pricing, Analytics & BI
Етапи:

1. Прийняття запиту на кампанію
2. Перевірка наявності товарів
3. Створення контенту
4. SEO-оптимізація посадкових сторінок
5. Налаштування цін та промокодів
6. Налаштування відстеження KPI

---

Зв'язки між агентами

Найчастіші взаємодії

GREENFOOD Assistant (центральний хаб)
    ├── Product & Catalog ←→ Batch & Quality
    ├── Warehouse ←→ Logistics & Delivery
    ├── Warehouse ←→ Batch & Quality
    ├── Seller ←→ Warehouse
    ├── Seller ←→ Finance & Pricing
    ├── Customer Care ←→ Logistics
    ├── SMM & Campaigns ←→ Warehouse
    ├── SMM & Campaigns ←→ SEO & Web
    ├── Analytics & BI ←→ (всі агенти)
    ├── Compliance & Audit ←→ (всі агенти)
    └── Vendor Success ←→ (всі агенти)

---

Інтеграція з DAGI Router

Додавання в router-config.yml

agents:
  greenfood:
    description: "GREENFOOD Assistant - ERP orchestrator"
    default_llm: local_qwen3_8b
    system_prompt: |
      Ти — GREENFOOD Assistant, фронтовий оркестратор ERP-системи...

Виклик через Router

from router_client import send_to_router

response = await send_to_router({
    "mode": "crew",
    "agent": "greenfood",
    "message": "Онбордь нового комітента 'Еко Мед Карпати'",
    "metadata": {
        "scenario": "onboard_vendor",
        "vendor_data": {...},
    },
})

---

Файлова структура

services/greenfood/
├── __init__.py
└── crew/
    ├── __init__.py
    ├── greenfood_prompts.py      # 13 системних промтів
    ├── greenfood_agents.py       # 13 агентів
    └── greenfood_crews.py        # 4 crews + task creators

---

Наступні кроки

Фаза 1: Базова інтеграція

• Підключити GREENFOOD Assistant до DAGI Router
• Протестувати базовий діалог
• Додати інструменти (tools) для агентів

Фаза 2: Інструменти та API

• Реалізувати ProductCatalogAPI
• Реалізувати WarehouseAPI
• Реалізувати FinanceAPI
• Додати інтеграції з зовнішніми сервісами

Фаза 3: Crews та workflows

• Протестувати onboard_vendor_crew
• Протестувати fulfill_order_crew
• Протестувати monthly_settlement_crew
• Додати monitoring та logging

Фаза 4: UI та UX

• Web-інтерфейс для комітентів
• Дашборди для різних ролей
• Mobile app для складських та логістів
• Інтеграція з Telegram для швидких запитів

---

Контакти та підтримка

Репозиторій: /Users/apple/github-projects/microdao-daarion
Модуль: services/greenfood/crew
Версія crewAI: 0.28.0+
Python: 3.11+

---

Документ створено: 2025-11-18
Останнє оновлення: 2025-11-18