Implementación guiada del MVP

Usa esta vista para orientar el recorrido. Cuando se requiera mayor detalle, conviene derivar a ai-agent-data/docs/ARCHITECTURE.md o ai-agent-rag/docs/ARCHITECTURE.md y mantener esta página como vista consolidada.

Conviene partir de un workspace explícito para que los comandos, rutas y validaciones sean consistentes.

export WORKSHOP_ROOT="$HOME/work/ai-agent"
cd "$WORKSHOP_ROOT"

Dentro de ese root se asume que existen `ai-agent-data`, `ai-agent-rag` y `ai-agent-chat`.

La preparación del entorno incluye declarar e instalar las herramientas que intervienen en el recorrido.

# macOS
brew install awscli
brew tap hashicorp/tap
brew install hashicorp/tap/terraform
brew install --cask docker
brew install node
brew install python

# Ubuntu / Debian
sudo apt-get update
sudo apt-get install -y awscli terraform docker.io nodejs npm python3 python3-pip

aws configure
aws sts get-caller-identity
terraform version
docker --version
node --version
npm --version
python --version

El recorrido principal del workshop está planteado en modo `local-first`. GitHub Actions puede complementar despliegues de equipo, pero no es indispensable para seguir el MVP.

ai-agent-data/.github/workflows/deploy-infrastructure.yml

ai-agent-rag/.github/workflows/infrastructure-dev.yml

ai-agent-chat/.github/workflows/deploy.yml

No existe un ai-agent-rag/.github/workflows/opensearch-dev.yml en el estado actual del repo.

ai-agent-data combina Terraform e imagen Batch. ai-agent-rag tiene workflow raíz para la infraestructura. ai-agent-chat despliega el frontend estático a S3 con OIDC y generación de API_URL en build.

La secuencia comienza en la capa de ingestión, donde se prepara el conocimiento que alimentará el runtime conversacional.

ai-agent-data/terraform/main.tf

ai-agent-data/terraform/outputs.tf

ai-agent-data/terraform/environments/dev.tfvars

cd "$WORKSHOP_ROOT/ai-agent-data/terraform"
terraform init \
  -backend-config="bucket=YOUR-STATE-BUCKET" \
  -backend-config="key=doc-processor/dev/terraform.tfstate" \
  -backend-config="region=us-east-1"
terraform apply -var-file=environments/dev.tfvars

Antes de construir la imagen, conviene revisar el comportamiento del contenedor y sus responsabilidades.

ai-agent-data/src/batch/processor.py

ai-agent-data/src/pdf_processor.py

ECR_URL=$(terraform output -raw ecr_repository_url)
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_URL
cd "$WORKSHOP_ROOT/ai-agent-data/src"
docker build -t $ECR_URL:latest -f batch/Dockerfile .
docker push $ECR_URL:latest

En esta etapa conviene trabajar con el source set canónico para mantener trazabilidad entre documentos, metadata y resultados esperados.

ai-agent-data/docs/WORKSHOP_DEMO_SOURCE_SET.md

cd "$WORKSHOP_ROOT/ai-agent-data/terraform"
BUCKET=$(terraform output -raw source_bucket)
aws s3 cp ./s3/pdfs_iso/ISO20022_MDRPart2_PaymentsInitiation_2023_2024_v1.pdf s3://$BUCKET/ --metadata domain="iso 20022",document_type="specification",standard="ISO 20022"
aws s3 cp ./s3/docxs_iso/ISO20022_MDRPart1_PaymentsInitiation_2023_2024_v2.docx s3://$BUCKET/ --metadata domain="iso 20022",document_type="specification",standard="ISO 20022"
aws s3 cp ./s3/pdfs_iso/ISO20022_MDRPart2_Bank-to-CustomerCashManagement_2023_2024_v1.pdf s3://$BUCKET/ --metadata domain="iso 20022",document_type="specification",standard="ISO 20022"

La metadata forma parte del retrieval path. pdf_processor.py y el contrato de rag_context la utilizan junto con el contenido extraído por Docling y segmentado con HybridChunker.

ai-agent-data/src/lambda/dispatcher.py

aws logs tail /aws/lambda/doc-processor-dispatcher-dev --follow
aws logs tail /aws/batch/doc-processor --follow
aws s3 ls s3://$BUCKET/processed/ --recursive

aws s3 cp s3://$BUCKET/processed/rag_context/YOUR_FILE.json /tmp/workshop-rag-context.json
cat /tmp/workshop-rag-context.json

INGESTOR_FN=$(terraform output -raw opensearch_ingestor_function_name)
aws logs tail /aws/lambda/$INGESTOR_FN --follow

La indexación downstream valida schema_version y construye bulk actions por chunk. Eso deja explícito que el contrato útil para RAG opera sobre chunks tipados, no sobre documentos completos.

ai-agent-rag/data.tf

ai-agent-rag/variables.tf

cd "$WORKSHOP_ROOT/ai-agent-rag"
export TF_VAR_aws_region=us-east-1
export TF_VAR_project_name=ai-agent-bank
export TF_VAR_environment=dev
export TF_VAR_terraform_state_bucket='your-terraform-state-bucket'
export TF_VAR_ai_agent_data_state_key='doc-processor/dev/terraform.tfstate'
export TF_VAR_response_generation_model_alias='nova'
terraform init \
  -backend-config="bucket=YOUR-RAG-STATE-BUCKET" \
  -backend-config="key=infra/dev/terraform.tfstate" \
  -backend-config="region=us-east-1"
terraform apply

En el estado actual del proyecto, el root module de ai-agent-rag todavía no deja resueltas por Terraform las variables OPENSEARCH_HOST, OPENSEARCH_USERNAME, OPENSEARCH_ADMIN_PASSWORD y OPENSEARCH_INDEX de la Lambda de retrieval. El workshop debe presentar ese punto como una configuración posterior requerida.

También es conveniente dejar visible que la generación final corre sobre un alias de modelo configurable, mientras que la clasificación usa internamente amazon.nova-micro-v1:0.

ai-agent-rag/modules/lambda/orchestrator-wa/lambda_langgraph_orchestrator-wa.py

python -m pytest modules/lambda/tests/test_langgraph_orchestrator.py -q

En esta etapa también se observa otra decisión relevante: el orquestador no solo entrega chunks finales; emite un evento de understanding con dominio, intención y resumen del contexto recuperado.

ai-agent-chat/src/app/chat.service.ts

cd "$WORKSHOP_ROOT/ai-agent-rag"
export API_URL="$(terraform output -raw api_endpoint_url)"
cd "$WORKSHOP_ROOT/ai-agent-chat"
npm install
npm start

ai-agent-chat genera sus environment files desde API_URL en scripts/set-env.sh. Para desarrollo local, el comando alineado con la implementación actual es npm start.