MAS Customer Support System (Final Assignment №3)

Підсумкова мультиагентна система (MAS) підтримки клієнтів, побудована на базі LangGraph та FastMCP з використанням LLM gpt-5.4-mini[cite: 1]. Проєкт поєднує перевикористані компоненти з попередніх етапів розробки (Pydantic tools, TrajectoryLogger, Plan-and-Execute, SqliteSaver) із новими механізмами MCP-протоколу, багаторівневими Guardrails, HITL-підтвердженнями та модулями Observability/Red-Teaming[cite: 1, 2, 3].

📁 Структура проєкту

. ├── .env # Конфігурація API-ключів та трейсингу ├── .gitignore # Ігнорування секретів, баз даних та кешу ├── requirements.txt # Залежності проєкту (pip install) ├── tools.py # Pydantic tools та базові функції (з ДЗ1/ДЗ2) ├── trajectory_logger.py # Логування траєкторій із полем agent_name (з ДЗ1) ├── guardrails.py # Input, Output, Tool та Rate-Limit захист (Завд. 4) ├── mcp_server.py # FastMCP сервер: Tools, Resources, Prompts (Завд. 3) ├── test_mcp_server.py # Async Unit-тести для MCP-сервера (Завд. 3) ├── mas_langgraph.py # Основний LangGraph Supervisor MAS + Checkpointer (Завд. 1) ├── hitl.py # Сценарії Human-in-the-Loop підтверджень (Завд. 4) ├── evals.py # Scenario-based оцінка якості та pass-rate (Завд. 5) ├── red_team.py # Adversarial Red-Teaming тести (Завд. 5) ├── mas_crewai.py # Альтернативна реалізація у CrewAI (Завд. 2 - Бонус) ├── trajectory.json # Лог траєкторій виконання агентів (автогенерація) ├── eval_results.json # Результати тестування evals (автогенерація) └── red_team_results.json # Результати тестування red-team (автогенерація)

🚀 Послідовний порядок запуску

Крок 1. Створення віртуального середовища та встановлення залежностей

У терміналі виконайте створення та активацію ізольованого середовища Python:

python -m venv venv

Активація для macOS/Linux:

source venv/bin/activate

Активація для Windows PowerShell:

.\venv\Scripts\Activate.ps1

Встановлення всіх залежностей:

pip install -r requirements.txt

Крок 2. Налаштування .env файлу

Створіть у корені проєкту файл .env та додайте ваші ключі доступу:

OPENAI_API_KEY=your_openai_api_key_here LANGCHAIN_TRACING_V2=true LANGCHAIN_ENDPOINT=https://api.smith.langchain.com LANGCHAIN_API_KEY=your_langsmith_api_key_here LANGCHAIN_PROJECT=mas-support-system

Крок 3. Перевірка MCP Сервера (Завдання 3)

Запустіть асинхронні unit-тести для перевірки примітивів FastMCP (Tools, Resources, Prompts)[cite: 1]:

pytest test_mcp_server.py python test_mcp_server.py

Крок 4. Запуск перевірки Guardrails Self-Tests (Завдання 4)

Перевірте функціональність Input injection detection, PII redaction, Tool allowlist та Rate Limiter[cite: 1]:

python guardrails.py

Крок 5. Виконання основного MAS у LangGraph (Завдання 1)

Запустіть графову систему із Supervisor-маршрутизацією між агентами (billing, tech, researcher)[cite: 1]:

python mas_langgraph.py

Крок 6. Демонстрація Human-in-the-Loop (Завдання 4)

Протестуйте сценарії переривання execution-потоку interrupt() для ризикових дій (повернення коштів)[cite: 1, 2]:

python hitl.py

Крок 7. Запуск автоматизованих Evals та Red-Teaming (Завдання 5)

Проженіть сценарії тестування якості та аналізу стійкості до атак[cite: 1]:

python evals.py python red_team.py

Крок 8. Запуск порівняльного CrewAI проєкту (Бонусне Завдання 2)

Запустіть аналогічний кейс, реалізований у фреймворку CrewAI[cite: 1]:

python mas_crewai.py

🛡 OWASP ASI 2026 Mitigation Matrix (Усі 10 ризиків)

| ASI Risk Code | Назва ризику за OWASP 2026 | Статус / Механізм мітигації у проєкті | | :--- | :--- | :--- | | ASI01 | Agent Goal Alignment Failure | Мітиговано: Строгий Supervisor із Pydantic-схемою RouteDecision для виключення невизначеності напрямку дій[cite: 1]. | | ASI02 | Tool Misuse & Abuse | Мітиговано: tool_allowlist_guardrail, що обмежує доступні tools суворо відповідно до ролі агента[cite: 1]. | | ASI03 | Identity & Privilege Abuse | Мітиговано: HITL approval gate через interrupt() для дій із фінансовим впливом (refund_order)[cite: 1, 2]. | | ASI04 | Agentic Supply Chain Vulnerabilities | Мітиговано: Ізоляція виконання інструментів у FastMCP-сервері окремим процесом через stdio[cite: 1]. | | ASI05 | Unexpected System Cascades | Мітиговано: Відстеження кроків через step_count, обмеження max_steps та зупинка зациклень[cite: 1, 3]. | | ASI06 | Memory & State Poisoning | Мітиговано: Чітка сесійна ізоляція стану в SqliteSaver за thread_id[cite: 1, 2]. | | ASI07 | Direct & Indirect Prompt Injection | Мітиговано: input_injection_guardrail з перевіркою регулярних виразів на вході Supervisor[cite: 1]. | | ASI08 | Exfiltration of Sensitive Data | Мітиговано: output_pii_redaction маскує email, номери телефонів та платіжних карток перед виводом[cite: 1]. | | ASI09 | Resource Exhaustion (DoS) | Мітиговано: RateLimiter контролює часові вікна запитів per session[cite: 1]. | | ASI10 | Lack of Observability & Auditability | Мітиговано: Повне логування кожного кроку в trajectory.json через MASTrajectoryLogger + LangSmith tracing[cite: 1, 3]. |

Що залишилось немітигованим:

1. Adversarial Audio/Multimodal Injection: Захист реалізований для текстового вводу; мультимодальні ін'єкції потребують окремого шару обробки.
2. Distributed Rate Limiting: RateLimiter реалізований in-memory (для production потрібен розподілений кеш Redis).

📊 Порівняння LangGraph vs CrewAI

| Критерій | LangGraph | CrewAI | | :--- | :--- | :--- | | Парадигма контролю (Control Flow) | Графова архітектура із явним контролем станів, умовних переходів та циклів[cite: 1]. | Рольова парадигма із більш автономним та секвенційним/ієрархічним виконанням[cite: 1]. | | Гнучкість стану (State Management) | Повний контроль над глобальним та локальним станом через TypedDict / Pydantic[cite: 1]. | Контекст передається між задачами (Tasks), стан агента прихований у внутрішній логіці. | | Підтримка HITL (Human-in-the-Loop) | Нативна підтримка переривань interrupt() та збереження стейту через Checkpointers[cite: 1, 2]. | Потребує власної обгортки або використання стандартного консольного підтвердження. | | Стандартизація MCP | Пряма інтеграція через langchain-mcp-adapters (MultiServerMCPClient)[cite: 1]. | Інтеграція через кастомні інструменти (Tools) або додаткові адаптери. | | Складність розробки | Вищий поріг входження, вимагає точного проектування графа та вузлів. | Швидкий старт для простих мультиагентних команд з описом ролей та задач. |

Запити і виводи програми

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python -m pytest test_mcp_server.py ================================= test session starts ================================== platform darwin -- Python 3.13.9, pytest-9.1.1, pluggy-1.6.0 rootdir: /Users/alexandrnechayevski/Downloads/FP_MAS plugins: asyncio-1.4.0, anyio-4.14.2, langsmith-0.11.2 asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function collected 3 items

test_mcp_server.py ... [100%]

================================== 3 passed in 0.60s =========================

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python guardrails.py

Всі guardrails self-tests успішно пройдено!

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python mas_langgraph.py --- Запуск 1: Researcher --- /Users/alexandrnechayevski/Downloads/FP_MAS/mas_langgraph.py:60: PydanticDeprecatedSince20: The dict method is deprecated; use model_dump instead. Deprecated in Pydantic V2.0 to be removed in V3.0. See Pydantic V2 Migration Guide at https://errors.pydantic.dev/2.12/migration/ logger.log_step("Supervisor", "routing", last_msg, decision.dict()) Відповідь: Знайдено інформацію: Згідно з FAQ: Повернення товару можливе протягом 14 днів при наявності чеку.

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python hitl.py

--- Запуск HITL Сценарію ---

[INTERRUPT DETECTED]: Потрібне підтвердження повернення коштів для запиту: 'Зробіть повернення коштів за замовлення ORD-12345 на сумму 150$'

Сценарій A: Схвалення (Approve) Результат: Операцію схвалено оператором. Результат: {"status": "success", "message": "\u041f\u043e\u0432\u0435\u0440\u043d\u0435\u043d\u043d\u044f \u043a\u043e\u0448\u0442\u0456\u0432 \u0443 \u0440\u043e\u0437\u043c\u0456\u0440\u0456 $150.0 \u0437\u0430 \u0437\u0430\u043c\u043e\u0432\u043b\u0435\u043d\u043d\u044f\u043c ORD-12345 \u0443\u0441\u043f\u0456\u0448\u043d\u043e \u0432\u0438\u043a\u043e\u043d\u0430\u043d\u043e."}

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python evals.py Evals завершено! Pass-rate: 100.0%. Результати у eval_results.json

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python red_team.py Red-teaming завершено! Blocked rate: 60.0%. Результати у red_team_results.json

(venv) (base) alexandrnechayevski@MacBook-Air-Admin FP_MAS % python mas_crewai.py

CrewAI MAS успішно сконфігуровано.