Agente de chat de IA empresarial

Un asistente interno: chat multiturno, más herramientas de sistema de archivos servidas por un servidor MCP real que se conecta solo cuando realmente se involucra un archivo.

• Arquitectura y razonamiento → WRITEUP.md

• Convenciones, salvaguardas, registro de decisiones → CLAUDE.md

• Prompts verbatim utilizados para construirlo → PROMPTS.md

Qué necesitas instalar, y en qué orden

El proyecto funciona por sí solo. Los rastreos y las evaluaciones de comportamiento son dos capas opcionales separadas, cada una con su propio requisito previo — ninguna es necesaria para ver el agente funcionar. Elige un nivel y detente ahí.

Los niveles 2 y 3 son independientes: puedes hacer cualquiera, ambos, o ninguno. Nada en el nivel 1 se rompe si Docker o Node están ausentes.

Related MCP server: Files MCP Server

Nivel 1 — Núcleo (requerido)

Requisitos

Las versiones exactas están en requirements.txt; los rangos están en pyproject.toml.

Por qué mcp se mantiene por debajo de 2.0.0: El SDK de Python de MCP v2 renombró FastMCP a MCPServer y eliminó el módulo mcp.server.fastmcp. langchain-mcp-adapters 0.3.2 declara el mismo límite superior, por lo que no se pueden instalar juntos por encima de él. El fijado hace explícita una restricción implícita; no es una degradación.

Ejecutar

# 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

Punto de control: el agente te saluda según la hora del día y responde una pregunta. Si el paso 4 imprimió 44 passed, el sandbox, la ventana de memoria y la visibilidad de herramientas están todos verificados sin una sola llamada a la API.

El agente mantiene una conversación normal y se conecta al servicio de archivos la primera vez que pides un archivo.

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

Sal con exit. Vuelve a iniciarlo con el mismo --thread y la conversación continúa: el estado se guarda en SQLite, no se mantiene en memoria.

Dos formas de ejecutar el servidor MCP

Nota los dos "predeterminados": el código cae a 0 cuando la variable no está configurada, mientras que .env.example incluye MCP_AUTOSTART=1 para que un clon limpio se ejecute sin una segunda terminal. Copia la plantilla y obtienes autostart; despliega sin un .env y obtienes la forma de producción.

De cualquier manera, nada se conecta hasta que pides un archivo.

Cosas que vale la pena probar

Qué buscar en los registros

Los registros son JSON, una línea por evento, en stderr. Las claves correlation_id (un turno de usuario) y thread_id (una conversación) los vinculan.

var/audit.jsonl es el rastro de auditoría: una línea por llamada de herramienta con el resultado y la duración. Registra rutas, tamaños y hashes — nunca contenidos de archivos, nunca secretos.

Está en var/, no en workspace/, a propósito: las propias herramientas de archivo del agente alcanzan cada ruta bajo la raíz del sandbox, por lo que un rastro de auditoría mantenido allí podría ser editado por el proceso que registra. La base de datos de puntos de control (var/checkpoints.sqlite) está fuera por la misma razón — es la memoria del agente, no su espacio de trabajo. El inicio rechaza una configuración que coloque cualquiera de los dos de nuevo dentro del sandbox.

Nivel 2 — Rastreos en Phoenix (opcional)

Requisito previo: Docker. Omite toda esta sección si no lo tienes — el agente no lo necesita. El valor predeterminado es OTEL_EXPORTER=none, por lo que un clon limpio se ejecuta sin ningún recolector.

La instrumentación es OpenTelemetry con semántica OpenInference, por lo que los spans describen llamadas de LLM y herramientas en lugar de trabajo HTTP genérico. El exportador es una variable de entorno, no una ruta de código — cambiar Phoenix por cualquier otro backend OTLP es una variable, no una refactorización.

# 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

Punto de control: abre http://localhost:6006. Dos turnos producen dos rastreos. Abre el de archivo — la llamada de herramienta está anidada dentro del bucle create_agent, bajo la llamada del modelo. Ese anidamiento es el punto: es el flujo de control del agente, no una lista plana de solicitudes HTTP.

# when finished
docker stop phoenix && docker rm phoenix

No uses OTEL_EXPORTER=console para nada más que depuración local: esos spans imprimen el prompt completo y cada resultado de herramienta — es decir, contenidos de archivos — que el rastro de auditoría deliberadamente nunca almacena.

Nivel 3 — Evaluaciones de comportamiento (opcional)

Requisito previo: Node 18+. Omite si está ausente; pytest ya cubre todo lo determinista.

pytest cubre lo que se puede verificar sin red: confinamiento de rutas, aritmética de ventanas, visibilidad de herramientas. Lo que no puede cubrir es si el sistema todavía se comporta después de una conversación real de nueve turnos con un modelo real. Esos tres casos viven en promptfooconfig.yaml y se ejecutan contra el agente real — no contra el modelo desnudo — a través de 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

Punto de control: EXIT=0, y results.json contiene "successes": 3, "failures": 0, "errors": 0. Una ejecución completa tarda 40–60 segundos — son nueve turnos reales más dos conversaciones de un solo turno.

Dos cosas que parecen fallos y no lo son. La barra de progreso puede parecer atascada en 0% | 0/3: Node escribe una advertencia en la misma línea de terminal y la sobrescribe. Juzga por EXIT y el JSON, no por la barra. Y assertions.cached > 0 en una ejecución repetida es el calificador almacenando en caché sus propias llamadas — las conversaciones del agente nunca se almacenan en caché. Añade --no-cache para una ejecución completamente fría.

Esto cuesta tokens. Tres casos, once turnos en total, más un calificador LLM para las afirmaciones de rúbrica — todo con la misma OPENROUTER_API_KEY de tu .env.

Configuración

Cada configuración está documentada en .env.example. Las que más cambian el comportamiento: MCP_AUTOSTART, SANDBOX_ROOT, MAX_FILE_BYTES, HISTORY_WINDOW_MESSAGES, SUMMARIZATION_TRIGGER_MESSAGES, OTEL_EXPORTER.

.env está en .gitignore desde el primer commit y nunca se ha comprometido:

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