Construyo sistemas de IA agéntica y automatización para negocios reales — con garantías deterministas alrededor del modelo. Perú · Español (nativo) · English · Deutsch

EN — I design and build agentic AI systems and business automation: personal finance reconciliation, algorithmic trading with independent risk validation, public-procurement intelligence, retail price comparison. My work centers on one question: what should the model decide, and what must software guarantee? The repositories below are architecture and decision documentation, not runnable code — the real systems run on private business data and real money, so I publish what a senior engineer would put in an ADR: the problem, the decision, the trade-offs, the failure modes and the evals.

ES — Diseño y construyo sistemas de IA agéntica y automatización de negocio: conciliación financiera personal, trading algorítmico con validación de riesgo independiente, inteligencia de compras públicas, comparación de precios de retail. Todo gira alrededor de una pregunta: ¿qué debe decidir el modelo y qué debe garantizar el software? Los repositorios de abajo son documentación de arquitectura y decisiones, no código ejecutable — los sistemas reales corren con datos de negocio privados y dinero real, así que publico lo que un ingeniero senior pondría en un ADR: el problema, la decisión, los trade-offs, los modos de fallo y las evaluaciones.

DE — Ich entwerfe und baue agentische KI-Systeme und Geschäftsautomatisierung: Finanzabgleich, algorithmischer Handel mit unabhängiger Risikoprüfung, Intelligenz für öffentliche Ausschreibungen, Preisvergleich im Einzelhandel. Im Zentrum steht eine Frage: Was soll das Modell entscheiden, und was muss die Software garantieren? Die Repositories unten sind Architektur- und Entscheidungsdokumentation, kein lauffähiger Code — die echten Systeme arbeiten mit privaten Geschäftsdaten und echtem Geld, daher veröffentliche ich das, was ein Senior Engineer in ein ADR schreiben würde: Problem, Entscheidung, Trade-offs, Fehlermodi und Evals.

Agentic systems architecture (Claude / Codex) — what I bring.

La pregunta que organiza todo mi trabajo: ¿qué debe decidir el modelo y qué debe garantizar el software? El modelo interpreta, razona, resuelve ambigüedad, propone y elige herramientas. El software valida, autoriza, aplica límites, mantiene estado, evita duplicados y garantiza invariantes. Un prompt nunca sustituye a una garantía determinista.

Diseño de agentes

• Workflow vs. agente vs. herramienta vs. código determinista: cuándo cada uno, y por qué "un agente por módulo" es un anti-patrón. Multi-agente solo cuando hay descomposición, especialización, paralelismo o aislamiento de contexto reales — y asumiendo su coste (coordinación, estado distribuido, latencia, depuración).
• Bucles agénticos acotados: el orquestador reacciona al stop reason y al estado de ejecución, no al texto del chat; límites fijos de negocio que el juicio del modelo no puede sobreescribir.
• Subagentes con contexto mínimo relevante y resultado esperado explícito — contexto relevante > contexto máximo.

Herramientas y MCP

• Diseño de herramientas con nombre específico, esquema preciso y errores explícitos; tool = hacer, resource = leer, prompt = instrucciones reutilizables.
• Error ≠ resultado vacío. Errores reintentables (timeout, red) vs. no reintentables (permiso denegado, petición inválida).
• El esquema valida la forma, no la verdad: un JSON válido puede contener un hecho falso; la validación factual es otra capa.

Estado, efectos secundarios y recuperación

• Estado de conversación ≠ estado de ejecución: ledger persistente de tareas y acciones (planned → authorized → executing → succeeded | failed | unknown).
• Idempotencia en toda acción con efecto secundario; tras un timeout el estado es desconocido, no fallido: se verifica el sistema externo antes de reintentar.
• Verificación contra evidencia externa (estado de API, base de datos, archivo, test) — nunca "dos agentes coinciden, luego es cierto".

Memoria y contexto

• Estado canónico vs. proyecciones: evidencia, hechos, decisiones y correcciones son canónicos; resúmenes, wiki, grafos y vectores se reconstruyen desde ellos y nunca los corrigen.
• Procedencia por hecho (quién lo afirmó, observado/declarado/inferido, validez temporal, qué sustituye) y propagación de correcciones a todo lo derivado.

Seguridad y autorización

• Autorización en la frontera de la herramienta, fuera del razonamiento del modelo: el modelo pide, el software decide si esa identidad puede hacer esa operación sobre ese recurso ahora. Autenticación ≠ autorización.
• Contenido externo = datos, nunca instrucciones: un documento no puede otorgar permisos al agente. Secretos fuera del contexto del LLM por construcción.
• Human-in-the-loop donde el impacto o la autoridad lo exigen — la confianza del modelo no es verificación.

Evaluación

• Evals para recuperación (evidencia correcta, hecho sustituido rechazado, contaminación entre proyectos), memoria (propagación de correcciones), herramientas (esquema inválido, permiso denegado, timeout, resultado vacío), ejecución (duplicados, reinicio, estado desconocido) y autorización (permisos revocados, inyección por documento). Un sistema que no se puede medir no se puede mejorar.

Claude Code y Codex como plataforma

• Configuración por capas (CLAUDE.md global/proyecto, reglas por ruta, sin duplicar), hooks (automatización por evento), skills (capacidad reutilizable), commands (flujo explícito), Plan Mode para cambios amplios o riesgosos, orquestación de subagentes con contexto aislado.
• Codex como revisor independiente vía MCP: una segunda mirada sin mis supuestos encuentra lo que mis propios tests no ven.
• En preparación para Claude Certified Architect – Foundations (Anthropic).

Dónde está aplicado: ejecución de herramientas y secretos · límites deterministas · evaluaciones · validación de riesgo independiente en trading · frontera de solo lectura probada por AST.

• El modelo propone, el código decide, el humano valida. Lo que toca dinero o producción pasa por una persona.
• Imposible por construcción, no por promesa. Una garantía vale más si el sistema no puede violarla (la herramienta no existe, el proceso no tiene la credencial, un test estructural lo bloquea) que si un prompt le pide que no lo haga.
• Primero contra el pasado, después en vivo. Todo sistema que decide, predice o cotiza se estrena contra casos históricos con respuesta conocida — sin que pueda ver la respuesta — y gradúa con un criterio explícito.
• Los fallos se documentan. Cada lección, incluida la que salió mal, queda registrada como insumo de la siguiente decisión.
• Los asistentes de código son mi método, no mi atajo: diseño la arquitectura, fijo las garantías y verifico lo que producen.

Por GitHub, o a través del enlace en mi perfil.