ai-agent-rag
Referencias críticas
Todo lo que cuenta este workshop está publicado acá
Esto no es material de relleno: el live site es el sistema corriendo y los tres repos son el código que lo sostiene. Si algo de lo que lees acá te suena demasiado bonito, puedes comprobarlo tú mismo.
Live Site
Pregúntale algo y mira cómo responde. Es la misma experiencia que vas a construir en el workshop: streaming, metadata visible y respuestas ancladas a documentación ISO 20022.
Source Code
ai-agent-data
Todo lo que pasa antes del chat: S3, dispatcher, Batch, rag_context y la indexación hacia OpenSearch.
Source Code
ai-agent-rag
El runtime conversacional: Function URL, orquestación con LangGraph, translation, classifier, retrieval y generation con grounding.
Source Code
ai-agent-chat
La UI Angular: recibe el NDJSON tipado, renderiza el streaming y es la cara pública que abres al final del workshop.
Qué resuelve
De documentos bancarios a un contrato API
El punto de partida es simple: documentación bancaria real, un source set acotado y una política de generación clara. Sobre eso, cada etapa se arma con servicios de AWS que puedes inspeccionar y repetir.
El resultado es un agente que propone un contrato API basado en lo que dice la documentación, no en lo que el modelo recuerda.
Arquitectura
Cómo se conectan las piezas (vista C2)
01
Persona y canal
Una sola superficie: ai-agent-chat, la UI Angular donde escribes, ves el streaming y lees el resultado.
02
ai-agent-chat
Frontend Angular servido como sitio estático de S3. Envía { message } al endpoint público y consume la respuesta en streaming.
03
ai-agent-rag
Recibe la consulta, orquesta translation, classifier, retrieval y generation, y responde con NDJSON tipado.
04
ai-agent-data
Prepara el conocimiento antes de que exista el chat: procesa documentos, produce rag_context e indexa chunks en OpenSearch.
Diagrama C2 consolidado
flowchart LR
USER["Usuario"]
subgraph Chat["ai-agent-chat"]
UI["Angular chat UI
sitio estático en S3"]
end
subgraph Rag["ai-agent-rag"]
URL["Lambda Function URL"]
API["Node.js API handler"]
ORCH["LangGraph orchestrator
translation -> classifier -> retrieval -> generation"]
CTX[("S3 context responses")]
URL --> API --> ORCH --> CTX
end
subgraph Data["ai-agent-data"]
SRC["S3 source bucket"]
BATCH["AWS Batch processor"]
RAGJSON["processed/rag_context JSON"]
ING["OpenSearch ingestor"]
OS[("
OpenSearch index")]
SRC --> BATCH --> RAGJSON --> ING --> OS
end
USER --> UI
UI --> URL
ORCH --> OS
ORCH -->|NDJSON tipado| UI
El diagrama muestra el sistema completo y qué le toca a cada repo. El detalle interno vive en la documentación de cada subproyecto.
AWS Fit
Por qué este stack encaja si vienes del mundo AWS
Entrada
S3 como punto de entrada
Los documentos entran por S3. Eso habilita disparo por eventos, trazabilidad y un lugar para los artefactos intermedios.
Proceso
Lambda y Batch sin forzarlos
Lambda se encarga de lo reactivo. El procesamiento pesado de documentos va a AWS Batch.
Conocimiento
OpenSearch: retrieval que puedes inspeccionar
Con OpenSearch puedes ver qué se recuperó y ajustar la query sin reescribir prompts. Mucho más manejable que meter todo el contexto en un prompt gigante.
Detalle fino
Batch corre sobre ECS
No aprovisionas nada extra, pero los jobs de AWS Batch se orquestan con Amazon ECS por debajo. Por eso el rol del job confía en ecs-tasks.amazonaws.com y verás clusters AWSBatch en la cuenta.
MVP Hardening
Qué quedó más sólido antes de enseñar este flujo
Fixture
Demo reproducible
El workshop corre sobre un source set fijo en S3, con prompts y resultados esperados definidos. Repetir la demo y comparar contra lo esperado es directo.
Contrato
Metadata explícita
El contrato de rag_context quedó documentado, y cada campo se explica en el workshop con su porqué.
UX
Contrato de streaming más claro
El stream es tipado: contenido, metadata y estados de ejecución viajan separados, no mezclados en texto libre.
Decisiones clave
Detalles de implementación que sí agregan valor al workshop
Bedrock
Modelos diferenciados por fase
Clasificar no cuesta lo mismo que generar. La clasificación usa Amazon Nova Micro: rápida, con salida JSON. La generación va en Amazon Nova Pro por defecto, y un alias permite pasar a Claude o Llama en la capa final.
Language bridge
Translate antes de retrieval
El query suele llegar en español, pero buena parte de la documentación de estándares y del material indexado está en inglés. Traducir primero hace que clasificación y búsqueda trabajen sobre el mismo idioma del corpus.
Payload limits
S3 como puente entre Lambdas
El retrieval guarda el hit set en S3 y devuelve una s3_reference. Así te libras de los límites de payload de Lambda y desacoplas retrieval de generation sin perder el grounding.
Classification
Clasificación con señales combinadas
La intención no se decide con una sola señal: keywords primero, clasificación LLM después. Menos errores tempranos, ejecución más estable.
Contract
Metadata explícita para retrieval
domain, document_type, standard, source_format y content_type viajan con cada chunk. Con metadata explícita, filtrar y depurar el retrieval es directo; con un prompt monolítico, no.
Operations
Rutas operativas documentadas
Los tres repos traen rutas para infraestructura, build y deploy. Lo que armas en el workshop no queda en demo: queda operable.
Servicios
Qué servicios usa el sistema
Amazon S3
documentos fuente y artefactos intermedios
AWS Lambda
dispatch, clasificación, retrieval y orquestación
AWS Batch
procesamiento documental con Docling
OpenSearch + Bedrock
retrieval y generación final
Amazon Translate
puente lingüístico entre prompts en español y documentación indexada en inglés
Amazon Bedrock
clasificación y generación final sobre modelos administrados
Amazon ECS
orquesta los jobs de Batch por debajo
Amazon ECR
imagen Docker del processor
Amazon CloudWatch
logs del dispatcher, los jobs y el ingestor
Recorrido
Qué vas a construir, en orden
Levanta la capa de datos
Provisiona bucket, dispatcher, Batch, ingestor y OpenSearch con Terraform desde ai-agent-data.
Prepara el conocimiento
Sube el source set canónico, dispara el procesamiento y verifica Markdown, rag_context e indexación.
Conecta la capa RAG
Despliega ai-agent-rag, consume el estado remoto de datos y valida el stream NDJSON tipado.
Prueba la interfaz
Levanta ai-agent-chat, ejecuta prompts canónicos y observa el flujo completo con grounding visible.
Canon
Los prompts de la demo, tal cual
Prompt principal
Necesito un contrato OpenAPI para iniciar pagos basado en ISO 20022. Quiero request y response en application/json y una propuesta inicial en YAML.Prompt explicativo
Explicame la estructura de un mensaje de estado de pagos en ISO 20022 y los campos principales que deberia considerar.Prompt de borde
Genera un contrato API completo basado en BIAN para customer onboarding y devuelvelo en OpenAPI.