📦 ParcelPilot AI

Интеллектуальный агент для операционной поддержки клиентов, созданный с использованием LangGraph, MCP, Agentic RAG и Streamlit.

ParcelPilot AI умеет получать информацию о клиентах/учётных записях/заказах/тикетах, отвечать на вопросы по политикам с помощью гибридного поиска, применять индивидуальные соглашения с клиентами и требовать подтверждения перед операциями, изменяющими состояние.

✨ Возможности

• Оркестрация агента на основе LangGraph

• Удалённый FastMCP-сервер по Streamable HTTP

• 9 MCP-инструментов для операций поддержки клиентов

• Гибридный Agentic RAG на базе Chroma + BM25

• Поиск по индивидуальным соглашениям с клиентами

• Обработка авторитетности источников и приоритетов документов

• Структурированные данные Excel по учётным записям, заказам и тикетам

• Имитация контроля доступа на основе ролей

• Подтверждение человеком-в-контуре для эскалаций и последующих действий

• Интерфейс Streamlit для взаимодействия с агентом

Related MCP server: Enterprise MCP Gateway

🏗️ Архитектура

                    ┌─────────────────────┐
                    │   Streamlit App     │
                    │      app.py         │
                    └──────────┬──────────┘
                               │
                               │ MCP / HTTP
                               ▼
                    ┌─────────────────────┐
                    │   FastMCP Server     │
                    │   mcp_server.py      │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
       Structured Data    Agentic RAG       Security
       Excel workbook    Chroma + BM25     Access checks
              │                │
              └────────────────┼────────────────┘
                               ▼
                    Grounded Tool Results
                               │
                               ▼
                         LangGraph Agent
                               │
                               ▼
                         Final Response

🔧 MCP-инструменты

MCP-сервер предоставляет:

1. get_account

2. get_order

3. get_ticket

4. search_knowledge

5. search_customer_agreement

6. calculate_service_credit

7. prepare_escalation

8. execute_escalation

9. create_followup

Операции, изменяющие состояние, перед выполнением требуют шага подтверждения.

📚 Agentic RAG

Конвейер поиска объединяет:

User Query
    ↓
Chroma Semantic Retrieval
    +
BM25 Keyword Retrieval
    ↓
Source Authority
    ↓
Customer-Aware Ranking
    ↓
Conflict / Precedence Handling
    ↓
Grounded Evidence
    ↓
LLM Answer

Приоритеты документов:

1. Действующее подписанное соглашение с клиентом

2. Действующая политика/SOP ParcelPilot

3. Прочая действующая документация

Устаревшие документы имеют более низкую авторитетность и не должны подменять актуальные источники.

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

ParcelPilot/
│
├── app.py
├── mcp_server.py
├── PARCELPILOT.ipynb
├── ParcelPilot_Assessment_Data.xlsx
│
├── 01_Support_Policy_v3_CURRENT.pdf
├── 02_Support_Policy_v2_DEPRECATED.pdf
├── 03_Cancellation_and_Service_Credit_SOP_v4.pdf
├── 04_Product_Operations_Guide_and_Known_Issues.pdf
├── 05_Northstar_Logistics_Enterprise_Agreement.pdf
├── 06_LumenWorks_Service_Agreement.pdf
│
├── pyproject.toml
└── README.md

⚙️ Настройка

1. Клонируйте репозиторий

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd ParcelPilot

2. Установите зависимости

В этом проекте используется pyproject.toml.

С помощью uv:

uv sync

Либо установите необходимые пакеты в любом удобном Python-окружении.

3. Создайте .env

Создайте файл .env в корне проекта:

OPENAI_API_KEY=your_openai_api_key
PARCELPILOT_USER=support_agent
MCP_HOST=0.0.0.0
MCP_PORT=8000

Для Streamlit-клиента укажите MCP URL:

PARCELPILOT_MCP_URL=http://127.0.0.1:8000/mcp

Не добавляйте .env или API-ключи в Git.

▶️ Запуск MCP-сервера

Сначала запустите MCP-сервер:

uv run python mcp_server.py

Сервер работает по адресу:

http://127.0.0.1:8000/mcp

В терминале вы должны увидеть информацию о запуске MCP-сервера ParcelPilot.

▶️ Запуск Streamlit

Во втором терминале:

uv run streamlit run app.py

Откройте URL Streamlit, показанный в терминале, обычно:

http://localhost:8501

🔐 Прототип контроля доступа

Этот проект включает имитацию контекста аутентифицированного пользователя для демонстрации поведения авторизации.

Поддерживаемые пользователи прототипа:

support_agent
customer_acct_002
customer_acct_003
admin

Сервер использует переменную PARCELPILOT_USER для выбора текущего пользователя прототипа.

В продакшен-системе это было бы заменено настоящими механизмами аутентификации и авторизации: токенами, выпущенными провайдером идентификации, claims о тенанте/учётной записи и серверными проверками разрешений.

🧑💼 Человек в контуре

Для действий, изменяющих состояние, агент сначала готовит операцию.

Пример:

User
  ↓
prepare_escalation
  ↓
Preview
  ↓
Explicit confirmation
  ↓
execute_escalation

Прототип не изменяет постоянные операционные данные во время выполнения.

🧪 Примеры запросов

Попробуйте следующие запросы в приложении Streamlit:

What is the current status of ORD-1001?

Show me the account details for ACCT-001.

What is the cancellation fee for a BOOKED shipment?

Can Northstar Logistics cancel a BOOKED shipment without a fee?

What is Northstar Logistics' P1 response target?

What are the failed-pickup service-credit rules for LumenWorks?

What is the current Enterprise P1 response target?

Escalate ticket TKT-501 because the customer needs urgent assistance.

В примере с эскалацией агент должен подготовить эскалацию и запросить подтверждение перед выполнением.

🎯 Продуктовые решения

Решение направлено на снижение нагрузки на сотрудника поддержки при сохранении контроля над операционными действиями.

Ключевые решения:

• Использовать MCP для отделения агента от операционных инструментов.

• Держать поиск внутри MCP-сервера, а не дублировать его в UI.

• Использовать комбинацию структурированных данных и поиска данных.

• Предоставлять вышестоящую роль соглашений с клиентами, чем общих политикам.

• Требовать явного подтверждения для действий, меняющих состояние.

• Включать проверки авторизации на уровне инструментов, а не только в интерфейсе.

🚀 Будущие улучшения

Если разработка продолжается, я бы приоритизировал:

1. Продакшен-аутентификацию и изоляцию тенантов

2. Постоянные журналы аудита для каждого вызова инструмента и действия

3. Реальные обновления тикетов/заказов через продакшен-API

4. Лучшую оценку поиска и автоматизированное тестирование RAG

5. Наблюдаемость: задержки, сбои инструментов и качество ответов

6. Процессы согласования для действий с высоким влиянием

• Аналитику поддержки и выявление рисков для клиентов

📊 Метрика успеха

Основной продуктовой метрикой могло стать:

Время решения тикета в поддержке

Целью было бы сокращение среднего времени решения при сохранении высокой точности и предотвращении несанкционированных или нежелательных операций.

📌 Сабмишн

Демо-видео

https://drive.google.com/file/d/1gTZlT4bx4oSflD68SWqcN6-uHPtcaT8l/view?usp=sharing

Разработано как оценочный прототип ParcelPilot.# 📦 ParcelPilot AI

Интеллектуальный агент для операционной поддержки клиентов, созданный с использованием LangGraph, MCP, Agentic RAG и Streamlit.

ParcelPilot AI умеет получать информацию о клиентах, учётных записях, заказах и тикетах, отвечать на вопросы по политикам с помощью гибридного поиска, применять индивидуальные соглашения с клиентами и требовать подтверждения перед операциями, изменяющими состояние.

✨ Возможности

• Оркестрация агента на основе LangGraph

• Удалённый FastMCP-сервер по протоколу Streamable HTTP

• 9 MCP-инструментов для операций поддержки клиентов

• Гибридный Agentic RAG на основе Chroma + BM25

• Получение индивидуальных соглашений клиента

• Обработка авторитетности источников и приоритетности документов

• Структурированные Excel-данные по учётным записям, заказам и тикетам

• Имитация управления доступом на основе ролей

• Подтверждение человеком в цикле для эскалаций и последующих действий

• Интерфейс Streamlit для взаимодействия с агентом

🏗️ Архитектура

                    ┌─────────────────────┐
                    │   Streamlit App     │
                    │      app.py         │
                    └──────────┬──────────┘
                               │
                               │ MCP / HTTP
                               ▼
                    ┌─────────────────────┐
                    │   FastMCP Server     │
                    │   mcp_server.py      │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
       Structured Data    Agentic RAG       Security
       Excel workbook    Chroma + BM25     Access checks
              │                │
              └────────────────┼────────────────┘
                               ▼
                    Grounded Tool Results
                               │
                               ▼
                         LangGraph Agent
                               │
                               ▼
                         Final Response

🔧 MCP-инструменты

MCP-сервер предоставляет:

1. get_account

2. get_order

3. get_ticket

4. search_knowledge

5. search_customer_agreement

6. calculate_service_credit

7. prepare_escalation

8. execute_escalation

9. create_followup

Операции, изменяющие состояние, выполняются только после шага подтверждения.

📚 Agentic RAG

Конвейер поиска объединяет:

User Query
    ↓
Chroma Semantic Retrieval
    +
BM25 Keyword Retrieval
    ↓
Source Authority
    ↓
Customer-Aware Ranking
    ↓
Conflict / Precedence Handling
    ↓
Grounded Evidence
    ↓
LLM Answer

Приоритеты документов:

1. Текущее подписанное соглашение с клиентом

2. Текущая политика/SOP ParcelPilot

3. Другая действующая документация

Устаревшие документы имеют более низкий авторитет и не должны подменять действующие источники.

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

ParcelPilot/
│
├── app.py
├── mcp_server.py
├── PARCELPILOT.ipynb
├── ParcelPilot_Assessment_Data.xlsx
│
├── 01_Support_Policy_v3_CURRENT.pdf
├── 02_Support_Policy_v2_DEPRECATED.pdf
├── 03_Cancellation_and_Service_Credit_SOP_v4.pdf
├── 04_Product_Operations_Guide_and_Known_Issues.pdf
├── 05_Northstar_Logistics_Enterprise_Agreement.pdf
├── 06_LumenWorks_Service_Agreement.pdf
│
├── pyproject.toml
└── README.md

⚙️ Настройка

1. Клонирование репозитория

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd ParcelPilot

2. Установка зависимостей

Проект использует pyproject.toml.

С помощью uv:

uv sync

Либо установите зависимости в выбранной Python-среде.

3. Создание файла .env

Создайте файл .env в корне проекта:

OPENAI_API_KEY=your_openai_api_key
PARCELPILOT_USER=support_agent
MCP_HOST=0.0.0.0
MCP_PORT=8000

Для Streamlit-клиента укажите MCP URL:

PARCELPILOT_MCP_URL=http://127.0.0.1:8000/mcp

Не сохраняйте .env и ключи в GitHub.

▶️ Запуск MCP-сервера

Сначала запустите MCP-сервер:

uv run python mcp_server.py

Сервер будет запущен по адресу:

http://127.0.0.1:8000/mcp

В терминале должна появиться информация о запуске MCP-сервера ParcelPilot.

▶️ Запуск Streamlit

Во втором терминале:

uv run streamlit run app.py

Откройте URL Streamlit, показанный в терминале, обычно:

http://localhost:8501

🔐 Контроль доступа в прототипе

Это решение включает имитацию контекста аутентифицированного пользователя для демонстрации авторизационного поведения.

Поддерживаемые пользователи прототипа:

support_agent
customer_acct_002
customer_acct_003
admin

Сервер использует переменную PARCELPILOT_USER для выбора текущего прототипа.

В производственной системе логика будет заменена полноценной аутентификацией и авторизацией: токенами от провайдера учётных данных, claims клиента/тенанта и серверными проверками прав.

🧑💼 Human-in-the-Loop

Для действий, изменяющих состояние, агент сначала подготавливает операцию.

Пример:

User
  ↓
prepare_escalation
  ↓
Preview
  ↓
Explicit confirmation
  ↓
execute_escalation

Прототип не изменяет постоянные операционные данные во время выполнения.

🧪 Примеры запросов

Попробуйте эти запросы в приложении Streamlit:

What is the current status of ORD-1001?

Show me the account details for ACCT-001.

What is the cancellation fee for a BOOKED shipment?

Can Northstar Logistics cancel a BOOKED shipment without a fee?

What is Northstar Logistics' P1 response target?

What are the failed-pickup service-credit rules for LumenWorks?

What is the current Enterprise P1 response target?

Escalate ticket TKT-501 because the customer needs urgent assistance.

В примере с эскалацией агент должен подготовить эскалацию и запросить подтверждение перед выполнением.

🎯 Решения для продукта

Решение направлено на снижение нагрузки на агентов поддержки с сохранением контроля над операциями.

Key decisions:

• Используйте MCP для изоляции инструментов от агента.

• Подберите интерактивный поиск на MCP-сервере, а не дублируйте его в интерфейсе.

• Объедините структурированные данные и поиск по документам.

• Отдавайте приоритет договорным соглашениям по общим политикам.

• Запрашивайте явное подтверждение для изменяющих состояние действий.

• Добавляйте проверки прав на уровне инструментов, а не только в интерфейсе.

🚀 Будущие улучшения

• Продакшен-аутентификация и изоляция тенантов

• Постоянные журналы аудита для каждого вызова инструмента и действия

• Реальные обновления тикетов и заказов через продакшен-API

• Улучшенная оценка поиска и автоматизированное тестирование RAG

• Наблюдаемость за задержками, сбоями инструментов и качеством ответов

• Процессы согласования для действий с высоким воздействием

• Аналитика поддержки и выявление рисков клиентов

📊 Метрика успеха

Основной продуктовой метрикой могла бы стать:

Время решения тикета в поддержке

Цель — сократить среднее время решения при сохранении высокой точности и предотвращении несанкционированных и нежелательных операций.

📌 Сабмишн

Демо-видео

https://drive.google.com/file/d/1gTZlT4bx4oSflD68SWqcN6-uHPtcaT8l/view?usp=sharing

Создано как прототип оценочного уровня ParcelPilot.