📦 ParcelPilot AI

Agente inteligente de operaciones de soporte al cliente construido con LangGraph, MCP, Agentic RAG y Streamlit.

ParcelPilot AI puede recuperar información de clientes/cuentas/pedidos/tickets, responder consultas sobre políticas mediante recuperación híbrida, aplicar acuerdos específicos del cliente y exigir confirmación antes de las operaciones que modifican el estado.

✨ Características

• Orquestación de agentes basada en LangGraph

• Servidor FastMCP remoto sobre Streamable HTTP

• 9 herramientas MCP para operaciones de soporte al cliente

• RAG agéntico híbrido con Chroma + BM25

• Recuperación de acuerdos específicos del cliente

• Manejo de autoridad de fuentes y precedencia de documentos

• Datos estructurados en Excel para cuentas, pedidos y tickets

• Control de acceso simulado basado en roles

• Confirmación con intervención humana para escalaciones y seguimientos

• Interfaz de Streamlit para interactuar con el agente

Related MCP server: Enterprise MCP Gateway

🏗️ Arquitectura

                    ┌─────────────────────┐
                    │   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

🔧 Herramientas MCP

El servidor MCP expone:

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

Las operaciones que modifican el estado utilizan un paso de confirmación antes de la ejecución.

📚 RAG agéntico

El proceso de recuperación combina:

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

Precedencia de documentos:

1. Acuerdo de cliente vigente y firmado

2. Política/SOP actual de ParcelPilot

3. Otra documentación válida

Los documentos obsoletos tienen menor autoridad y no deben anular las fuentes actuales.

📁 Estructura del proyecto

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

⚙️ Configuración

1. Clonar el repositorio

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd ParcelPilot

2. Instalar dependencias

Este proyecto usa pyproject.toml.

Con uv:

uv sync

O instala los paquetes necesarios usando tu entorno de Python preferido.

3. Crea el archivo .env

Crea un archivo .env en la raíz del proyecto:

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

Para el cliente de Streamlit, configura la URL de MCP:

PARCELPILOT_MCP_URL=http://127.0.0.1:8000/mcp

No hagas commit de .env ni de claves de API en GitHub.

▶️ Ejecutar el servidor MCP

Primero inicia el servidor MCP:

uv run python mcp_server.py

El servidor se ejecuta en:

http://127.0.0.1:8000/mcp

Deberías ver la información de inicio del servidor MCP de ParcelPilot en la terminal.

▶️ Ejecutar Streamlit

En una segunda terminal:

uv run streamlit run app.py

Abre la URL de Streamlit que muestra la terminal, normalmente:

http://localhost:8501

🔐 Control de acceso del prototipo

Esta entrega incluye un contexto de usuario autenticado simulado para demostrar el comportamiento de autorización.

Los usuarios compatibles del prototipo incluyen:

support_agent
customer_acct_002
customer_acct_003
admin

El servidor usa PARCELPILOT_USER para seleccionar el usuario actual del prototipo.

En un sistema de producción, esto se sustituiría por autenticación y autorización reales, como tokens emitidos por el proveedor de identidad, reclamaciones de tenant/cuenta y comprobaciones de permisos en el servidor.

🧑💼 Intervención humana

Para las acciones que modifican el estado, el agente primero prepara la operación.

Ejemplo:

User
  ↓
prepare_escalation
  ↓
Preview
  ↓
Explicit confirmation
  ↓
execute_escalation

El prototipo no modifica datos operativos persistentes durante la ejecución.

🧪 Consultas de ejemplo

Prueba estas consultas en la aplicación de 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.

Para el ejemplo de escalación, el agente debe preparar la escalación y solicitar confirmación antes de la ejecución.

🎯 Decisiones de producto

La solución se centra en reducir el esfuerzo de los agentes de soporte manteniendo controladas las acciones operativas.

Decisiones clave:

• Usar MCP para separar el agente de las herramientas operativas.

• Mantener la recuperación dentro del servidor MCP en lugar de duplicarla en la UI.

• Combinar datos estructurados y recuperación de documentos.

• Otorgar a los acuerdos de cliente mayor autoridad que a las políticas generales.

• Exigir confirmación explícita para las acciones que modifican el estado.

• Incluir comprobaciones de autorización en la capa de herramientas y no sólo en la interfaz.

🚀 Mejoras futuras

Si continuara el desarrollo, priorizaría:

1. Autenticación en producción y aislamiento de tenants

2. Registros de auditoría persistentes para cada llamada y acción de herramienta

3. Actualizaciones reales de tickets/pedidos mediante APIs de producción

4. Mejor evaluación de la recuperación y pruebas automatizadas de RAG

5. Observabilidad de latencia, fallos de herramientas y calidad de respuestas

6. Flujos de aprobación para acciones de alto impacto

7. Análisis del soporte y detección de riesgo del cliente

📊 Métrica de éxito

Una métrica principal del producto sería:

Tiempo de resolución de soporte por ticket

El objetivo sería reducir el tiempo medio de resolución manteniendo una alta precisión y evitando acciones operativas no autorizadas o incorrectas.

📌 Entrega

Vídeo de demostración

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

Construido como prototipo de evaluación de ParcelPilot.