SAP SuccessFactors Multi-Agent MCP Prototype

Демонстрация с использованием синтетических данных в стиле SuccessFactors. Это образовательный прототип только для чтения, а не система SAP SuccessFactors и не готов к производству.

Приложение отвечает на авторизованные HR-вопросы через узкую границу инструментов MCP. Режим Mock не требует учетных данных SAP или OpenAI. Режим Demo добавляет необязательную оркестрацию OpenAI Agents SDK; реальный режим зарезервирован для явно настроенного непроизводственного тенанта SuccessFactors.

Возможности

• Одиннадцать типизированных инструментов MCP только для чтения; нет произвольного HTTP, OData или поверхности записи.

• Четыре синтетические учетные записи с серверными ролями и областями охвата.

• Явные списки разрешений для сущностей и полей, а также санитизация ответов по принципу запрета по умолчанию.

• Десять вымышленных сотрудников, двенадцать должностей, базовые объекты, история с датами вступления в силу, вакансии и намеренные проблемы с качеством данных.

• Структурированный журнал аудита SQLite без полных HR-нагрузок или секретов.

• FastAPI чат/аудит API и интерфейс Streamlit, ориентированный на доказательства.

• Детерминированный мок-чат работает без ключа API.

Related MCP server: HRIS MCP Connector

Настройка Windows (основной путь)

cd .\successfactors-mcp-prototype
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup_windows.ps1

Запустите все сервисы:

.\scripts\run_all_windows.ps1

Или используйте три терминала:

.\scripts\run_mcp_windows.ps1
.\scripts\run_backend_windows.ps1
.\scripts\run_ui_windows.ps1

run_ui_windows.ps1 автоматически запускает FastAPI в фоновом режиме, если бэкенд еще не запущен, поэтому его также можно использовать как самый простой запускатель мок-интерфейса одной командой.

• UI: http://127.0.0.1:8501

• API: http://127.0.0.1:8000

• OpenAPI: http://127.0.0.1:8000/docs

• MCP: http://127.0.0.1:8001/mcp

Unix и VS Code

Запустите bash scripts/setup_unix.sh, затем bash scripts/run_all_unix.sh. В VS Code выберите .venv в качестве интерпретатора Python и при необходимости откройте три терминала.

Конфигурация и режимы

Скопируйте .env.example в .env; заполнители не содержат секретов.

• APP_MODE=mock: синтетический провайдер и детерминированный чат; внешние учетные данные не требуются.

• APP_MODE=demo: синтетический провайдер с живой оркестрацией Agents SDK; требует OPENAI_API_KEY и MCP_INTERNAL_TOKEN.

• APP_MODE=real: только настроенный тестовый тенант. Отсутствующие настройки приводят к сбою запуска; резервного мок-режима нет.

OPENAI_MODEL централизует выбор модели. Диапазоны зависимостей нацелены на Python 3.11 и текущие совместимые основные версии, избегая непроверенных крупных обновлений.

Живая демонстрация Agents SDK

Скопируйте .env.example в .env, затем установите следующие значения:

APP_MODE=demo
OPENAI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=your-key-from-a-secret-store
MCP_INTERNAL_TOKEN=a-long-random-local-secret

Не коммитьте .env. run_ui_windows.ps1 теперь запускает MCP-сервер и FastAPI при необходимости. Приложение передает пользователя, сессию и корреляционную идентичность в MCP через защищенные HTTP-заголовки; эти поля отсутствуют в схемах инструментов, вызываемых моделью. Специалисты получают жестко заданные списки разрешенных инструментов. Трассировка интерфейса записывает только имена жизненного цикла агента/инструмента, а не подсказки, аргументы, результаты или приватные рассуждения.

Контроль затрат настраивается с помощью DEMO_MAX_TURNS, DEMO_MAX_OUTPUT_TOKENS и DEMO_DAILY_TOKEN_BUDGET. Установите OPENAI_INPUT_COST_PER_1M и OPENAI_OUTPUT_COST_PER_1M на текущие тарифы для выбранной модели, чтобы отображать локальную оценку. Трассировка OpenAI по умолчанию выключена, и при включении конфиденциальное содержимое трассировки остается отключенным.

Обычный набор тестов никогда не вызывает OpenAI. Чтобы запустить единственный добровольный живой смоук-тест делегирования после запуска всех трех сервисов в демо-режиме:

$env:RUN_LIVE_AGENT_TESTS="true"
.\.venv\Scripts\python.exe -m pytest -m live -q

Этот тест выполняет один реальный запрос к API и, следовательно, приводит к использованию модели.

Проверка

python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest

Настройка аутентификации для реального тестового тенанта

1. Зарегистрируйте OAuth-клиент в API Center SuccessFactors.

2. Создайте выделенного пользователя API.

3. Назначьте минимально необходимые разрешения на запросы RBP.

4. Ограничьте целевую популяцию.

5. Предоставьте доступ к запросам только для одобренных сущностей и полей.

6. Храните материалы OAuth вне системы контроля версий.

7. Проверьте подписанный поток OAuth для конкретного тенанта на непроизводственном тенанте.

8. Проверьте сценарии как разрешенных, так и запрещенных сотрудников.

Базовая аутентификация не поддерживается. Включенный интерфейс реального поставщика токенов намеренно не работает, пока не будет реализован и проверен специфичный для тенанта поток, документированный SAP.

Docker

После копирования .env.example в .env выполните docker compose up --build. Docker необязателен, а файл compose предназначен только для разработки и не защищен для производства.

Устранение неполадок и ограничения

• Если интерфейс сообщает о недоступности бэкенда, сначала запустите FastAPI.

• Если привязка порта не удается, остановите процесс, использующий порт 8000, 8001 или 8501.

• Селектор пользователя прототипа не является производственной аутентификацией.

• SQLite не предназначен для горизонтально масштабируемого производственного хранилища аудита.

• Реальный OAuth, особенности метаданных тенанта и поведение RBP требуют проверки тенанта.

• Мок-маршрутизация намеренно поддерживает предоставленные демонстрационные шаблоны вопросов; это не универсальный движок обработки естественного языка.

• Будущие записи требуют отдельной одобренной архитектуры и отсутствуют даже в виде заглушек.

Подробный поток и границы доверия см. в ARCHITECTURE.md; контроль и риски — в SECURITY.md. Точные синтетические записи и руководство по сценариям описаны в TEST_DATA.md и экспортированы в test_data/.