periferia-reto-03-agente-o
Agente conversacional de órdenes de compra – Prueba IA Periferia (Reto 3).
Chat web en español que conversa con Claude, llama herramientas tipadas con zod y crea órdenes de compra en un SAP simulado, siempre con confirmación humana antes de crear la OC.
Link de prueba: https://agente-oc-periferia.vercel.app (público, sin clave de acceso) · Diseño y decisiones: SOLUCION.md
Inicio rápido (un comando)
cp .env.example .env.local # escribe tu ANTHROPIC_API_KEY en .env.local
bun install && bun run dev # http://localhost:3000
Demo sin modelo de IA (no necesita clave): bun install && bun run demo.ts
Estructura
| Ruta | Qué es |
|---|
app/page.tsx | Chat web: historial, tarjetas de herramientas (nombre, argumentos, resultado resumido), markdown y botones Confirmar / Cancelar. |
app/api/* | API HTTP: /api/chat, /api/sessions/:id, /api/health. |
src/agent/ | Ciclo del agente (loop.ts), registro de herramientas, sesiones, detección de confirmaciones y carga del prompt. |
src/llm/ | Interfaz propia del proveedor (adapter.ts) e implementación Anthropic (anthropic.ts). |
agent/prompt.md | System prompt (comportamiento). Se envía junto con src/knowledge/ordenes-compra.md. |
src/tools/oc.ts | Herramientas oc_leer_paquete, oc_validar, oc_construir_payload, oc_generar_evidencia, oc_crear (contrato PRD 6.2). |
src/domain/ | Reglas RC1–RC10, parseo, payload y evidencia como funciones puras. |
src/sap/adapter.ts, src/sap/mock.ts | Interfaz SapAdapter y SAP simulado sobre archivos (out/sap/ordenes.jsonl). |
src/knowledge/ordenes-compra.md | Conocimiento del proceso: reglas, maestros y qué hacer en cada excepción. |
demo.ts | Procesa sol-001 a sol-006 llamando las herramientas sin modelo de IA; verifica el resultado esperado. |
fixtures/reto-03/ | Maestros y casos del reto (sol-001 a sol-006), solo lectura. |
modulo/ | Bonus PRD 9.4: el agente empaquetado (agent.md, tools/oc.ts, skill/ordenes-compra/SKILL.md) sin depender del servidor. |
scripts/modulo.ts | Genera y verifica modulo/ desde las fuentes de la app. |
SOLUCION.md | Documento de la solución (arquitectura, controles, adaptador SAP, análisis). |
Requisitos
- Bun 1.x
- Una API key de Anthropic (solo para el chat; la demo no la necesita).
Instalación paso a paso
bun install
cp .env.example .env.local # y escribe tu ANTHROPIC_API_KEY en .env.local
.env.local está en .gitignore: la clave nunca se sube al repositorio.
Ejecución local
bun run dev # abre http://localhost:3000
bun run demo.ts # demo sin IA: procesa sol-001 a sol-006 y verifica el resultado esperado
bun run typecheck # revisa tipos
bun run build # verifica modulo/ y compila como en producción
bun run modulo # regenera modulo/ desde agent/prompt.md y src/knowledge/
Salidas en out/ (configurable con OUT_DIR; en Vercel se usa /tmp/out): sap/ordenes.jsonl, control.csv, log.jsonl y, por caso, trazabilidad.json, aprobacion.txt y aprobacion.pdf.
Módulo reutilizable (modulo/)
El agente empaquetado para otras plataformas de agentes (PRD 9.4), sin depender del servidor:
| Archivo | Contenido | Fuente única |
|---|
modulo/agent.md | Frontmatter (description, mode: primary, permission: { edit: deny, bash: deny }) + system prompt | agent/prompt.md |
modulo/tools/oc.ts | Re-exporta las herramientas (leer_paquete, validar, construir_payload, generar_evidencia, crear) | src/tools/oc.ts |
modulo/skill/ordenes-compra/SKILL.md | Frontmatter (name, description) + conocimiento del proceso | src/knowledge/ordenes-compra.md |
bun run modulo # regenera agent.md y SKILL.md tras cambiar el prompt o el conocimiento
bun run modulo --verificar # falla si modulo/ difiere de las fuentes
La verificación corre en bun run build (y por tanto en cada despliegue de Vercel) y en demo.ts: no puede quedar una copia divergente.
API
| Método | Ruta | Cuerpo / respuesta |
|---|
POST | /api/chat | { sessionId, message } → { sessionId, reply, toolCalls[], needsConfirmation } |
GET | /api/sessions/:id | { sessionId, creada, tokens, pendientes, historial[] } |
GET | /api/health | { ok, provider, model } (ok = hay clave configurada; nunca expone la clave) |
sessionId: 8 a 64 caracteres [A-Za-z0-9_-]; el chat lo genera y lo guarda en el navegador.toolCalls[]: { nombre, args, ok, resumen, resultado, nota? } por cada herramienta ejecutada en el turno.needsConfirmation: true cuando un caso quedó con confirmación humana pendiente. Para confirmar se envía un mensaje como «confirmo»; para cancelar, «cancelar».- Errores:
{ error: "No pude procesar la solicitud, intenta de nuevo" }; el detalle técnico queda solo en los logs del servidor.
Ejemplo:
curl -s -X POST http://localhost:3000/api/chat -H 'content-type: application/json' \
-d '{"sessionId":"prueba-0001","message":"Procesa la solicitud sol-004"}'
Variables de entorno
Todas están en .env.example, sin valores.
| Variable | Obligatoria | Por defecto |
|---|
ANTHROPIC_API_KEY | Sí (solo para el chat; la demo no la usa) | — |
ANTHROPIC_MODEL | No | claude-sonnet-5-5 |
MAX_ITERACIONES | No | 25 |
MAX_TOKENS_SESION | No | 300000 |
LLM_TIMEOUT_MS | No | 60000 |
OUT_DIR | No | ./out (en Vercel /tmp/out) |
Despliegue en Vercel
- En vercel.com → Add New… → Project → importa este repositorio de GitHub. Nombre del proyecto:
agente-oc-periferia.
- Framework: Next.js (se detecta solo). Vercel detecta
bun.lock y usa Bun para instalar.
- En Settings → Environment Variables agrega
ANTHROPIC_API_KEY (y, si quieres, las variables opcionales de la tabla anterior).
- Deploy. Cada push a
main publica una nueva versión automáticamente.
En Vercel el disco es de solo lectura: las salidas van a /tmp/out y se pierden cuando la función se recicla. Es suficiente para la demo; en producción se reemplaza por un adaptador SAP real.
