Корпоративный ИИ-чат-агент

Внутренний ассистент: многоходовой чат, плюс инструменты файловой системы, предоставляемые настоящим MCP-сервером, который подключается только когда реально задействован файл.

• Архитектура и обоснование → WRITEUP.md

• Соглашения, ограничения, журнал решений → CLAUDE.md

• Дословные промпты, использованные для его создания → PROMPTS.md

Что нужно установить и в каком порядке

Проект работает сам по себе. Трейсы и поведенческие оценки — это два отдельных необязательных слоя, каждый со своими предварительными требованиями — ни один из них не нужен, чтобы увидеть работу агента. Выберите уровень и остановитесь на нём.

Уровни 2 и 3 независимы — можно сделать любой, оба или ни одного. Ничто в уровне 1 не сломается, если Docker или Node отсутствуют.

Related MCP server: Files MCP Server

Уровень 1 — Ядро (обязательно)

Требования

Точные версии указаны в requirements.txt; диапазоны — в pyproject.toml.

Почему mcp удерживается ниже 2.0.0: MCP Python SDK v2 переименовал FastMCP в MCPServer и удалил модуль mcp.server.fastmcp. langchain-mcp-adapters 0.3.2 объявляет ту же верхнюю границу, поэтому их нельзя установить вместе выше неё. Пин делает неявное ограничение явным; это не понижение версии.

Запуск

# 0. clone
git clone https://github.com/Semmargl/enterprise-ai-chat-agent.git
cd enterprise-ai-chat-agent

# 1. environment
python3 -m venv .venv                 # or: uv venv --python 3.14
source .venv/bin/activate             # Windows: .venv\Scripts\activate
pip install -r requirements.txt       # or: uv pip install -r requirements.txt

# 2. secrets
cp .env.example .env
# then open .env and put your OpenRouter key in OPENROUTER_API_KEY

# 3. sample files to play with (the working folder starts empty)
mkdir -p workspace && cp samples/* workspace/

# 4. check the wiring before spending a token
pytest -q                             # expect: 44 passed, <1s, no network needed

# 5. start
python -m src.main

Контрольная точка: агент приветствует вас в зависимости от времени суток и отвечает на вопрос. Если шаг 4 вывел 44 passed, песочница, окно памяти и видимость инструментов проверены без единого вызова API.

Агент ведёт обычный разговор и подключается к файловому сервису при первом запросе файла.

python -m src.main --thread report   # a separate, named conversation

Выйдите с помощью exit. Запустите снова с тем же --thread — разговор продолжится: состояние сохраняется в SQLite, а не в памяти.

Два способа запуска MCP-сервера

Обратите внимание на два «значения по умолчанию»: код возвращается к 0, когда переменная не задана, а .env.example поставляется с MCP_AUTOSTART=1, чтобы чистая копия работала без второго терминала. Скопируйте шаблон — получите автозапуск; разверните без .env — получите продакшн-форму.

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

Что стоит попробовать

Что искать в логах

Логи — JSON, одна строка на событие, в stderr. Ключи correlation_id (один пользовательский ход) и thread_id (один разговор) связывают их вместе.

var/audit.jsonl — журнал аудита: одна строка на вызов инструмента с результатом и длительностью. Он записывает пути, размеры и хэши — никогда содержимое файлов, никогда секреты.

Он находится в var/, а не в workspace/, намеренно: собственные файловые инструменты агента достигают любого пути в корне песочницы, поэтому журнал аудита, хранящийся там, мог бы быть изменён процессом, который он записывает. База данных контрольных точек (var/checkpoints.sqlite) вынесена по той же причине — это память агента, а не его рабочее пространство. При запуске отклоняется конфигурация, которая помещает любой из них обратно в песочницу.

Уровень 2 — Трейсы в Phoenix (опционально)

Предварительное требование: Docker. Пропустите весь этот раздел, если у вас его нет — агенту он не нужен. По умолчанию OTEL_EXPORTER=none, поэтому чистая копия работает без какого-либо коллектора.

Инструментарий — OpenTelemetry с семантикой OpenInference, поэтому спаны описывают вызовы LLM и инструментов, а не общую HTTP-работу. Экспортёр — переменная окружения, а не путь в коде — замена Phoenix на любой другой OTLP-бэкенд — это одна переменная, а не рефакторинг.

# 1. start Phoenix (first run pulls the image, ~1-2 min)
docker run -d --name phoenix -p 6006:6006 -p 4317:4317 arizephoenix/phoenix

# 2. wait for it, then confirm it answers
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6006    # expect: 200

# 3. run the agent pointed at it — two turns, one plain and one about a file
OTEL_EXPORTER=otlp OTEL_ENDPOINT=http://127.0.0.1:6006/v1/traces \
  python -m src.main --thread traces

Контрольная точка: откройте http://localhost:6006. Два хода дают два трейса. Откройте файловый — вызов инструмента вложен в цикл create_agent, под вызовом модели. Эта вложенность и есть суть: это поток управления агента, а не плоский список HTTP-запросов.

# when finished
docker stop phoenix && docker rm phoenix

Не используйте OTEL_EXPORTER=console ни для чего, кроме локальной отладки: эти спаны печатают весь промпт и каждый результат инструмента — то есть содержимое файлов, которое журнал аудита намеренно никогда не хранит.

Уровень 3 — Поведенческие оценки (опционально)

Предварительное требование: Node 18+. Пропустите, если отсутствует; pytest уже покрывает всё детерминированное.

pytest покрывает то, что можно проверить без сети: ограничение путей, арифметику окна, видимость инструментов. Что он не может покрыть — так это поведение системы после реального девятиходового разговора с реальной моделью. Эти три случая находятся в promptfooconfig.yaml и запускаются против фактического агента — не против голой модели — через scripts/promptfoo_provider.py.

# 1. install
npm i -g promptfoo@latest

# 2. the venv must be active and .env filled in — the provider spawns the real agent
source .venv/bin/activate

# 3. run
NODE_NO_WARNINGS=1 PROMPTFOO_DISABLE_TELEMETRY=1 PROMPTFOO_DISABLE_UPDATE=1 \
  promptfoo eval -o results.json; echo "EXIT=$?"

# 4. browse the results (optional)
promptfoo view

Контрольная точка: EXIT=0, и results.json содержит "successes": 3, "failures": 0, "errors": 0. Полный прогон занимает 40–60 секунд — это девять реальных ходов плюс два одноходовых разговора.

Две вещи, которые выглядят как сбои, но не являются ими. Индикатор прогресса может казаться застрявшим на 0% | 0/3: Node записывает предупреждение в ту же строку терминала и перезаписывает её. Судите по EXIT и JSON, а не по индикатору. И assertions.cached > 0 при повторном запуске — это оценщик кэширует свои собственные вызовы — сами разговоры агента никогда не кэшируются. Добавьте --no-cache для полностью холодного запуска.

Это стоит токенов. Три случая, всего одиннадцать ходов, плюс LLM-оценщик для рубричных утверждений — всё на том же OPENROUTER_API_KEY из вашего .env.

Конфигурация

Каждый параметр задокументирован в .env.example. Те, что сильнее всего меняют поведение: MCP_AUTOSTART, SANDBOX_ROOT, MAX_FILE_BYTES, HISTORY_WINDOW_MESSAGES, SUMMARIZATION_TRIGGER_MESSAGES, OTEL_EXPORTER.

.env находится в .gitignore с первого коммита и никогда не был закоммичен:

git log --all --full-history -- .env    # returns nothing