Reference Architecture

Esta arquitectura de referencia combina los patrones principales del libro en un agentic system listo para producción. Es intencionalmente conservadora: el software determinista es dueño del state, la policy y los side effects; las llamadas al model proponen decisiones dentro de loops acotados.

Usa este capítulo como puente entre la selección de patterns y el diseño del sistema. El diagrama no es una prescripción de framework; muestra los límites de propiedad que un sistema en producción necesita antes de que los agents manejen datos privados, acciones externas o trabajo de larga duración.

Architecture

Lee este diagrama como un mapa de propiedad para sistemas en producción: los servicios deterministas son dueños de la identidad, el state, la policy, la retrieval, las aprobaciones y los traces alrededor de llamadas acotadas al model.

Descarga el artifact reutilizable de revisión: reference architecture review checklist.

Boundary Flow

Usa este flujo para revisar una solicitud desde la entrada hasta el estado final. Separa el control plane que decide qué está permitido del execution plane que recupera evidencia, invoca tools y escribe el state.

El flujo debe fallar cerrado. Una propuesta del model solo puede avanzar después de que los checks de state, policy, schema, evidencia, aprobación o verificador la acepten.

What This Architecture Is For

Usa esta estructura cuando el agent pueda tocar datos privados, invocar tools, esperar aprobación, ejecutarse por más de una solicitud o afectar clientes, dinero, infraestructura, cumplimiento o operaciones internas. Es más pesada que un prompt chain, pero la estructura adicional permite revisiones.

No comiences aquí para un prototipo de solo lectura, un resumidor de una sola vez o un workflow cuyos pasos sean totalmente deterministas. Para esos sistemas, usa el pattern más pequeño que resuelva el task y mantén los controles de producción proporcionales al riesgo.

Readiness Questions

Usa estas preguntas antes de una revisión de diseño:

1. ¿Qué puede hacer el sistema que una respuesta normal de chat no puede?
2. ¿Qué acción crea el mayor riesgo, costo o impacto al usuario?
3. ¿Qué servicio es dueño del state que sobrevive reintentos, caídas y esperas de aprobación?
4. ¿Qué policy check se ejecuta antes de la retrieval, antes del uso de tools, antes de escribir en memory y antes de la respuesta final?
5. ¿Qué evidencia debe ver el model y cuál debe permanecer fuera del context del model?
6. ¿Qué evento exacto mueve una ejecución de borrador a acción aprobada?
7. ¿Qué trace prueba que el sistema siguió el camino previsto?
8. ¿Qué switch desactiva el comportamiento riesgoso sin deshabilitar todo el producto?

Si un equipo responde esto solo con texto de prompt, el diseño sigue siendo un prototipo.

Layered View

Las capas no requieren servicios separados. Un sistema pequeño puede implementar varias capas en una sola base de código. Lo importante es la propiedad: otro ingeniero debe poder encontrar dónde se toma, prueba, registra y revierte cada decisión.

Control Plane vs Execution Plane

Mantén las decisiones de control fuera del texto libre del model. El model puede proponer, resumir, clasificar o redactar. Los servicios controlados por el runtime deciden si la propuesta puede afectar el state, tools, memory, aprobaciones o usuarios.

Esta separación previene una falla común: que un model proponga una acción y la autorice implícitamente. La arquitectura de producción debe hacer visible y comprobable el camino de autorización.

Maturity Ladder

Adopta la arquitectura por etapas. No construyas todos los componentes de plataforma antes de que el sistema demuestre valor.

La escalera no es una insignia de estatus. Es un control de alcance. Un sistema nivel 1 puede ser excelente para un task de solo lectura. Un sistema nivel 3 que no puede probar la aprobación vinculante no está listo para producción.

Primer Camino de Implementación

Comienza con un solo workflow de usuario y un solo límite de riesgo. Una primera implementación útil debe ser lo suficientemente pequeña como para revisarse en una sola reunión de diseño.

Este camino mantiene la arquitectura ligada a la evidencia. Cada capa agregada debe cerrar un riesgo nombrado, no solo satisfacer un diagrama.

Flujo de Solicitud

1. Autentica al usuario o fuente del evento.
2. Crea un registro de goal con restricciones, alcance de usuario y resultado solicitado.
3. Enruta la task a una respuesta directa, Agentic RAG, durable workflow o proceso multi-agent.
4. Ejecuta verificaciones de policy antes de la recuperación, uso de tools o efectos secundarios.
5. Persiste observaciones, decisiones, llamadas a tools y outputs.
6. Verifica evidencia, calidad del output y cumplimiento de policy.
7. Devuelve una respuesta, solicita aprobación, rechaza o escala.
8. Almacena traces para depuración y mejora del dataset de eval.

Ejemplo: Solicitud de Reembolso en Soporte

Un cliente solicita un reembolso. La arquitectura debe mantener tres decisiones separadas.

El model puede redactar una recomendación. No autentica al usuario, no elige sus propios tools, no decide la autoridad de pago, no escribe memory sin policy, ni marca el workflow como completo sin un stop reason. Esa separación es el objetivo de la reference architecture.

Mapeo de Puntos de Control

Convierte la arquitectura en tickets de implementación asignando cada transición riesgosa a un punto de control concreto.

Si una fila no tiene owner, prueba o evidencia almacenada, la arquitectura sigue siendo solo un dibujo. La implementación está lista solo cuando cada transición puede fallar de forma cerrada.

Puntos de Control

• Antes de retrieval: aplica control de acceso y elegibilidad de fuente.
• Antes de usar tools: valida schema, permisos, presupuesto y necesidades de aprobación.
• Antes de la respuesta final: verifica afirmaciones, citas y policy.
• Antes de escribir memory: clasifica qué tipo de memory se almacena.
• Antes de liberar: ejecuta evals y revisiones de regresión.

Slices de Implementación de Referencia

Construye la arquitectura en slices. Cada slice debe producir una prueba desplegable, no solo una promesa en un diagrama.

Esta secuencia evita que los equipos construyan orquestación antes de poder probar límites de state, policy y evidencia.

Formas de Despliegue

La reference architecture no requiere una plataforma grande desde el primer día. Usa la forma de despliegue más pequeña que preserve los puntos de control para el riesgo que estás asumiendo.

La compresión es segura solo cuando la propiedad se mantiene explícita. Un prototipo puede compartir rutas de código. No puede compartir la pregunta de quién es owner de state, policy, autoridad de tool, evidencia y rollback.

Guía de Ubicación de Límites

Usa esta guía para decidir si un componente pertenece dentro del agent runtime, el servicio de aplicación o un servicio de plataforma separado.

La separación debe seguir la propiedad y el riesgo, no la moda. Un servicio separado sin un owner más fuerte es solo código más distribuido.

Evidence Bundle

Un diseño que afirma seguir esta arquitectura debe adjuntar estos artifacts:

Run Trace Contract

Una reference architecture solo es real si un run puede demostrar que los límites funcionaron. Captura el run como trace data estructurado, no como logs dispersos.

type ReferenceRunTrace = {
  runId: string;
  tenantId: string;
  userOrEvent: string;
  goal: string;
  route: "direct_answer" | "rag" | "agent_loop" | "durable_workflow" | "multi_agent";
  stateVersion: string;
  context: Array<{
    source: string;
    accessDecision: "allow" | "deny";
    freshness: "current" | "stale" | "unknown";
    citationRequired: boolean;
  }>;
  modelDecisions: Array<{
    step: string;
    proposal: string;
    acceptedBy: "schema" | "policy" | "human" | "runtime";
  }>;
  policyChecks: Array<{
    boundary: "retrieval" | "tool" | "memory" | "approval" | "final_answer";
    decision: "allow" | "deny" | "escalate";
    policyVersion: string;
  }>;
  toolCalls: Array<{
    name: string;
    authority: "read" | "draft" | "write" | "execute";
    idempotencyKey?: string;
    result: "success" | "failed" | "denied";
  }>;
  finalStatus: "completed" | "refused" | "needs_approval" | "policy_blocked" | "evidence_missing" | "failed";
  stopReason: string;
  rollbackPath?: string;
};

Los nombres exactos de los campos pueden cambiar. Lo que no debe cambiar es el invariante: un revisor debe poder reconstruir quién preguntó, qué evidencia entró al context, qué propuso el model, qué policies se ejecutaron, qué tools se usaron, por qué se detuvo el run y cómo revertir o deshabilitar el camino riesgoso.

Architecture Acceptance Tests

Antes de un piloto, ejecuta al menos estas verificaciones de aceptación contra el trace contract.

Si estas pruebas son difíciles de escribir, probablemente la arquitectura aún está oculta en framework glue, prompts o procesos informales.

Runtime Components

• Identity and tenant boundary
• Goal and state store
• Prompt and instruction registry
• Tool gateway
• Retrieval router
• Memory service
• Policy engine
• Approval service
• Workflow engine
• Evals service
• Trace and audit store

Ownership Matrix

Asigna responsables antes de producción. La falta de ownership es un defecto de arquitectura.

Una persona puede ser responsable de varias celdas en un equipo pequeño. La tabla sigue siendo importante porque cada falla en producción preguntará quién era responsable del boundary.

Design Review Questions

Haz estas preguntas antes de un piloto en producción:

1. ¿Qué decisión toma el model y qué decisión toma el software después de eso?
2. ¿Qué cambios de state sobreviven a un crash, retry o espera de approval?
3. ¿Qué llamada de tool tiene el mayor costo, riesgo o irreversibilidad?
4. ¿Qué evidencia se requiere antes de que el sistema responda o actúe?
5. ¿Qué sucede cuando la evidencia falta, está desactualizada, es conflictiva o no está autorizada?
6. ¿Qué se escribe en memory y quién puede corregirlo o eliminarlo?
7. ¿Qué eval bloquea el release si el sistema falla mañana?
8. ¿Puede un operador reconstruir el run fallido sin adivinar?
9. ¿Qué se puede deshabilitar sin volver a desplegar todo el sistema?
10. ¿Qué haría que el equipo apague el agent?

Minimum Production Checklist

• Responsable explícito para goal y state
• Tool schemas y validación
• Aprobación humana para acciones de alto riesgo
• Retrieval con control de acceso
• Validación de citas para respuestas fundamentadas
• Evals para core tasks
• Traces para cada run
• Controles de presupuesto, timeout y cancelación
• Ruta de revisión de incidentes
• Switch de rollback o deshabilitar

Reference Architecture Review Gate

Usa la reference architecture review checklist antes de un piloto o release de producción. Bloquea el release cuando:

• el model es responsable de autenticación, autorización, policy o permiso de efectos secundarios;
• el durable state no tiene schema, replay path o motivo de detención;
• las retrieval sources carecen de control de acceso, confianza, frescura o validación de citas;
• las approvals autorizan comportamientos futuros vagos;
• los evals solo inspeccionan el texto final e ignoran tools, policy, evidence y transiciones de state;
• los operadores no pueden reconstruir un run exitoso y uno fallido a partir de traces.

Scaling Path

Comienza pequeño:

1. Single agent con validación de tool.
2. Agrega goals y state.
3. Agrega retrieval y validación de citas.
4. Agrega durable workflow para tasks de larga duración.
5. Agrega gates de aprobación humana.
6. Agrega datasets de eval y observability.
7. Agrega multi-agent decomposition solo cuando un agent se convierte en un cuello de botella.

Anti-Patterns

Evita estos diseños:

• El model elige de una lista amplia de tools sin permiso a nivel de ruta.
• El texto del prompt es el único boundary de policy.
• Retrieval, memory y resultados de tool se mezclan en el context sin procedencia.
• El sistema puede actuar pero no puede reproducir por qué actuó.
• Las approvals autorizan comportamientos futuros vagos en lugar de una acción exacta.
• Los evals solo revisan la calidad de la respuesta final e ignoran el uso de tools, policy, evidence y motivo de detención.
• El rollback requiere eliminar todo el deployment porque prompts, tools y policies no pueden deshabilitarse de forma independiente.

Related Chapters

• Agentic System Architecture
• Agentic RAG Systems
• MCP-first Tool Use
• Production Runtime Overview
• Durable Workflows
• Policy Enforcement
• Observability and Evals