DEV Community: AWS

Multi-step workflows que sobreviven fallos

Hazel Saenz — Thu, 23 Apr 2026 23:23:14 +0000

Cómo los checkpoints automáticos en Lambda Durable Functions mantienen tu progreso incluso cuando todo se rompe.

En el artículo anterior construimos una Durable Function de procesamiento de imágenes paso a paso. Instalamos el Kiro Power, generamos el código con IA, testeamos localmente, y deployamos a AWS con CDK.

Todo funcionó perfecto.

Y ese es el problema.

En producción, las cosas se rompen. APIs que no responden, timeouts, servicios caídos, datos corruptos. La pregunta no es si algo va a fallar, sino cuándo.

La promesa central de Durable Functions es que tu workflow sobrevive a los fallos sin perder progreso. Pero, ¿cómo funciona eso realmente? ¿Qué pasa cuando un step falla a mitad de ejecución? ¿Cómo sabe la función dónde retomar?

En este artículo vamos a romper cosas a propósito. Vamos a simular fallos reales, ver cómo el replay model recupera la ejecución, configurar estrategias de reintento, y aprender a manejar errores dentro del contexto durable.

Mismo proyecto de procesamiento de imágenes. Pero esta vez, en modo destrucción.

El replay model por dentro

En el artículo anterior mencionamos que cada context.step() es un checkpoint. Pero no explicamos qué pasa por debajo. Ahora sí.

Cuando una Durable Function se ejecuta por primera vez, el flujo es lineal:

Entra el evento
Ejecuta el Step 1 → guarda el resultado como checkpoint
Ejecuta el Step 2 → guarda el resultado como checkpoint
Ejecuta el Step 3 → guarda el resultado como checkpoint
Retorna el resultado final

Hasta aquí, nada especial. Parece una función normal.

Pero ahora imagina que el Step 3 falla. Un timeout, un error de red, lo que sea. La función se cae.

Cuando la función se reintenta (ya sea por el retry automático de Lambda o por una nueva invocación), esto es lo que pasa:

Entra el evento (el mismo)
Llega al Step 1 → ya tiene checkpoint → salta la ejecución, usa el resultado guardado
Llega al Step 2 → ya tiene checkpoint → salta la ejecución, usa el resultado guardado
Llega al Step 3 → no tiene checkpoint → lo ejecuta de nuevo
Si funciona → guarda checkpoint → continúa
Si falla otra vez → repite el ciclo

Eso es el replay model. No es magia. Es un sistema de checkpoints que guarda el resultado de cada step y lo reutiliza en los reintentos.

Lo importante: el código se ejecuta desde el principio cada vez. Pero los steps que ya completaron se saltan instantáneamente porque el resultado ya está guardado. El código fuera de los steps sí se vuelve a ejecutar (por eso la regla de oro del determinismo que vimos en el artículo anterior).

Anatomía de un checkpoint

¿Qué se guarda exactamente en cada context.step()?

Cada checkpoint almacena:

El nombre del step: el string que le pasas como primer argumento ('validate-file', 'resize-image', etc.)
El resultado: lo que retorna la función async dentro del step
El estado: completado, fallido, o en progreso
Timestamps: cuándo empezó y cuándo terminó

// Cuando este step se completa exitosamente...
const validated = await context.step('validate-file', async () => {
  const metadata = await sharp(buffer).metadata();
  return {
    format: metadata.format,
    width: metadata.width,
    height: metadata.height,
    size: buffer.length
  };
});

// ...el checkpoint guarda algo como:
// {
//   name: 'validate-file',
//   status: 'completed',
//   result: { format: 'jpeg', width: 1920, height: 1080, size: 2456789 },
//   startedAt: '2026-04-20T10:00:00.000Z',
//   completedAt: '2026-04-20T10:00:01.234Z'
// }

Consideraciones sobre el tamaño de los datos

El resultado de cada step se serializa y se guarda. Eso significa que si tu step retorna un buffer de 5 MB, esos 5 MB se guardan en el checkpoint.

Recuerda que Durable Functions maneja datos entre pasos a través de checkpoints serializados. La documentación oficial recomienda mantener el estado mínimo y usar almacenamiento externo (S3, DynamoDB) para datos grandes. No es infinito.

Buena práctica: retorna solo lo que el siguiente step necesita. Si procesaste una imagen, no retornes el buffer completo. Guárdalo en S3 y retorna la key.

// ❌ Esto puede ser problemático con imágenes grandes
const imageBuffer = await context.step('resize', async () => {
  const resized = await sharp(buffer).resize(1920, 1080).toBuffer();
  return resized.toString('base64'); // Puede ser varios MB
});

// ✅ Mejor: guarda en S3 y retorna la referencia
const resizedKey = await context.step('resize', async () => {
  const resized = await sharp(buffer).resize(1920, 1080).toBuffer();
  const key = `processed/${baseName}-resized${ext}`;
  await s3.send(new PutObjectCommand({
    Bucket: outputBucket,
    Key: key,
    Body: resized,
  }));
  return key; // Solo unos bytes
});

Rompiendo cosas a propósito — Escenario 1: Fallo transitorio

Basta de teoría. Vamos a romper algo.

Usaremos el mismo proyecto de procesamiento de imágenes del artículo anterior. Si no lo tienes, puedes clonarlo desde GitHub.

Simulando un fallo de red en el resize

Vamos a modificar el step de resize para que falle las primeras dos veces, simulando un error de red transitorio:

// Contador de intentos (solo para demostración)
let resizeAttempts = 0;

const resizedBase64 = await context.step('resize-image', async () => {
  resizeAttempts++;

  // Simular fallo de red en los primeros 2 intentos
  if (resizeAttempts <= 2) {
    context.logger.error(`Resize attempt ${resizeAttempts} failed - simulating network error`);
    throw new Error('ENETUNREACH: network is unreachable');
  }

  context.logger.info(`Resize attempt ${resizeAttempts} succeeded`);

  const buffer = Buffer.from(imageBuffer, 'base64');
  const resized = await sharp(buffer)
    .resize(1920, 1080, { fit: 'inside', withoutEnlargement: true })
    .toBuffer();

  const resizedKey = `${outputPrefix}/${baseName}-resized${ext}`;
  await s3.send(new PutObjectCommand({
    Bucket: outputBucket,
    Key: resizedKey,
    Body: resized,
    ContentType: `image/${ext.replace('.', '')}`,
  }));

  return resized.toString('base64');
});

Qué pasa cuando lo ejecutas

Invoca la función:

aws lambda invoke \
  --function-name 'TU-FUNCION:prod' \
  --invocation-type RequestResponse \
  --durable-execution-name "test-failure-$(date +%s)" \
  --payload '{"bucket":"TU-BUCKET","key":"photos/test.jpg"}' \
  --cli-binary-format raw-in-base64-out \
  response.json

En los logs de CloudWatch vas a ver algo como esto:

2026-04-23T10:00:00.000Z [INFO] Step 'validate-file' - executing
2026-04-23T10:00:01.234Z [INFO] File validated: jpeg, 1920x1080, 2.4MB
2026-04-23T10:00:01.235Z [INFO] Step 'validate-file' - completed ✓
2026-04-23T10:00:01.300Z [INFO] Step 'resize-image' - executing
2026-04-23T10:00:01.301Z [ERROR] Resize attempt 1 failed - simulating network error
2026-04-23T10:00:02.500Z [INFO] Step 'resize-image' - retrying (attempt 2)
2026-04-23T10:00:02.501Z [ERROR] Resize attempt 2 failed - simulating network error
2026-04-23T10:00:04.800Z [INFO] Step 'resize-image' - retrying (attempt 3)
2026-04-23T10:00:05.120Z [INFO] Resize attempt 3 succeeded
2026-04-23T10:00:05.121Z [INFO] Step 'resize-image' - completed ✓
2026-04-23T10:00:05.200Z [INFO] Step 'apply-watermark' - executing
...

Fíjate en lo que no aparece: no hay un segundo Step 'validate-file' - executing. El step de validación se completó en el primer intento, se guardó el checkpoint, y en los reintentos del resize no se volvió a ejecutar.

Eso es el replay model haciendo su trabajo. El progreso no se pierde.

Estrategias de reintento

En el ejemplo anterior, el SDK reintentó automáticamente. Pero en producción necesitas control fino sobre cómo y cuándo reintentar.

Cada step acepta un retryStrategy que te permite configurar. El SDK provee un helper createRetryStrategy() para construir estrategias con configuración declarativa:

import { createRetryStrategy, JitterStrategy } from '@aws/durable-execution-sdk-js';

const retryStrategy = createRetryStrategy({
  maxAttempts: 5,                    // Total de intentos (incluyendo el primero)
  initialDelay: { seconds: 1 },     // Espera inicial: 1 segundo
  backoffRate: 2,                    // Multiplica el tiempo de espera entre reintentos: 1s → 2s → 4s → 8s
  maxDelay: { seconds: 30 },        // Tope máximo: 30 segundos
  jitter: JitterStrategy.FULL,      // Variación aleatoria 
});

También puedes escribir una estrategia custom como función directa:

const result = await context.step('call-api', async () => callAPI(), {
  retryStrategy: (error, attemptCount) => {
    if (attemptCount >= 5) return { shouldRetry: false };
    const delay = Math.min(2 * Math.pow(2, attemptCount - 1), 30);
    return { shouldRetry: true, delay: { seconds: delay } };
  }
});

Exponential backoff: por qué importa

Si un servicio está caído y reintentamos inmediatamente, lo único que logramos es bombardearlo con requests mientras intenta recuperarse. Es como tocar el timbre 50 veces cuando alguien no abre la puerta.

El exponential backoff resuelve esto: cada reintento espera más que el anterior.

Intento 1: falla → espera 1 segundo
Intento 2: falla → espera 2 segundos
Intento 3: falla → espera 4 segundos
Intento 4: falla → espera 8 segundos
Intento 5: falla → se rinde

Esto le da tiempo al servicio para recuperarse sin ahogarlo con requests.

Aplicando retry strategy al step de watermark

const watermarked = await context.step(
  'apply-watermark',
  async () => {
    const buffer = Buffer.from(resizedBase64, 'base64');

    // Llamada a un servicio externo de watermark
    const response = await fetch('https://watermark-api.example.com/apply', {
      method: 'POST',
      body: buffer,
      headers: { 'Content-Type': 'application/octet-stream' },
    });

    if (!response.ok) {
      throw new Error(`Watermark API failed: ${response.status}`);
    }

    const watermarkedBuffer = Buffer.from(await response.arrayBuffer());
    const watermarkedKey = `${outputPrefix}/${baseName}-watermarked${ext}`;

    await s3.send(new PutObjectCommand({
      Bucket: outputBucket,
      Key: watermarkedKey,
      Body: watermarkedBuffer,
    }));

    return watermarkedKey;
  },
  {
    retryStrategy: createRetryStrategy({
      maxAttempts: 5,
      initialDelay: { seconds: 2 },
      backoffRate: 2,
      maxDelay: { seconds: 30 },
    })
  }
);

Qué errores reintentar y cuáles no

No todos los errores merecen un reintento. Si el servicio devuelve un 404 Not Found, reintentarlo 5 veces no va a cambiar nada. Pero un 503 Service Unavailable sí puede resolverse con tiempo.

Regla general:

Error	¿Reintentar?	Por qué
Timeout / ENETUNREACH	✅	Problema de red transitorio
429 Too Many Requests	✅	Rate limiting, esperar ayuda
500 Internal Server Error	✅	El servidor puede recuperarse
503 Service Unavailable	✅	Servicio temporalmente caído
400 Bad Request	❌	Los datos están mal, reintentar no cambia nada
404 Not Found	❌	El recurso no existe
403 Forbidden	❌	No tienes permisos
Formato de archivo inválido	❌	El archivo no va a cambiar

Para errores que no deberían reintentarse, puedes lanzar un error específico y manejarlo con try/catch (lo vemos en el siguiente escenario).

Rompiendo cosas a propósito — Escenario 2: Fallo permanente

No todos los fallos se resuelven reintentando. A veces el archivo está corrupto, el formato no es soportado, o los datos de entrada son inválidos. Reintentar 100 veces no va a arreglar un PNG roto.

Para estos casos necesitas manejo de errores explícito con try/catch y lógica de compensación. El enfoque más robusto es envolver los steps que pueden fallar permanentemente en un try/catch y ejecutar la compensación en un step separado:

Simulando un archivo corrupto

export const handler = withDurableExecution(async (event: ImageEvent, context: DurableContext) => {
  const outputBucket = event.outputBucket ?? event.bucket;
  const outputPrefix = event.outputPrefix ?? 'processed';
  const baseName = event.key.replace(/\.[^.]+$/, '');
  const ext = event.key.match(/\.[^.]+$/)?.[0] ?? '.jpg';

  let imageBuffer: string;

  try {
    // Step 1: Validar el archivo
    imageBuffer = await context.step('validate-file', async () => {
      const response = await s3.send(new GetObjectCommand({
        Bucket: event.bucket,
        Key: event.key,
      }));

      if (!response.Body) {
        throw new Error(`File not found: ${event.key}`);
      }

      const buffer = Buffer.from(await response.Body.transformToByteArray());
      const metadata = await sharp(buffer).metadata();

      if (!metadata.format || !['jpeg', 'png', 'webp', 'tiff'].includes(metadata.format)) {
        throw new Error(
          `Unsupported image format: ${metadata.format}. Supported: jpeg, png, webp, tiff`
        );
      }

      return buffer.toString('base64');
    });

  } catch (error) {
    // Compensación: notificar y limpiar
    await context.step('handle-validation-failure', async () => {
      context.logger.error('Validation failed, executing compensation', {
        error: (error as Error).message,
        key: event.key,
      });

      // Notificar al usuario
      await sns.send(new PublishCommand({
        TopicArn: process.env.NOTIFICATION_TOPIC_ARN,
        Subject: 'Image Processing Failed',
        Message: JSON.stringify({
          status: 'failed',
          reason: (error as Error).message,
          key: event.key,
          timestamp: new Date().toISOString(),
        }),
      }));

      // Mover el archivo a una carpeta de errores para revisión
      await s3.send(new CopyObjectCommand({
        Bucket: event.bucket,
        CopySource: `${event.bucket}/${event.key}`,
        Key: `errors/${event.key}`,
      }));
    });

    return {
      status: 'failed',
      reason: (error as Error).message,
      key: event.key,
    };
  }

  // Si llegamos aquí, la validación pasó. Continuar con el procesamiento...
  const resizedBase64 = await context.step('resize-image', async () => {
    // ... resize logic
  });

  // ... resto del workflow
});

Qué está pasando aquí

El step validate-file detecta que el formato no es soportado y lanza un error
El error no se reintenta porque es un fallo permanente (el archivo no va a cambiar)
El catch ejecuta un step de compensación: handle-validation-failure
La compensación notifica al usuario vía SNS y mueve el archivo a una carpeta de errores
La función retorna un resultado de fallo limpio

Fíjate que la compensación también está dentro de un context.step(). Esto es importante: si la función se cae mientras envía la notificación, el replay model se encarga de que no se pierda.

El patrón de compensación

La compensación es el "plan B" cuando algo falla de forma irrecuperable. No es solo loggear el error y seguir adelante. Es deshacer o mitigar el impacto del fallo.

Ejemplos de compensación:

Fallo	Compensación
Procesamiento de imagen falla	Notificar al usuario, mover archivo a revisión
Cobro duplicado	Emitir reembolso automático
Envío de email falla permanentemente	Registrar en cola de dead letters, alertar al equipo
Creación de recurso falla a mitad	Eliminar recursos parcialmente creados

La clave: cada step de compensación debe ser idempotente (ya llegaremos a eso). Si la compensación se ejecuta dos veces, el resultado debe ser el mismo.

Errores fuera de los steps

Hay un caso que confunde a muchos: ¿qué pasa cuando el error ocurre fuera de un context.step()?

export const handler = withDurableExecution(async (event: ImageEvent, context: DurableContext) => {
  // ⚠️ Este código está FUERA de un step
  const config = JSON.parse(event.config); // Si event.config no es JSON válido... 💥

  const validated = await context.step('validate-file', async () => {
    // ...
  });
});

Si JSON.parse falla, la función se cae antes de llegar a cualquier step. No hay checkpoint. No hay replay. No hay recuperación elegante.

Según la documentación oficial: cuando un error ocurre fuera de un step, el SDK marca la ejecución como FAILED y no la reintenta automáticamente. La ejecución termina ahí. No hay loop infinito de reintentos, pero tampoco hay recuperación. Tu workflow simplemente muere.

La regla: todo lo que puede fallar va dentro de un step

export const handler = withDurableExecution(async (event: ImageEvent, context: DurableContext) => {
  // ✅ Ahora el parseo está dentro de un step
  const config = await context.step('parse-config', async () => {
    try {
      return JSON.parse(event.config);
    } catch {
      // Retornar config por defecto si el parseo falla
      context.logger.warn('Invalid config, using defaults');
      return { maxWidth: 1920, maxHeight: 1080, quality: 80 };
    }
  });

  const validated = await context.step('validate-file', async () => {
    // ...
  });
});

Ahora si el parseo falla, el step lo maneja con un fallback. Y si la función se reintenta después de que este step completó, el resultado (ya sea el config parseado o el default) ya está en el checkpoint.

Regla práctica: si una línea de código puede lanzar una excepción, debería estar dentro de un step. El código fuera de los steps debe ser puramente determinístico: asignaciones simples, cálculos con datos del evento, cosas que nunca fallan.

¿Qué es idempotencia?

Antes de hablar de por qué la idempotencia importa en Durable Functions, hay que entender el concepto.

Una operación es idempotente cuando ejecutarla una vez produce exactamente el mismo resultado que ejecutarla múltiples veces con los mismos inputs.

Suena abstracto. Vamos con ejemplos.

La analogía del elevador

Presionas el botón del elevador. El elevador viene. Presionas el botón 10 veces más. El elevador sigue viniendo una sola vez. No vienen 11 elevadores.

Presionar el botón del elevador es una operación idempotente.

Ahora imagina un botón de "comprar" en una tienda online. Lo presionas una vez: se cobra $10. Lo presionas otra vez: se cobran otros $10. Ahora debes $20 por un solo producto.

Presionar el botón de comprar no es idempotente (a menos que lo diseñes para que lo sea).

En software

Algunas operaciones son naturalmente idempotentes:

// ✅ PUT: actualizar un registro con los mismos datos siempre da el mismo resultado
await dynamodb.send(new PutItemCommand({
  TableName: 'users',
  Item: { userId: { S: '123' }, name: { S: 'Ana' }, email: { S: 'ana@example.com' } }
}));
// Ejecutar esto 1 vez o 100 veces → el registro queda igual

// ✅ DELETE por ID: eliminar algo que ya no existe no causa error
await s3.send(new DeleteObjectCommand({
  Bucket: 'my-bucket',
  Key: 'photos/test.jpg'
}));
// Ejecutar esto 1 vez o 100 veces → el archivo no está

// ✅ Escribir en S3 con la misma key: sobrescribe con el mismo contenido
await s3.send(new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'processed/photo-resized.jpg', // Key fija y determinística
  Body: resizedBuffer,
}));
// Ejecutar esto 1 vez o 100 veces → el mismo archivo en la misma ubicación

Otras operaciones requieren diseño explícito para ser idempotentes:

// ❌ INSERT: cada ejecución crea un registro nuevo
await dynamodb.send(new PutItemCommand({
  TableName: 'orders',
  Item: {
    orderId: { S: crypto.randomUUID() }, // ID diferente cada vez
    amount: { N: '10' }
  }
}));
// Ejecutar 3 veces → 3 órdenes diferentes. Desastre.

// ❌ Envío de email: cada ejecución envía un email nuevo
await ses.send(new SendEmailCommand({
  Destination: { ToAddresses: ['user@example.com'] },
  Message: { Subject: { Data: 'Tu orden fue procesada' }, Body: { Text: { Data: '...' } } }
}));
// Ejecutar 3 veces → 3 emails. El usuario piensa que tiene 3 órdenes.

// ❌ Cobro: cada ejecución cobra de nuevo
await stripe.charges.create({ amount: 1000, currency: 'usd', source: token });
// Ejecutar 3 veces → 3 cobros de $10. El usuario paga $30.

Cómo hacer idempotente lo que no lo es

El patrón más común es usar una idempotency key: un identificador único que garantiza que la operación solo se ejecuta una vez.

// ✅ INSERT con idempotency key
const orderId = `order-${event.userId}-${event.timestamp}`; // Determinístico

await dynamodb.send(new PutItemCommand({
  TableName: 'orders',
  Item: {
    orderId: { S: orderId }, // Siempre el mismo para el mismo input
    amount: { N: '10' }
  },
  ConditionExpression: 'attribute_not_exists(orderId)', // Solo inserta si no existe
}));

// ✅ Cobro con idempotency key
await stripe.charges.create({
  amount: 1000,
  currency: 'usd',
  source: token,
  idempotencyKey: `charge-${event.userId}-${event.orderId}`, // Stripe ignora duplicados
});

// ✅ Email con deduplicación
const emailId = `email-${event.orderId}-confirmation`;
const alreadySent = await checkIfEmailSent(emailId); // Consulta a DynamoDB
if (!alreadySent) {
  await ses.send(new SendEmailCommand({ /* ... */ }));
  await markEmailAsSent(emailId);
}

La diferencia entre operaciones naturalmente idempotentes y las que requieren diseño es crucial. Las primeras "simplemente funcionan" en un contexto de reintentos. Las segundas necesitan que tú pienses en el caso de ejecución múltiple.

Idempotencia en Durable Functions: la regla que nadie te dice

Ahora que entiendes qué es idempotencia, conectemos con el replay model.

Cada step en una Durable Function debe ser idempotente.

¿Por qué? Porque el replay model puede re-ejecutar un step si:

La función se cae después de que el step ejecutó pero antes de que el checkpoint se guardara
Hay un error transitorio en el sistema de checkpoints
La función hace timeout justo en el momento del checkpoint

En estos casos (poco frecuentes pero reales), el step se ejecuta de nuevo con los mismos inputs. Si el step no es idempotente, tienes un problema.

El ejemplo del procesamiento de imágenes

Veamos dos versiones del step que sube la imagen procesada a S3:

// ❌ NO idempotente: genera un nombre aleatorio cada vez
const savedKey = await context.step('save-to-s3', async () => {
  const randomId = crypto.randomUUID(); // Diferente en cada ejecución
  const key = `processed/${randomId}.jpg`;

  await s3.send(new PutObjectCommand({
    Bucket: outputBucket,
    Key: key,
    Body: processedBuffer,
  }));

  return key;
});
// Si se ejecuta 2 veces: 2 archivos diferentes en S3
// processed/a1b2c3d4.jpg Y processed/e5f6g7h8.jpg

// ✅ Idempotente: usa un nombre determinístico basado en el input
const savedKey = await context.step('save-to-s3', async () => {
  const key = `processed/${baseName}-final${ext}`; // Siempre igual para el mismo input

  await s3.send(new PutObjectCommand({
    Bucket: outputBucket,
    Key: key,
    Body: processedBuffer,
  }));

  return key;
});
// Si se ejecuta 2 veces: el mismo archivo se sobrescribe
// processed/photo-final.jpg (una sola copia)

La diferencia es sutil pero crítica. En el primer caso, cada ejecución deja basura en S3. Y esa basura se acumula: archivos huérfanos que nadie usa pero que siguen sumando a tu factura de almacenamiento mes a mes. En el segundo, no importa cuántas veces se ejecute: el resultado es el mismo.

Checklist de idempotencia para tus steps

Antes de deployar, revisa cada step con estas preguntas:

[ ] ¿El step genera IDs aleatorios? → Usa IDs determinísticos basados en el input
[ ] ¿El step inserta registros en una base de datos? → Usa ConditionExpression o upsert
[ ] ¿El step envía emails o notificaciones? → Implementa deduplicación
[ ] ¿El step cobra dinero? → Usa idempotency keys del proveedor de pagos
[ ] ¿El step crea recursos en la nube? → Usa nombres determinísticos o verifica existencia antes de crear
[ ] ¿El step llama a una API externa que modifica estado? → Verifica si la API soporta idempotency keys

Si respondiste "sí" a alguna y no tienes protección, tu step no es idempotente. Y en un sistema con reintentos automáticos, eso es una bomba de tiempo.

AT_MOST_ONCE_PER_RETRY: la red de seguridad del SDK

Para operaciones críticas que no pueden ejecutarse dos veces (como cobros), el SDK ofrece una opción adicional: AT_MOST_ONCE_PER_RETRY semantics. Con esta configuración, si un step se interrumpe antes de guardar el checkpoint, el SDK no lo re-ejecuta en la siguiente invocación.

// Para operaciones que NUNCA deben duplicarse
const charge = await context.step('charge-payment', async () => {
  return chargeCard(event.amount);
}, {
  semantics: 'AT_MOST_ONCE_PER_RETRY'
});

El trade-off: si el step se interrumpe, puede que la operación se haya ejecutado pero no tengas el resultado. Tendrás que verificar manualmente (por ejemplo, consultar el sistema de pagos). Pero es mejor verificar un cobro que cobrar dos veces.

Usa AT_MOST_ONCE_PER_RETRY solo para operaciones donde la duplicación es peor que la incertidumbre. Para la mayoría de los steps, el default AT_LEAST_ONCE_PER_RETRY con diseño idempotente es la mejor opción.

Rompiendo cosas a propósito — Escenario 3: Timeout de la función

Este es el escenario más interesante. ¿Qué pasa cuando la Lambda se queda sin tiempo a mitad del workflow?

Imagina que tu función tiene un timeout de 30 segundos (el default de Lambda), pero el procesamiento completo tarda 45 segundos.

Step 1: validate-file     → 2 segundos  ✓ (checkpoint guardado)
Step 2: resize-image      → 5 segundos  ✓ (checkpoint guardado)
Step 3: apply-watermark   → 10 segundos ✓ (checkpoint guardado)
Step 4: generate-thumbnails → 15 segundos... ⏰ TIMEOUT a los 30 segundos
Step 5: save-to-s3        → nunca se ejecutó

La función se cae. Pero los primeros 3 steps tienen sus checkpoints guardados.

Cuando la función se invoca de nuevo (ya sea manualmente o por el retry automático):

Step 1: validate-file     → checkpoint existe → SKIP (0 segundos)
Step 2: resize-image      → checkpoint existe → SKIP (0 segundos)
Step 3: apply-watermark   → checkpoint existe → SKIP (0 segundos)
Step 4: generate-thumbnails → SIN checkpoint → ejecuta (15 segundos) ✓
Step 5: save-to-s3        → ejecuta (3 segundos) ✓
Total: 18 segundos → dentro del timeout ✓

El workflow completo tardó 45 segundos, pero ninguna invocación individual excedió los 30 segundos. El replay model distribuyó el trabajo entre múltiples invocaciones.

Pero espera... ¿y el `durableConfig.executionTimeout`?

Aquí hay una distinción importante:

Lambda timeout: cuánto tiempo puede correr una sola invocación de la función (máximo 15 minutos)
executionTimeout en durableConfig: cuánto tiempo puede correr el workflow completo a través de múltiples invocaciones (hasta 1 año)

// En tu CDK stack:
const imageFunction = new lambda.Function(this, 'ImageProcessing', {
  runtime: lambda.Runtime.NODEJS_24_X,
  handler: 'handler.handler',
  code: lambda.Code.fromAsset('dist'),
  timeout: cdk.Duration.minutes(5),  // Cada invocación: máximo 5 minutos
  durableConfig: {
    executionTimeout: cdk.Duration.hours(1),  // Workflow completo: máximo 1 hora
    retentionPeriod: cdk.Duration.days(7),
  },
});

Esto significa que tu workflow puede tardar hasta 1 hora en completarse, distribuido en tantas invocaciones de 5 minutos como necesite. El replay model se encarga de retomar donde quedó cada vez.

Para workflows de procesamiento de imágenes, 5 minutos por invocación suele ser suficiente. Pero para workflows que involucran aprobaciones humanas o esperas largas (que veremos en el próximo artículo), el executionTimeout de hasta 1 año es lo que hace posible esos patrones.

Monitoreando fallos en la consola

Ya rompiste cosas. Ahora necesitas ver qué pasó.

La consola de AWS Lambda tiene una pestaña dedicada para Durable Functions: Durable executions. Ahí puedes ver:

Lista de ejecuciones: todas las ejecuciones con su estado (running, completed, failed)
Detalle de cada ejecución: qué steps se completaron, cuáles fallaron, cuántos reintentos hubo
Datos de cada checkpoint: qué resultado guardó cada step
Timeline: cuánto tardó cada step y dónde ocurrieron los fallos

Tips para debugging efectivo

Nombra tus steps de forma descriptiva: 'validate-file' es mucho más útil que 'step-1' cuando estás buscando un fallo en la consola.
Usa context.logger: No uses console.log. El logger del contexto es replay-aware: no duplica logs cuando la función se reintenta. Además, incluye metadata del step actual automáticamente.

// ❌ console.log se duplica en cada replay
console.log('Processing image:', event.key);

// ✅ context.logger es replay-aware
context.logger.info('Processing image', { key: event.key });

Incluye contexto en los errores: Cuando lanzas un error, incluye datos que te ayuden a diagnosticar.

if (!metadata.format) {
  throw new Error(
    `Invalid image format. Key: ${event.key}, ` +
    `Size: ${buffer.length} bytes, ` +
    `First bytes: ${buffer.slice(0, 4).toString('hex')}`
  );
}

Revisa el estado de los checkpoints: En la consola, cada step muestra su resultado guardado. Si un step retornó datos inesperados, ahí lo vas a ver sin necesidad de reproducir el error.

Patrones de resiliencia

Antes de cerrar, un resumen de los patrones que cubrimos y algunos adicionales que deberías tener en tu toolkit:

1. Retry con backoff exponencial

Para fallos transitorios. Ya lo vimos en detalle.

await context.step('call-external-api', apiCall, {
  retryStrategy: createRetryStrategy({
    maxAttempts: 5,
    initialDelay: { seconds: 1 },
    backoffRate: 2,
    maxDelay: { seconds: 30 },
  })
});

2. Compensación

Para fallos permanentes. Ejecuta lógica de "deshacer" o "mitigar".

try {
  await context.step('charge-payment', chargeUser);
  await context.step('send-product', shipProduct);
} catch (error) {
  await context.step('refund-payment', refundUser); // Compensación
  await context.step('notify-failure', notifyUser);
}

3. Circuit breaker manual

Si un servicio externo está fallando consistentemente, no tiene sentido seguir intentando. Puedes implementar un circuit breaker básico verificando el estado del servicio antes de llamarlo.

const serviceHealth = await context.step('check-service-health', async () => {
  try {
    const response = await fetch('https://api.example.com/health');
    return response.ok;
  } catch {
    return false;
  }
});

if (!serviceHealth) {
  // El servicio está caído, no intentar
  await context.step('fallback-processing', async () => {
    context.logger.warn('External service down, using fallback');
    return processLocally(imageBuffer);
  });
} else {
  await context.step('external-processing', async () => {
    return processWithExternalService(imageBuffer);
  });
}

4. Dead letter queue para workflows irrecuperables

Cuando un workflow falla de forma definitiva y la compensación no es suficiente, envía los datos a una cola de dead letters para revisión manual.

try {
  // ... workflow completo
} catch (error) {
  await context.step('send-to-dlq', async () => {
    await sqs.send(new SendMessageCommand({
      QueueUrl: process.env.DLQ_URL,
      MessageBody: JSON.stringify({
        event,
        error: (error as Error).message,
        failedAt: new Date().toISOString(),
        executionId: context.executionId,
      }),
    }));
  });
}

Esto garantiza que ningún workflow se pierde silenciosamente. Alguien (o algo) puede revisar la cola y decidir qué hacer.

Lo que aprendiste

El replay model no es magia. Es un sistema de checkpoints que guarda el resultado de cada step y lo reutiliza cuando la función se reintenta. Los steps completados se saltan, los pendientes se ejecutan.

Los fallos transitorios se manejan con retry strategies configurables por step: exponential backoff, máximo de intentos, y topes de espera. Los fallos permanentes se manejan con try/catch y lógica de compensación: notificar, limpiar, revertir.

El código fuera de los steps se ejecuta en cada replay. Si puede fallar, debería estar dentro de un step. Si genera valores no determinísticos, definitivamente debería estar dentro de un step.

Cada step debe ser idempotente. Si se ejecuta dos veces con los mismos inputs, debe producir el mismo resultado. Para operaciones que no son naturalmente idempotentes (inserts, cobros, emails), usa idempotency keys y deduplicación.

Y la consola de AWS Lambda te da visibilidad completa: qué steps se completaron, cuáles fallaron, cuántos reintentos hubo, y qué datos se guardaron en cada checkpoint.

Rompimos cosas a propósito. Y el workflow sobrevivió.

Qué sigue

En tres artículos recorrimos el camino completo de Lambda Durable Functions: desde entender cuándo usarlas (y cuándo no), pasando por construir tu primera función con Kiro Power, hasta romper cosas a propósito para entender cómo el replay model mantiene tu progreso.

Si llegaste hasta aquí, ya tienes las herramientas para construir workflows resilientes en producción. Sabes cómo funcionan los checkpoints, cómo configurar retries con backoff exponencial, cómo manejar fallos permanentes con compensación, y por qué la idempotencia no es opcional.

Durable Functions tiene más por explorar: callbacks para aprobaciones humanas, waits que pausan ejecución sin costo, ejecución en paralelo con context.map(), e invocaciones entre funciones con context.invoke(). La documentación oficial y el SDK de Durable Execution cubren todo eso en detalle.

Construye. Rompe. Recupera. Esa es la promesa.

Si quieres profundizar en Durable Functions, estos recursos te llevan más lejos:

Documentación oficial de Lambda Durable Functions — El punto de partida para todo: callbacks, waits, ejecución en paralelo, y más
Best practices for Lambda durable functions — Determinismo, idempotencia, manejo de estado, y errores comunes
Durable Execution SDK — Retry Strategies — Referencia completa de createRetryStrategy, presets, y custom strategies
Durable Execution SDK (JavaScript) — Código fuente del SDK, open source
Proyecto de ejemplo de esta serie (GitHub) — El código completo del procesamiento de imágenes

Como funciona um site na internet

Giovana Armani — Thu, 23 Apr 2026 22:30:19 +0000

Você já parou pra pensar no que acontece entre digitar um endereço no navegador e ver a página carregada na sua tela? Como algo que pode ter sido criado em qualquer lugar no mundo chega tão rápido até a gente? Nesse artigo, vamos desvendar juntos o caminho que um site percorre até chegar até você.

Como sites são criados?

A parte que vemos e usamos para interagir com uma aplicação, ou seja, as telas, representam o que chamamos de front-end. Para sites web, o front-end é criado com linguagens de programação que rodam diretamente no navegador:

HTML — cria a estrutura dos elementos, o esqueleto da página. Com ele conseguimos inserir elementos como textos, botões, imagens, links, etc
CSS — ajuda a dar estilo aos componentes como cores, tamanho, posicionamento, animação
JavaScript — permite a interação com os componentes. Com ele conseguimos, por exemplo, ter uma ação quando um usuário clica num botão

Podemos abstrair essa estrutura básica usando frameworks JavaScript como React, Angular, Astro, entre outros. Esses frameworks facilitam a construção de interfaces complexas sem precisar escrever tudo do zero.

Além do código, um site também pode conter outros arquivos estáticos como imagens, vídeos, PDFs e outros documentos que são enviados diretamente ao navegador.

Onde moram os sites que vemos na internet?

Antes de mais nada, precisamos entender que tudo que encontramos na internet está em um servidor. Eles são super computadores especializados em diferentes tarefas. Eles podem armazenar, processar, gerenciar e transferir dados e arquivos, executar programas, enviar emails, disponibilizar conteúdo na
internet, entre muitas outras funções. Veja abaixo uma imagem de um servidor.

Quando você cria um site, os arquivos de código e conteúdo precisam ficar guardados em algum lugar acessível pela internet. Esse lugar é o que chamamos de servidor de origem (ou origin server). Ele armazena a versão principal e original do seu site.

Alguns exemplos de serviços que podem servir como servidor de origem para seus arquivos estáticos são o Amazon S3, GitHub Pages, Vercel, Netlify e Cloudflare Pages. Existem ainda softwares que você pode instalar em um servidor próprio que auxiliam na comunicação com a internet como apache, nginx e outros.

Mas como o navegador sabe onde encontrar esse servidor? Cada dispositivo conectado à internet possui um endereço único chamado IP (Internet Protocol, ou Protocolo de Internet). Gosto de pensar no IP como o endereço de um computador. Assim como uma carta precisa de um endereço para chegar na casa certa, o navegador precisa do IP para encontrar o servidor certo.

O IP é formado por uma sequência de caracteres, como por exemplo: 123.456.78.9. Existem alguns protocolos (conjuntos de regras) diferentes que podem determinar diferentes formatos para os endereços de IP.

Como podemos dar um nome bonito aos nossos sites?

Mas ninguém merece ficar digitando números e letras aleatórias pra entrar em qualquer site, né? Pra nossa sorte existem os domínios, que são os nomes bonitos que usamos para acessar os sites como github.com ou dev.to.

Existem ainda diferentes níveis de domínios que se compõem pra formar o nome completo do site:

Top Level Domains ou Domínios de Nível Superior (TLD): são as extensões finais dos domínios de internet. Podem ainda ser dos tipos:
- De código de país como .br, .uk, .jp
- Genericos como .com, .org, .net
Second Level Domains ou Domínios de Segundo Nível (SLD): representa o nome popular do site como amazon em amazon.com ou youtube em youtube.com
Subdomínios: Um prefixo que pode ser adicionado antes do SLD e mostra uma subdivisão do domínio como support em support.apple.com ou learn em learn.microsoft.com

Isso é ótimo para nós, mas os computadores ainda precisam saber qual é o IP original para conseguir levar o conteúdo até nossas máquinas. Para isso, existe o DNS (Domain Name System ou Sistema de Nomes de Domínio). Ele funciona como uma enorme lista de telefone da internet e mapeia os domínios para o endereço de IP correspondente.

Quando você digita google.com, por exemplo, o DNS traduz isso para o IP 142.250.80.46 e direciona sua chamada para o servidor correto.

O DNS é distribuído em vários servidores organizados em um sistema hierárquico como mostra a imagem abaixo.

Como acessamos o conteúdo de um site?

Agora que sabemos onde os sites moram e como damos nomes a eles, vamos entender como o conteúdo chega até você.

Quando você acessa um site, seu navegador precisa descobrir o IP do servidor que contém seus arquivos. Para isso, ele usa um resolver, um serviço que faz a busca pelo endereço IP correto. O resolver consulta a hierarquia de servidores DNS, começando pelos servidores raiz, até encontrar o IP associado ao domínio que você digitou. Com o IP, o navegador faz a requisição ao servidor correspondente e recebe o conteúdo de volta.

Parece simples, mas tem um problema: se o servidor de origem estiver nos Estados Unidos e você no Brasil, essa requisição vai percorrer uma longa distância e demorar mais tempo para chegar até você. É aí que entra a CDN (Content Delivery Network ou Rede de Entrega de Conteúdo).

Uma CDN é uma rede de servidores distribuídos pelo mundo todo que armazenam cópias dos seus arquivos em locais mais próximos dos usuários. Ao invés do navegador buscar uma imagem lá no servidor de origem nos Estados Unidos, ele pode buscar essa mesma imagem em um servidor CDN aqui no Brasil, que vai chegar muito mais rápido até você!

O fluxo funciona assim:

O navegador quer carregar o conteúdo de um site
A requisição vai para o servidor CDN mais próximo do usuário
Se o servidor CDN não tiver o arquivo, ele busca no servidor de origem
O servidor de origem envia o arquivo para o CDN
O CDN entrega o conteúdo ao navegador

Deixando sites mais rápidos: a mágica do cache

No fluxo que descrevemos acima, se o servidor CDN precisar buscar o conteúdo no servidor de origem a cada requisição, o ganho de velocidade não seria tão grande. Nesse caso, seria melhor nem ter o servidor CDN e ir direto para o servidor de origem. A grande vantagem do CDN está no cache.

Cache é um armazenamento temporário de alta velocidade que guarda cópias de dados acessados com frequência por certo tempo. Quando um servidor CDN recebe um arquivo do servidor de origem, ele guarda uma cópia. Na próxima vez que alguém pedir o mesmo arquivo, o CDN já tem ele guardado e entrega direto, sem precisar ir até a origem de novo.

De tempos em tempos, conteúdos que não são acessados pelo cache são apagados, para que o cache mantenha sempre um registro dos conteúdos mais relevantes.

O processo funciona assim:

O usuário faz uma requisição de conteúdo
O servidor CDN mais próximo verifica se tem o conteúdo em cache
Se tiver em cache → entrega direto para o navegador (rápido!)
Se não tiver ou estiver expirado → busca no servidor de origem, guarda em cache e depois entrega

Aproveitando para passar uns conceitos para sua próxima entrevista de design de sistemas, quando o conteúdo que queremos acessar está disponível no cache, chamamos isso de cache hit, que indica o acerto. Já quando o conteúdo não está em cache, chamamos de cache miss.

O benefício do cache é diminuição de latência, ou seja, do tempo que demora para completar a requisição. O conteúdo chega mais rápido porque está mais perto. Além disso, como o CDN guarda uma cópia dos arquivos por um tempo, menos requisições são feitas ao servidor de origem, prevenindo sua sobrecarga.

Conclusão

Agora você já sabe o caminho que um site percorre até chegar na sua tela! Veja abaixo um glossário com os principais termos que vimos:

Termo	Significado
HTML	Linguagem de marcação que define a estrutura da página
CSS	Linguagem de estilo que define a aparência da página
JavaScript	Linguagem de programação que permite interação com os componentes
IP	Internet Protocol - Endereço numérico único que identifica dispositivos na internet
DNS	Domain Name System - Sistema que traduz nomes de domínio em endereços IP
TLD	Domínio de nível superior como .com, .br, .org
SLD	Domínio de nível inferior que representa o nome do site
CDN	Content Delivery Network - Rede de servidores distribuídos que entregam conteúdo mais perto do usuário
Cache	Armazenamento temporário que guarda cópias de dados para acesso mais rápido

Quer colocar a mão na massa e publicar seu próprio site na internet? Confira meu artigo sobre seus primeiros passos com computação em nuvem onde deployamos uma página pessoal gratuitamente usando AWS Amplify!

E aí, ficou mais claro como a internet funciona por trás dos panos? Se tiver dúvidas ou quiser compartilhar feedback, fique à vontade para me procurar!

Two Pointers en entrevistas técnicas: 3 problemas resueltos

Axel Espinosa — Wed, 22 Apr 2026 20:31:27 +0000

Si estás preparándote para entrevistas técnicas, tarde o temprano vas a encontrarte con problemas de arrays y strings. Y varios se resuelven con una misma familia de técnicas: two pointers.

En los artículos anteriores vimos cómo funcionan los arrays y los strings por debajo: memoria contigua, acceso por índice, operaciones y sus costos. Hoy toca usar todo eso para resolver problemas reales.

Lo que vas a encontrar en este artículo:

Qué son las entrevistas técnicas y por qué te piden resolver problemas

Qué es two pointers y qué técnicas incluye

Cómo identificar cuál técnica usar

Un problema resuelto paso a paso por cada técnica

¿Qué son los problemas de entrevistas técnicas?

Son ejercicios de programación que te ponen en entrevistas para puestos de desarrollo de software. Ojo, las entrevistas técnicas existen para muchos roles (arquitectura, DevOps, SRE, developer) y no todas se ven igual. Este artículo se enfoca en las entrevistas para roles de developer.

El objetivo no es que te sepas la respuesta de memoria. Lo que evalúan es cómo piensas: cómo descompones un problema, qué estructura de datos eliges y si tu solución es eficiente.

Y aquí viene lo interesante: existen técnicas que se crearon específicamente para resolver estos problemas de forma óptima. No es magia, es práctica y reconocimiento de patrones.

¿Qué es Two Pointers?

Two pointers es un paradigma general para resolver problemas con arrays y strings. La idea es simple: usas dos variables (los "punteros") que recorren la estructura de datos de formas específicas.

Ojo, cuando digo "punteros" no me refiero a punteros de memoria como en C. Aquí son simplemente variables que guardan índices para acceder a posiciones del array o string.

¿Por qué funciona? Porque con dos punteros moviéndose de forma inteligente, puedes evitar soluciones de fuerza bruta O(n²) y resolverlo en O(n). Eso es exactamente lo que buscan en una entrevista.

¿Qué técnicas incluye?

Two pointers incluye tres variantes principales:

Fast and slow pointers (lento y rápido): un puntero explora y otro se queda marcando una posición.
Opposite direction pointers (punteros convergentes): empiezan en los extremos y se acercan al centro.
Parallel pointers (punteros paralelos): cada puntero recorre un array diferente al mismo tiempo.

Lo que todas tienen en común: usan al menos 2 variables para recorrer un arreglo o string, y nos ayudan a pasar de O(n²) a O(n).

Vamos a usar los nombres en inglés porque así los encuentras en la mayoría de recursos, LeetCode y entrevistas.

¿Cómo saber cuál técnica usar?

Antes de entrar a los problemas, una guía rápida. Si en el enunciado ves algo de esto, probablemente necesitas two pointers:

Te dan uno o dos arreglos/strings.
Te piden espacio O(1) o modificar el array en su lugar.
La solución obvia sería O(n²) pero necesitas algo mejor.

Ahora, ¿cuál variante? Aquí va un resumen:

Técnica	Úsala cuando...
Fast and slow	Necesitas comparar o modificar elementos dentro del mismo array
Opposite direction	Necesitas verificar propiedades simétricas, encontrar pares, o trabajar desde los extremos
Parallel pointers	Tienes dos arrays y necesitas compararlos o fusionarlos

Sé que puede parecer mucho, pero conforme resolvamos los problemas vas a ver que es más intuitivo de lo que parece. Vamos a eso.

Opposite direction: Verificar un palíndromo

Empecemos con opposite direction porque es la más visual.

Tomemos el problema "Valid Palindrome" de LeetCode:

Problema:
Una frase es un palíndromo si, tras convertir todas las letras a minúsculas y eliminar los caracteres no alfanuméricos, se lee igual de izquierda a derecha que de derecha a izquierda.

Dada una cadena s, devuelve true si es un palíndromo, o false en caso contrario.

Ejemplos

Input:  s = "A man, a plan, a canal: Panama"
Output: true
// Porque "amanaplanacanalpanama" se lee igual en ambas direcciones

Input:  s = "race a car"
Output: false
// Porque "raceacar" no es palíndromo

Input:  s = " "
Output: true
// Un string vacío se lee igual al derecho y al revés

¿Cómo lo pensamos?

La solución de fuerza bruta sería limpiar el string, invertirlo y comparar. Funciona, pero crea strings nuevos en memoria (recuerda que los strings son inmutables, así que cada operación crea uno nuevo).

Con opposite direction pointers hacemos algo más elegante: ponemos un puntero al inicio y otro al final. Los vamos acercando al centro comparando los caracteres. Si en algún momento no coinciden, no es palíndromo. Si los punteros se cruzan sin encontrar diferencias, sí lo es.

Solución paso a paso

/**
 * @param {string} s
 * @return {boolean}
 */
var isPalindrome = function (s) {
  let l = 0;
  let r = s.length - 1;

  while (l < r) {
    if (!isAlphanumeric(s[l])) {
      l++;
    } else if (!isAlphanumeric(s[r])) {
      r--;
    } else if (s[l].toLowerCase() !== s[r].toLowerCase()) {
      return false;
    } else {
      l++;
      r--;
    }
  }
  return true;
};

// función auxiliar: ¿es letra o número?
function isAlphanumeric(char) {
  const code = char.charCodeAt(0);
  return (
    (code >= 48 && code <= 57) || // 0-9
    (code >= 65 && code <= 90) || // A-Z
    (code >= 97 && code <= 122) // a-z
  );
}

Vamos línea por línea:

l arranca en 0 (inicio del string) y r en s.length - 1 (final). Son nuestros dos punteros que se van a acercar al centro.
El while (l < r) se ejecuta mientras los punteros no se hayan cruzado.
Dentro del loop hay cuatro casos:
- Si s[l] no es alfanumérico (un espacio, coma, dos puntos...), lo saltamos moviendo l a la derecha.
- Si s[r] no es alfanumérico, lo saltamos moviendo r a la izquierda.
- Si ambos son alfanuméricos pero no coinciden (comparando en minúsculas), no es palíndromo. Retornamos false.
- Si coinciden, avanzamos ambos punteros hacia el centro (l++, r--).
Si el loop termina sin retornar false, los punteros se cruzaron sin encontrar diferencias. Es palíndromo, retornamos true.

La función auxiliar isAlphanumeric revisa el código ASCII del carácter: 48-57 son dígitos, 65-90 letras mayúsculas, 97-122 letras minúsculas. Todo lo demás (espacios, puntuación, etc.) retorna false.

💡 Complejidad: O(n) en tiempo, O(1) en espacio. Un solo recorrido del string, sin crear copias ni estructuras extra.

Veamos cómo se ve con s = "A man, a plan, a canal: Panama":

Fast and slow: Remove Duplicates

Ahora veamos fast and slow con el clásico "Remove Duplicates from Sorted Array" de LeetCode:

Problema:
Te dan una lista de números nums ya ordenada de menor a mayor, pero con algunos repetidos. Tienes que dejar cada número una sola vez, moviendo los únicos al inicio de la misma lista (sin crear otra lista nueva).
Por ejemplo, si te dan [1, 1, 2, 3, 3], la lista debe quedar así: [1, 2, 3, ?, ?]. Los primeros tres espacios tienen los números únicos en orden, y los últimos dos espacios no importan (pueden quedar con cualquier valor, por eso los marcamos con ?).
Además, tu función debe devolver cuántos números únicos quedaron al inicio. En el ejemplo anterior, devolverías 3 porque hay tres números únicos (1, 2, 3). A ese número lo llaman k en el enunciado.

Ejemplos

Ejemplo 1

Entrada: nums = [1,1,2]
Salida: 2, nums = [1,2,_]

Explicación: Tu función debe devolver k = 2, y los primeros dos elementos de nums deben ser 1 y 2 respectivamente. No importa qué quede después de los primeros k espacios (por eso aparecen como guiones bajos).

Ejemplo 2

Entrada: nums = [0,0,1,1,1,2,2,3,3,4]
Salida: 5, nums = [0,1,2,3,4,_,_,_,_,_]

Explicación: Tu función debe devolver k = 5, y los primeros cinco elementos de nums deben ser 0, 1, 2, 3 y 4 respectivamente. No importa qué quede después de los primeros k espacios (por eso aparecen como guiones bajos).

¿Cómo lo pensamos?

La fuerza bruta sería crear un nuevo array y copiar solo los valores que no se repiten. Pero el problema dice explícitamente que lo hagas "in-place", o sea, modificando el mismo array sin crear otro. Ahí es donde entra fast and slow.

La idea es esta: usamos dos punteros que arrancan casi juntos. slow marca la posición donde va el siguiente número único. fast se adelanta recorriendo todo el array buscando valores nuevos.

Como el array ya está ordenado, los duplicados siempre están juntos. Entonces fast solo necesita comparar su valor con el de slow. Si son diferentes, encontramos un número nuevo: avanzamos slow una posición y copiamos ahí el valor de fast. Si son iguales, fast simplemente sigue avanzando.

Piénsalo así: slow es el que construye la respuesta, y fast es el explorador que le dice "oye, encontré uno nuevo".

Solución paso a paso

/**
 * @param {number[]} nums
 * @return {number}
 */
var removeDuplicates = function (nums) {
  let slow = 0;
  for (let fast = 1; fast < nums.length; fast++) {
    if (nums[fast] !== nums[slow]) {
      slow++;
      nums[slow] = nums[fast];
    }
  }
  return slow + 1;
};

Vamos línea por línea:

slow arranca en 0, apuntando al primer elemento. Ese siempre es único porque no hay nada antes con qué comparar.
fast arranca en 1 y recorre el array completo con el for.
En cada paso, comparamos nums[fast] con nums[slow]:
- Si son iguales, es un duplicado. fast avanza y slow se queda donde está. No hacemos nada.
- Si son diferentes, encontramos un valor nuevo. Avanzamos slow una posición (slow++) y copiamos el valor de fast ahí (nums[slow] = nums[fast]).
Al final, slow queda apuntando al último elemento único. Como los índices empiezan en 0, el total de únicos es slow + 1.

Veamos cómo se ve con nums = [0, 0, 1, 1, 1, 2, 2, 3, 3, 4]:

Los primeros 5 elementos son [0, 1, 2, 3, 4], exactamente los valores únicos en orden. Lo que queda después del índice 4 no importa.

¿Ves el patrón? fast recorre todo el array una sola vez, y slow solo avanza cuando encuentra algo nuevo. Eso nos da O(n) en tiempo y O(1) en espacio, porque no creamos ninguna estructura extra.

💡 Complejidad: O(n) en tiempo, O(1) en espacio. Un solo recorrido, sin estructuras extra.

Parallel pointers: Intersección de dos arrays

Por último, parallel pointers con "Intersection of Two Arrays" de LeetCode:

Problema:
Dados dos arreglos de enteros, devuelve un arreglo con su intersección. Cada elemento del resultado debe ser único y puede estar en cualquier orden.

Ejemplos

Input:  nums1 = [1, 2, 2, 1], nums2 = [2, 2]
Output: [2]

Input:  nums1 = [4, 9, 5], nums2 = [9, 4, 9, 8, 4]
Output: [9, 4]  // el orden no importa

¿Cómo lo pensamos?

La fuerza bruta sería usar dos loops anidados: por cada elemento de nums1, recorrer todo nums2 buscando coincidencias.

Con parallel pointers hacemos algo más inteligente: primero ordenamos ambos arrays y después los recorremos una sola vez con dos punteros. Como están ordenados, podemos comparar los valores y decidir cuál puntero mover:

Si los valores son iguales, encontramos una intersección. Avanzamos ambos.
Si el valor de p1 es menor, lo avanzamos porque no puede haber coincidencia más atrás en nums2.
Si el valor de p2 es menor, lo avanzamos por la misma razón.

Es como hacer merge de dos listas ordenadas, pero solo nos quedamos con los valores que aparecen en ambas.

Solución paso a paso

/**
 * @param {number[]} nums1
 * @param {number[]} nums2
 * @return {number[]}
 */
var intersection = function (nums1, nums2) {
  let p1 = 0,
    p2 = 0;

  // ordenar arreglos
  nums1.sort((a, b) => a - b);
  nums2.sort((a, b) => a - b);
  const intersection = [];

  while (p1 < nums1.length && p2 < nums2.length) {
    if (nums1[p1] === nums2[p2]) {
      // Evita duplicados en el resultado
      if (
        intersection.length === 0 ||
        intersection[intersection.length - 1] !== nums1[p1]
      ) {
        intersection.push(nums1[p1]);
      }
      p1++;
      p2++;
    } else if (nums1[p1] < nums2[p2]) {
      p1++;
    } else {
      p2++;
    }
  }

  return intersection;
};

Vamos línea por línea:

Ordenamos ambos arrays con .sort(). Esto es clave: sin el orden, no podríamos saber hacia dónde mover los punteros.
p1 y p2 arrancan en 0, cada uno apuntando al inicio de su array.
El while se ejecuta mientras ambos punteros estén dentro de sus arrays.
Dentro del loop hay tres casos:
- Si nums1[p1] === nums2[p2], encontramos un valor en común. Antes de agregarlo, verificamos que no sea un duplicado (comparando con el último elemento del resultado). Avanzamos ambos punteros.
- Si nums1[p1] < nums2[p2], el valor de p1 es más chico. Como ambos arrays están ordenados, ese valor no puede existir más adelante en nums2. Avanzamos p1.
- Si nums1[p1] > nums2[p2], misma lógica pero al revés. Avanzamos p2.
Cuando alguno de los dos punteros llega al final de su array, el loop termina. Ya no puede haber más intersecciones.

Veamos con nums1 = [4, 9, 5], nums2 = [9, 4, 9, 8, 4]:

¿Ves cómo cada puntero solo avanza hacia adelante? Nunca retroceden. El recorrido en sí es O(n + m), pero el ordenamiento inicial domina: O(n log n + m log m) en total.

💡 Complejidad: O(n log n + m log m) en tiempo por el ordenamiento. O(n) en espacio para el resultado.

Resumen

Estas tres técnicas son variantes de un mismo concepto: usar dos punteros para recorrer arrays o strings de forma eficiente.

Técnica	Movimiento de punteros	Problema resuelto
Opposite direction	De los extremos al centro	Valid Palindrome
Fast and slow	Uno explora, otro referencia	Remove Duplicates
Parallel pointers	Cada uno en su array	Intersection of Two Arrays

La clave no es memorizar las soluciones. Es reconocer el patrón en el enunciado y saber qué técnica aplicar. Con práctica, vas a leer un problema y saber qué variante de two pointers usar antes de escribir una línea de código.

Si quieres seguir practicando, aquí te dejo más problemas de LeetCode:

¿Cuál técnica te costó más entender? ¿Hay algún problema que quieras que resolvamos juntos? Déjamelo en los comentarios. 🙌🏻

Build your own blog post view counter on AWS Free Tier

Esin Saribudak — Tue, 21 Apr 2026 19:35:19 +0000

Your blog deserves to know it's being read. A Lambda function counts the views, DynamoDB remembers them, and it's all eligible for the Free Tier.

Last updated: April 20, 2026

Most analytics tools require an account, a script tag, and a separate dashboard you have to check outside your infrastructure. If you're already on AWS, you can build a view counter that lives in your own account and stores data in a table you control. It takes about an hour, and all three services it uses are eligible for the AWS Free Tier.

This tutorial walks you through building that counter. You add one <script> tag to your blog, and every time someone reads a post, the count goes up in a DynamoDB table you own.

Along the way, you'll wire together Lambda, DynamoDB, and API Gateway into something that goes beyond "Hello World." By the end, you'll have working software on your blog and hands-on experience with the same services that power production applications.

If you've already set up your AWS account and deployed something to the cloud before, this is a good next project. If you haven't, start with a free AWS account and come back.

What you're building

Here's the application flow:

A visitor loads your blog post in a browser
A small script on your page sends a request to API Gateway
API Gateway invokes a Lambda function
Lambda checks DynamoDB to see if this visitor has already been counted today
If they're new, it increments the counter
API Gateway returns a 204 response to the client

Two serverless services for compute and storage, one API layer in front, about 100 lines of TypeScript.

The counter deduplicates by IP address (hashed, so you're not storing raw IPs) and auto-cleans old records with DynamoDB's TTL feature. You add it to your blog with a single <script> tag, and it automatically tracks every page.

Prerequisites

An AWS account. If you don't have one yet, the Creating an AWS account guide walks you through it. You'll need a credit card on file, but this project stays within Free Tier limits.
Node.js 24 or later
AWS CLI installed and configured. Follow the AWS CLI quickstart if this is your first time.
AWS CDK bootstrapped in your account:

npx cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1

If you haven't used CDK before, it's an AWS infrastructure-as-code tool. You write TypeScript that describes your AWS resources, and CDK turns it into CloudFormation and deploys it. The bootstrap command creates a staging bucket CDK needs to upload your code. The CDK getting started guide has more information if you want it.

Project setup

Create a new directory and initialize the project:

mkdir blog-post-view-counter && cd blog-post-view-counter
npm init -y
npm install aws-cdk-lib constructs @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm install -D aws-cdk tsx typescript @types/node

Create a cdk.json file in the project root. This tells CDK how to run your app:

{
  "app": "npx tsx cdk/app.ts"
}

And a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "dist",
    "rootDir": ".",
    "strict": true,
    "types": ["node"],
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["lambda/**/*", "cdk/**/*"]
}

Your project structure will look like this:

blog-post-view-counter/
├── cdk/
│   ├── app.ts          # CDK entry point
│   └── stack.ts        # Infrastructure definition
├── lambda/
│   └── index.ts        # Lambda function code
├── cdk.json
├── package.json
└── tsconfig.json

Step 1: The DynamoDB table

DynamoDB is a key-value database. You give it a key, it gives you back the data. No servers to manage, no connection strings to configure.

Our table stores two kinds of records using a composite key (pk + sk):

Counter records track views per page:

pk	sk	views
`/blog/my-first-post`	`counter`	42
`/about`	`counter`	17

Dedup records prevent the same person from being counted twice:

pk	sk	ttl
`/blog/my-first-post#a1b2c3d4...`	`dedup`	1745208000

The dedup key combines the page path with a hash of the visitor's IP. The ttl field is a Unix timestamp 24 hours in the future. DynamoDB automatically deletes expired records, so the same visitor gets counted again the next day.

Think of it like a filing cabinet. Each drawer is labeled with a page path. Inside, there's a counter folder with the view count, and temporary visitor sign-in sheets that get shredded after 24 hours.

Step 2: The Lambda function

Create lambda/index.ts. This is the code that runs every time someone visits your blog:

import { createHash } from 'node:crypto';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, GetCommand, PutCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';

// DynamoDB document client — lets us read/write JS objects instead of raw DynamoDB types
const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE_NAME = process.env.TABLE_NAME!;
const DEDUP_HOURS = 24;

// These come from environment variables set in the CDK stack
const ALLOWED_ORIGIN = process.env.ALLOWED_ORIGIN || '*';
const ALLOWED_HOSTNAME = ALLOWED_ORIGIN !== '*' ? new URL(ALLOWED_ORIGIN).hostname : null;

// CORS headers — browsers require these when your blog (yourdomain.com)
// makes a fetch() to a different domain (your API Gateway URL)
const CORS_HEADERS = {
  'Access-Control-Allow-Origin': ALLOWED_ORIGIN,
  'Access-Control-Allow-Methods': 'GET,OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type',
};

// Only allow typical blog URL paths — letters, numbers, hyphens, slashes, dots
const VALID_PATH = /^\/[\w\-./]{0,199}$/;

// Hash an IP so we never store raw addresses in DynamoDB (GDPR-friendly)
function hashIp(ip: string): string {
  return createHash('sha256').update(ip).digest('hex').slice(0, 16);
}

export const handler = async (event: any) => {
  // Handle CORS preflight — browsers send this before the real request
  if (event.httpMethod === 'OPTIONS') {
    return { statusCode: 204, headers: CORS_HEADERS, body: '' };
  }

  const page = event.queryStringParameters?.page || '/';

  // Reject paths that don't look like blog URLs
  if (!VALID_PATH.test(page)) {
    return { statusCode: 400, headers: CORS_HEADERS, body: '' };
  }

  // If a Referer header exists, make sure it's from your site
  if (ALLOWED_HOSTNAME) {
    const referer = event.headers?.referer || event.headers?.Referer || '';
    if (referer && !referer.includes(ALLOWED_HOSTNAME)) {
      return { statusCode: 403, headers: CORS_HEADERS, body: '' };
    }
  }

  // Combine page path + hashed IP to create a unique dedup key
  const ip = event.requestContext?.identity?.sourceIp || 'unknown';
  const dedupKey = `${page}#${hashIp(ip)}`;
  const now = Math.floor(Date.now() / 1000);
  const ttl = now + DEDUP_HOURS * 3600; // DynamoDB TTL auto-deletes after 24h

  // Check if this visitor was already counted for this page today
  let isNewView = true;
  try {
    const existing = await client.send(new GetCommand({
      TableName: TABLE_NAME,
      Key: { pk: dedupKey, sk: 'dedup' },
    }));
    if (existing.Item) isNewView = false;
  } catch {
    // If lookup fails, count it as a new view
  }

  if (isNewView) {
    // Write a dedup record so this IP won't be counted again for 24h
    await client.send(new PutCommand({
      TableName: TABLE_NAME,
      Item: { pk: dedupKey, sk: 'dedup', ttl },
    }));

    // Increment the page's view counter (ADD creates the item if it doesn't exist)
    await client.send(new UpdateCommand({
      TableName: TABLE_NAME,
      Key: { pk: page, sk: 'counter' },
      UpdateExpression: 'ADD #v :inc',
      ExpressionAttributeNames: { '#v': 'views' },
      ExpressionAttributeValues: { ':inc': 1 },
    }));
  }

  // 204 No Content — the browser doesn't need a response body
  return { statusCode: 204, headers: CORS_HEADERS, body: '' };
};

The code comments cover the details, but here's the high-level flow: the function validates the incoming page path, checks the Referer header, then hashes the visitor's IP with SHA-256 so no raw addresses end up in your database. It looks up the hashed IP in DynamoDB to see if this visitor was already counted today. If not, it writes a dedup record (which DynamoDB auto-deletes after 24 hours via TTL) and atomically increments the page's view counter. The browser gets back a 204 No Content, meaning "got it, nothing to show you."

Step 3: The infrastructure

Create cdk/stack.ts. This defines all three AWS resources:

import * as cdk from 'aws-cdk-lib';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { Runtime } from 'aws-cdk-lib/aws-lambda';
import * as path from 'path';
import { fileURLToPath } from 'url';
import { Construct } from 'constructs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export class ViewCounterStack extends cdk.Stack {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // Read your blog's domain from the deploy command:
    //   npx cdk deploy -c blogOrigin=https://yourdomain.com
    const blogOrigin = this.node.tryGetContext('blogOrigin');
    if (!blogOrigin) {
      throw new Error('Missing required context: -c blogOrigin=https://yourdomain.com');
    }

    // DynamoDB table — stores page view counts and IP dedup records
    const table = new dynamodb.Table(this, 'ViewCounterTable', {
      partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
      sortKey: { name: 'sk', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PROVISIONED,
      readCapacity: 25,  // 25 RCU is within the always-free tier
      writeCapacity: 25, // 25 WCU is within the always-free tier
      timeToLiveAttribute: 'ttl', // Auto-delete dedup records after 24h
      removalPolicy: cdk.RemovalPolicy.DESTROY, // Clean up on `cdk destroy`
    });

    // Lambda function — NodejsFunction bundles TypeScript with esbuild automatically
    const fn = new NodejsFunction(this, 'CounterFunction', {
      runtime: Runtime.NODEJS_24_X,
      entry: path.join(__dirname, '../lambda/index.ts'),
      handler: 'handler',
      environment: {
        TABLE_NAME: table.tableName,
        ALLOWED_ORIGIN: blogOrigin, // Passed to Lambda for CORS and Referer checks
      },
      timeout: cdk.Duration.seconds(10),
      memorySize: 128,
    });

    // Give the Lambda read/write access to the DynamoDB table
    table.grantReadWriteData(fn);

    // API Gateway — public HTTPS endpoint that triggers the Lambda
    const api = new apigateway.RestApi(this, 'CounterApi', {
      restApiName: 'blog-post-view-counter',
      deployOptions: {
        throttlingRateLimit: 10,   // Max 10 requests/second sustained
        throttlingBurstLimit: 20,  // Allow short bursts up to 20/second
      },
    });

    const integration = new apigateway.LambdaIntegration(fn);

    // CORS — only allow requests from your blog domain
    const corsOptions: apigateway.CorsOptions = {
      allowOrigins: [blogOrigin],
      allowMethods: ['GET', 'OPTIONS'],
    };

    // GET /counter?page=/some-path — record a page view
    const counter = api.root.addResource('counter');
    counter.addMethod('GET', integration);
    counter.addCorsPreflight(corsOptions);

    // Print the tracking URL after deploy
    new cdk.CfnOutput(this, 'CounterUrl', {
      value: `${api.url}counter`,
      description: 'Tracking endpoint',
    });
  }
}

A few things to notice:

NodejsFunction instead of Function. You're writing TypeScript, but Lambda runs JavaScript. The regular lambda.Function construct would deploy your .ts files as-is, and Lambda wouldn't know what to do with them. NodejsFunction compiles your TypeScript to JavaScript with esbuild at deploy time. You write TypeScript, Lambda gets JavaScript, and you don't need a separate build step.
Provisioned capacity at 25/25. DynamoDB's always-free tier gives you 25 read capacity units and 25 write capacity units at no cost. That's 25 reads and 25 writes per second, which is way more than a personal blog needs. We're using provisioned mode instead of on-demand specifically to stay within this free allocation.
removalPolicy: DESTROY. By default, CDK protects your DynamoDB table from accidental deletion. Since this is a learning project, we set it to DESTROY so cdk destroy cleans everything up. For a production table, you'd leave the default.
Throttling. API Gateway is set to 10 requests per second with bursts up to 20. This caps how much traffic can hit your Lambda and DynamoDB, which limits your bill if someone discovers your endpoint and tries to hammer it.

Now create the CDK entry point at cdk/app.ts:

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { ViewCounterStack } from './stack.js';

const app = new cdk.App();
new ViewCounterStack(app, 'BlogPostViewCounterSampleForAws');

Step 4: Deploy

One command:

npx cdk deploy -c blogOrigin=https://yourdomain.com

Replace yourdomain.com with your actual blog domain. CDK will show you a summary of the resources it's about to create and ask for confirmation. Type y.

After about a minute, you'll see output that looks something like this:

Pay special attention to the Outputs section with the CounterUrl endpoint.

Outputs:
BlogPostViewCounterSampleForAws.CounterUrl = https://abc123.execute-api.us-east-1.amazonaws.com/prod/counter

That's your tracking endpoint. Save that URL.

Step 5: Add it to your blog

Add this script tag to your site's base layout. In Astro, that's your layout component. In Hugo, it's baseof.html. In plain HTML, put it before the closing </body> tag.

<script>
  fetch(`https://YOUR_COUNTER_URL?page=${encodeURIComponent(window.location.pathname)}`);
</script>

Replace YOUR_COUNTER_URL with the URL from the deploy output.

Here's what it looks like in an Astro blog layout, with the real endpoint URL:

<BaseLayout {title} {description} {image} type="article" {pubDate}>
  <script type="application/ld+json" set:html={JSON.stringify(schemaData)} slot="head" />

  <script>
    fetch(`https://u1sdf1bq66.execute-api.us-east-1.amazonaws.com/prod/counter?page=${encodeURIComponent(window.location.pathname)}`);
  </script>

  <a href="/blog" class="back-link">&larr; all posts</a>

  <article>
    <header class="post-header">
      <h1 class="post-header__title">{title}</h1>
      <p class="post-header__meta">
        <time datetime={pubDate.toISOString()}>{formattedDate}</time>
        {formattedUpdated && (
          <span> &middot; updated {formattedUpdated}</span>
        )}
      </p>
    </header>

    <div class="post-body">
      <slot />
    </div>
  </article>
</BaseLayout>

Now every page load fires a request to your API, which counts the view and returns a 204. The window.location.pathname part means it automatically sends the current page's path, so you don't need to configure anything per post.

Step 6: Check your view counts

Open the DynamoDB console, find your table, and click "Explore table items." If you have a lot of items, filter for items where sk equals counter. You'll see each page path and its view count.

You can also run this from the CLI:

aws dynamodb scan \
  --table-name YOUR_TABLE_NAME \
  --filter-expression "sk = :sk" \
  --expression-attribute-values '{":sk": {"S": "counter"}}'

How much does this cost?

This project uses services eligible for the AWS Free Tier. Depending on your usage and account status, charges may apply. Here's the breakdown:

DynamoDB provisioned at 25 WCU/25 RCU is within the always-free tier. No cost regardless of account age.
Lambda gives you 1 million requests per month free. Most personal blogs will stay within these limits.
API Gateway is the only service with a direct cost: $3.50 per million requests for REST APIs in us-east-1. A blog getting 10,000 views per month would cost about $0.035, which comes out of your Free Tier credits if you're a new customer.

I'd recommend setting up a billing alarm at $5 as a best practice in new sandbox accounts.

What you just learned

If you followed along, you now have hands-on experience with:

DynamoDB: composite keys, TTL for automatic cleanup, atomic counters with UpdateExpression
Lambda: handling HTTP events, environment variables, working with the AWS SDK
API Gateway: REST endpoints, CORS configuration, throttling
CDK: defining infrastructure in TypeScript, deploying with a single command

And you have something running on your blog that you built from scratch.

Cleanup

If you want to tear everything down:

npx cdk destroy -c blogOrigin=https://yourdomain.com

This deletes the Lambda, the DynamoDB table, and the API Gateway endpoint. All your view count data will be gone, so make sure you're done with it.

What to try next

Add a billing alarm so you get an email if your AWS charges go above $5
Build a small dashboard that reads from DynamoDB and displays your view counts
Track views over time by adding a date field to the counter records

The source code for this project is on GitHub if you want to fork it and make it your own. Let me know in the comments what you're building this week!

¿Qué es un Modelo de IA? Explicación sencilla

Ramses Mata — Mon, 20 Apr 2026 20:10:32 +0000

La mayoría de nosotros ha utilizado chats de IA en los últimos años en su día a día. Sin importar si eres estudiante o profesional, son herramientas que se han enraizado en nuestras vidas. Pero, ¿sabes exactamente qué hay detrás? ¿Cómo es que funcionan realmente? No es magia, en realidad es pura estadística.

Detrás de cada chat de IA, cada traductor automático y cada asistente de código, hay algo llamado modelo. No necesitas ser ingeniero de Machine Learning para entender qué es, y tampoco vamos a entrar en matemáticas o algoritmos. En este artículo vas a aprender qué es un modelo, cómo interactúas con uno, cómo elegir el correcto y si necesitas crear el tuyo propio.

1. ¿Qué es un modelo?

Un modelo de IA es un programa informático entrenado con grandes cantidades de datos que predice qué es lo más probable que venga después en una secuencia de texto. No "entiende" ni "sabe", calcula probabilidades basándose en patrones.

Imagina que tienes un amigo que es increíblemente bueno para terminar tus frases. Tú dices "hoy me siento..." y él responde "cansado" porque te conoce, sabe el contexto y ha escuchado miles de conversaciones similares. Eso, en esencia, es lo que hace un modelo de IA: un programa entrenado con cantidades masivas de texto que predice qué es lo más probable que venga después.

Por ejemplo, en el contexto "Mi color favorito es...", un modelo debería predecir "rojo" mejor que "auto". No porque "entienda" colores, sino porque en los millones de textos que ha procesado, "rojo" aparece mucho más frecuentemente después de "mi color favorito es" que "auto".

Esto es importante: el modelo no "sabe" cosas ni "entiende" el mundo. Calcula probabilidades. Es muy bueno encontrando patrones en texto, y eso le permite generar respuestas que parecen inteligentes, pero por debajo es estadística.

💡 Tip importante: Antes de procesar texto, los modelos lo descomponen en piezas pequeñas llamadas tokens (que pueden ser palabras, partes de palabras o caracteres). Esto es lo que les permite trabajar con cualquier idioma y tipo de texto.

2. ¿Cómo interactúas con un modelo?

Como desarrollador, tú no entrenas modelos, los usas. Y la interacción es más simple de lo que parece: tú envías un prompt (una instrucción o pregunta en texto) y el modelo te devuelve una respuesta.

Esto sucede a través de APIs. Servicios como Amazon Bedrock, OpenAI API o Google Vertex AI te dan acceso a modelos poderosos sin que tengas que preocuparte por la infraestructura detrás.

Pero también puedes correr un modelo directamente en tu computadora usando herramientas como Ollama. Con un solo comando puedes descargar un modelo y empezar a hablar con él:

ollama run llama3.1

Esto descarga el modelo Llama 3.1 y abre una conversación directa en tu terminal:

Piénsalo así: tú no construyes el motor del auto, tú lo conduces. Los modelos ya están construidos y entrenados, tu trabajo es aprender a usarlos bien.

Y aquí hay un detalle clave: la calidad de la respuesta que recibes depende mucho de cómo escribes tu prompt. Veamos un ejemplo real. Si le pedimos al modelo algo vago como "escribe algo sobre perros", obtenemos una respuesta genérica:

Pero si somos más específicos con "escribe un párrafo de 3 oraciones explicando por qué los perros son buenas mascotas para familias con niños", la respuesta es mucho más útil:

La diferencia es notable. A esta habilidad de escribir buenos prompts se le llama prompt engineering, es una de esas habilidades que suele ser muy infravalorada y muchas veces usada como meme, pero te va a ayudar mucho al desarrollar software y usar modelos de IA.

💡 Tip importante: No necesitas instalar ni configurar un modelo en tu computadora para usarlo. A través de APIs puedes enviar un prompt y recibir una respuesta con unas pocas líneas de código.

3. ¿Cómo elijo un modelo?

Cuando empiezas a investigar sobre modelos, te encuentras con muchos nombres: Claude, GPT, Llama, Nova, Mistral... ¿Cómo sabes cuál usar? En lugar de memorizar una taxonomía de tipos de modelos, lo que realmente importa son las capacidades del modelo.

Si usas Ollama, puedes explorar los modelos disponibles en ollama.com/library. Cada modelo tiene una página con sus capacidades, tamaño y ventana de contexto. Por ejemplo, en la página de Llama 3.1 puedes ver toda esta información de un vistazo:

Estas son las capacidades más relevantes:

Capacidad	Qué hace	Cuándo la necesitas
Generación de texto	Produce texto, código, resúmenes	Siempre (es la base)
Multimodalidad	Procesa imágenes, audio, video	Cuando trabajas con más que texto
Ventana de contexto	Cuánto texto puede "ver" a la vez	Documentos largos, conversaciones extensas
Costo y velocidad	Tradeoff entre capacidad y precio	Aplicaciones con muchas llamadas

Generación de texto

Todos los modelos modernos pueden generar texto, pero no todos lo hacen igual de bien. Algunos son mejores para conversación, otros para código, otros para análisis. Esta es la capacidad base.

Multimodalidad

Algunos modelos pueden procesar no solo texto, sino también imágenes, audio o video. Si necesitas analizar capturas de pantalla, interpretar documentos escaneados o procesar fotos, necesitas un modelo multimodal.

Ventana de contexto

La ventana de contexto es la cantidad de texto que el modelo puede "ver" al mismo tiempo. Piénsalo como su memoria a corto plazo. Un modelo con una ventana de contexto grande puede leer documentos largos, mantener conversaciones extensas o analizar múltiples archivos a la vez.

Puedes encontrar el tamaño de la ventana de contexto en la página de documentación de cada modelo. Como referencia: 128K tokens es suficiente para la mayoría de tareas con texto. Si necesitas trabajar con múltiples documentos largos o conversaciones muy extensas, busca modelos con 200K+ tokens.

Costo y velocidad

Los modelos más capaces suelen ser más lentos y más caros por petición. Si tu aplicación hace muchas llamadas al modelo, esto importa. A veces un modelo más pequeño y rápido es mejor opción que el más poderoso.

💡 Tip importante: No necesitas el modelo más grande o más caro. Elige basándote en lo que necesitas hacer. Una tarea que solo clasifica textos cortos no necesita el mismo modelo que una que analiza documentos de 100 páginas.

4. ¿Necesito crear mi propio modelo?

Respuesta corta: casi seguro que no.

Como desarrollador, tu rol es consumir modelos a través de APIs y servicios, no construirlos desde cero. Entrenar un modelo requiere cantidades enormes de datos, poder computacional y experiencia en Machine Learning.

Proveedores de nube como AWS con Amazon Bedrock te dan acceso a múltiples modelos fundacionales sin que tengas que manejar infraestructura. Tú eliges el modelo, envías tu prompt a través de la API, y recibes tu respuesta.

¿Cuándo necesitarías tu propio modelo? En casos muy específicos donde los modelos existentes no cubren tu necesidad. Por ejemplo, un hospital que necesita un modelo entrenado específicamente con sus registros médicos internos y terminología propia, o una empresa con un lenguaje de dominio tan especializado que los modelos generales no manejan bien. Y aún en esos casos, lo más común es hacer fine-tuning (ajustar un modelo existente o preentrenado con tus datos) en lugar de construir uno desde cero.

Tu trabajo como desarrollador: aprender a usar modelos de manera efectiva, elegir el correcto para cada caso de uso, y construir aplicaciones que los aprovechen.

Preguntas frecuentes

¿Cuál es la diferencia entre un modelo de IA y un LLM?

Un LLM (Large Language Model) es un tipo específico de modelo de IA. Todos los LLMs son modelos de IA, pero no todos los modelos de IA son LLMs. "LLM" se refiere a modelos de lenguaje entrenados con cantidades masivas de datos, como Claude, GPT o Llama.

¿Puedo correr un modelo de IA en mi computadora?

Sí, pero con limitaciones. Herramientas como Ollama te permiten descargar y correr modelos localmente con un solo comando. Modelos como Llama 3.1 funcionan bien en computadoras con 16GB de RAM. Sin embargo, los modelos más capaces requieren hardware muy potente (GPUs especializadas y decenas de gigabytes de memoria) que la mayoría de computadoras personales no tienen. Aquí es donde el cloud computing ayuda: servicios como Amazon Bedrock te dan acceso a los modelos más poderosos a través de una API, sin necesidad de tener el hardware en tu máquina.

¿Qué modelo de IA debería usar para mi proyecto?

Depende de lo que necesites. Para tareas de texto general, cualquier LLM moderno funciona. Si necesitas procesar imágenes o audio, busca un modelo multimodal. Si tu aplicación hace muchas llamadas, prioriza costo y velocidad sobre capacidad máxima.

Conclusión

Recapitulemos lo que aprendimos:

Un modelo de IA es un programa que predice qué viene después basándose en patrones que aprendió de datos. No "entiende" ni "sabe", calcula probabilidades
Interactúas con modelos enviando prompts y recibiendo respuestas a través de APIs
Al elegir un modelo, lo que importa son las capacidades: generación de texto, multimodalidad, ventana de contexto, costo y velocidad
No necesitas crear tu propio modelo. Servicios en la nube te dan acceso a modelos poderosos listos para usar

Algo que no cubrimos en este artículo pero vale la pena mencionar: algunos modelos también soportan uso de herramientas (tool use), lo que significa que pueden describir cuándo necesitan llamar a una función externa y con qué parámetros. Esta capacidad es lo que hace posible construir agentes de IA, y es exactamente lo que exploraremos en el próximo artículo.

Building Serverless APIs with TDD and AI-Powered Spec Generation

Salih Guler — Thu, 16 Apr 2026 14:44:03 +0000

Test-Driven Development has been around for decades, but most teams still struggle to adopt it consistently. The biggest friction point? Writing specs and tests takes time, especially when you're dealing with the ambiguity of greenfield projects. You're not always sure what the requirements should be, what edge cases to cover, or how to structure your tests before you write the code.

This gets more complicated with serverless architectures. You're juggling Lambda functions, API Gateway configurations, database tables, and event-driven workflows. Traditional TDD assumes you're working in a monolithic environment where you can stub out dependencies easily. In serverless, your "dependencies" are managed AWS services with their own quirks, quotas, and failure modes.

What if you could use AI to generate comprehensive specifications from high-level requirements, then use those specs to drive your test creation and implementation? This is how spec-driven development with AI assistants changes how TDD works in practice.

The Problem with Traditional TDD in Serverless

Classic TDD follows a simple loop: write a failing test, write code to pass the test, refactor. This works when you know exactly what you're building. But in real projects, requirements are often vague: "Build an API that handles user registrations" doesn't tell you what fields are required, what validation rules apply, what error responses look like, or how you'll handle concurrent registrations.

You end up spending hours in planning meetings, writing detailed specification documents, or (more commonly) skipping specs entirely and letting the code become the specification. All three approaches have problems:

Planning meetings slow down development and documentation gradually becomes obsolete
Skipping specs means inconsistent implementations and missing edge cases
Code-as-specification makes onboarding painful and refactoring risky

Serverless adds another layer of complexity. You need to test that your Lambda function works, that API Gateway routes requests correctly, that DynamoDB handles your access patterns, that IAM permissions are configured properly, and that everything scales under load. Unit tests with mocks only get you so far. You need integration tests in the cloud to catch configuration issues, but those are slow and expensive to run constantly.

Spec-Driven Development: The Missing Layer

Spec-driven development sits between requirements and tests. You start with a formal specification that describes exactly what your system should do, including success cases, error conditions, data formats, and constraints. This spec becomes the contract that your code must fulfill.

The difference from traditional documentation is that specs are executable. You can generate tests from specs, validate implementations against specs, and use specs to generate API documentation or client SDKs automatically. OpenAPI is the most common example, but specs can be more detailed and include business logic constraints that OpenAPI doesn't capture.

Here's where AI comes in. Instead of manually writing specifications, you can use AI to generate comprehensive specs from natural language requirements. An AI assistant trained on API design patterns, AWS best practices, and your existing codebase can produce detailed specs that cover edge cases you might not think of.

Building a User Registration API with Specs

We'll create a Lambda-backed API for user registration.

Step 1: Generate the Specification with AI

Use an AI assistant (we will be using Kiro) to generate a formal specification from these requirements. Here's a prompt that works:

Given the following requirements for a serverless API endpoint, generate a comprehensive specification that includes:

1. OpenAPI schema with all request/response formats
2. Validation rules with specific regex patterns and constraints
3. Error scenarios with HTTP status codes and error formats
4. Concurrency handling strategy
5. Security considerations
6. DynamoDB table design for the data model

Requirements: Build a user registration endpoint that:
- Accepts email, password, and optional full name
- Validates email format and password strength
- Prevents duplicate registrations
- Returns a user ID on success
- Handles concurrent requests safely
- Logs failed attempts for security monitoring

Format the output as a structured JSON specification that can drive test generation.

This spec captures things you might not have specified in the original requirements: password regex pattern, exact error messages, the concurrency strategy using DynamoDB conditional writes, and a field for tracking registration attempts (useful for rate limiting).

# User Registration API Specification

## OpenAPI Schema

openapi: 3.0.3
info:
  title: User Registration API
  version: 1.0.0
paths:
  /register:
    post:
      operationId: registerUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Email already registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RegisterRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
        fullName:
          type: string
    RegisterResponse:
      type: object
      required: [userId, email, createdAt]
      properties:
        userId:
          type: string
          format: uuid
        email:
          type: string
        createdAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
        message:
          type: string
        fields:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              reason:
                type: string

## Validation Rules

### Email

| Rule ID | Constraint | Details |
|---------|-----------|---------|
| EMAIL_FORMAT | Regex pattern | `^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$` |
| EMAIL_LENGTH | Max length | 254 characters |
| — | Transform | Lowercase before storage and uniqueness check |

### Password

| Rule ID | Constraint | Details |
|---------|-----------|---------|
| PWD_MIN_LENGTH | Min length | 8 characters |
| PWD_MAX_LENGTH | Max length | 128 characters |
| PWD_UPPERCASE | Pattern | At least one uppercase letter |
| PWD_LOWERCASE | Pattern | At least one lowercase letter |
| PWD_DIGIT | Pattern | At least one digit |
| PWD_SPECIAL | Pattern | At least one special character |

Full pattern: `^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=\[\]{}|;:',.<>?/` `` `~])[A-Za-z\d!@#$%^&*()_+\-=\[\]{}|;:',.<>?/` `` `~]{8,128}$`

### Full Name (optional)

| Rule ID | Constraint | Details |
|---------|-----------|---------|
| NAME_FORMAT | Regex pattern | `^[\p{L}\s'.\-]{1,100}$` |
| NAME_LENGTH | Max length | 100 characters |

## Error Scenarios

| ID | HTTP Status | Code | Message | Trigger |
|----|------------|------|---------|---------|
| MISSING_EMAIL | 400 | VALIDATION_ERROR | Email is required | Missing email field |
| INVALID_EMAIL | 400 | VALIDATION_ERROR | Invalid email format | Email fails pattern |
| MISSING_PASSWORD | 400 | VALIDATION_ERROR | Password is required | Missing password field |
| WEAK_PASSWORD | 400 | VALIDATION_ERROR | Password does not meet strength requirements | Password fails strength rules |
| INVALID_NAME | 400 | VALIDATION_ERROR | Full name contains invalid characters | fullName fails pattern |
| INVALID_JSON | 400 | INVALID_REQUEST | Request body must be valid JSON | Malformed or non-JSON body |
| DUPLICATE_EMAIL | 409 | CONFLICT | An account with this email already exists | ConditionalCheckFailedException from DynamoDB |
| INTERNAL_ERROR | 500 | INTERNAL_ERROR | An unexpected error occurred | Unhandled exception or DynamoDB service error |

## Concurrency Handling

**Strategy:** DynamoDB conditional writes

- **Operation:** `PutItem` with `ConditionExpression: attribute_not_exists(pk)`
- **Partition key:** `USER#<normalized_email>` — the email itself is the uniqueness key
- **Behavior:** If two concurrent requests register the same email, exactly one succeeds (201) and the other receives a 409 (`ConditionalCheckFailedException`)
- **Retry policy:** No retry on `ConditionalCheckFailedException`; map directly to 409
- **Idempotency:** Not idempotent by design — repeated calls with the same email return 409 after first success

## Security Considerations

### Password Handling

- **Algorithm:** bcrypt, cost factor 12
- **Storage:** Store only the bcrypt hash, never plaintext
- **Input sanitization:** Reject null bytes in password input

### Rate Limiting

| Scope | Limit | Implementation |
|-------|-------|---------------|
| Per source IP | 10 requests/minute | API Gateway throttling |
| Global | 1000 requests/minute | API Gateway throttling |

### Failed Attempt Logging

| Event | Logged Data | Destination |
|-------|------------|-------------|
| DUPLICATE_EMAIL | Hashed email, source IP | CloudWatch Logs (structured JSON) |
| VALIDATION_ERROR | Error type, source IP | CloudWatch Logs (structured JSON) |
| INTERNAL_ERROR | Full error, correlation ID | CloudWatch Logs (structured JSON) |

- **Retention:** 90 days
- **Alerting:** CloudWatch alarm on >50 failed registrations per 5 minutes from same IP

### Transport & Headers

- HTTPS only (enforced at API Gateway)
- Max request body size: 10KB
- Response headers:
  - `Strict-Transport-Security: max-age=31536000; includeSubDomains`
  - `Content-Type: application/json`
  - `X-Content-Type-Options: nosniff`

## DynamoDB Table Design

**Table name:** `Users`
**Capacity mode:** PAY_PER_REQUEST
**Point-in-time recovery:** Enabled
**Encryption:** AWS_OWNED_KMS

### Key Schema

| Attribute | Type | Key | Format | Description |
|-----------|------|-----|--------|-------------|
| pk | S | HASH | `USER#<normalized_email>` | Partition key for uniqueness enforcement |

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| pk | S | `USER#user@example.com` |
| userId | S | UUIDv4 |
| email | S | Original email (lowercased) |
| passwordHash | S | bcrypt hash |
| fullName | S | Optional, omitted if not provided |
| createdAt | S | ISO 8601 timestamp |
| updatedAt | S | ISO 8601 timestamp |

### Global Secondary Index

| Index Name | Partition Key | Projection | Purpose |
|-----------|--------------|------------|---------|
| userId-index | userId (S) | ALL | Lookup user by UUID for downstream APIs |

## Test Matrix

### Happy Path

- Valid email + strong password → 201 with userId
- Valid email + strong password + fullName → 201 with userId
- Email with subaddressing (`user+tag@example.com`) → 201

### Validation Errors

- Missing email → 400 VALIDATION_ERROR
- Missing password → 400 VALIDATION_ERROR
- Invalid email format → 400 VALIDATION_ERROR
- Password too short → 400 VALIDATION_ERROR
- Password missing uppercase → 400 VALIDATION_ERROR
- Password missing lowercase → 400 VALIDATION_ERROR
- Password missing digit → 400 VALIDATION_ERROR
- Password missing special char → 400 VALIDATION_ERROR
- fullName with invalid chars → 400 VALIDATION_ERROR
- Empty request body → 400 INVALID_REQUEST
- Non-JSON body → 400 INVALID_REQUEST

### Duplicate Handling

- Register same email twice → first 201, second 409
- Register same email different case → 409 (normalization)

### Concurrency

- Two simultaneous registrations same email → exactly one 201, one 409
- Two simultaneous registrations different emails → both 201

### Security

- Password not returned in response body
- Password stored as bcrypt hash in DynamoDB
- Oversized request body → rejected
- Null bytes in password → rejected

This will create a logical structure like the following:

Step 2: Generate Tests from the Specification

Now use the spec to generate comprehensive tests. You can write Generate tests from the specs. Once they are generated run the tests, you should see tests are failing and indicating why are they failing as well:

Test Suites: 5 failed, 5 total
Tests:       21 failed, 1 passed, 22 total
Snapshots:   0 total
Time:        1.541 s, estimated 2 s
Ran all test suites.
 - Completed in 2.530s

> As expected — 21 of 22 tests fail with 501 (the stub's "Not implemented" 
response). The one passing test is "password not returned in response body" 
which trivially passes since the stub doesn't return any user data.

Summary:

| Suite | Tests | Failing |
|---|---|---|
| Happy Path | 3 | 3 |
| Validation Errors | 11 | 11 |
| Duplicate Handling | 2 | 2 |
| Concurrency | 2 | 2 |
| Security | 4 | 3 |
| Total | 22 | 21 |

Ready for the red → green cycle. Want me to start implementing the handler to make these pass?

These tests are comprehensive. They cover the happy path, all error scenarios from the spec, and even a concurrency test that sends two simultaneous requests.

Step 3: Implement to Pass the Tests

Now write the Lambda function to make these tests pass. It depends on you to either write them or allow AI to write it for you. Let's ask AI to write it:

> Implement everything needed to cover the specs.
... a few moments after implementation 

> All 22 tests green. Here's what was implemented:

- src/repository.ts — UserRepository interface with putUserIfNotExists contract, plus a setter/getter for dependency injection

- src/handler.ts — full handler with JSON parsing, body size check, email/password/name validation, bcrypt hashing, email normalization, and conditional put for duplicate prevention

- tests/helpers.ts — updated with an InMemoryUserRepository that mimics DynamoDB's conditional write behavior, beforeEach reset for test isolation, and getDynamoDBMock() for the bcrypt storage assertion

The real DynamoDB implementation can be swapped in later by calling setRepository() with a DynamoDB-backed class that uses attribute_not_exists(pk) on PutItem.

The implementation follows the spec exactly. The validation logic uses the regex patterns from the spec. Error responses match the error formats from the spec. e.g. you can see below, the concurrency handling uses DynamoDB conditional writes as specified:

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
import type { UserRecord, UserRepository } from './repository';

export class DynamoDBUserRepository implements UserRepository {
  private readonly client: DynamoDBDocumentClient;
  private readonly tableName: string;

  constructor(tableName: string) {
    this.tableName = tableName;
    this.client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
  }

  async putUserIfNotExists(user: UserRecord): Promise<boolean> {
    try {
      await this.client.send(
        new PutCommand({
          TableName: this.tableName,
          Item: user,
          ConditionExpression: 'attribute_not_exists(pk)',
        })
      );
      return true;
    } catch (err: unknown) {
      if (
        err instanceof Error &&
        err.name === 'ConditionalCheckFailedException'
      ) {
        return false;
      }
      throw err;
    }
  }
}

Deploy and Test in the Cloud

To deploy and test in the cloud, we will be asking to deploy the app with CDK. It will create the project and allows us to deploy to the cloud through CDK's CLI tools. Ask it to deploy the code and run tests on cloud.

> Everything is deployed and tested. Here's the summary:

Stack deployed: ServerlessTddStack in us-east-1
- API Gateway: 
https://62lf8w8qnk.execute-api.us-east-1.amazonaws.com/prod/register
- Lambda: Node 20, 256MB, esbuild-bundled
- DynamoDB: Users table with pk (HASH) + userId-index GSI, PAY_PER_REQUEST, 
PITR enabled

Test results:
- 22 unit tests ✅ (in-memory mock)
- 5 integration tests ✅ (live API)

Files added:
- src/dynamodb-repository.ts — real DynamoDB repo with conditional writes
- src/lambda.ts — Lambda entry point wiring the DynamoDB repo
- infra/stack.ts — CDK stack definition
- infra/app.ts — CDK app entry
- cdk.json — CDK config
- tests/integration.test.ts — live API tests
- jest.integration.config.js — integration test config

Commands:
- npm test — run unit tests
- 
API_ENDPOINT=https://62lf8w8qnk.execute-api.us-east-1.amazonaws.com/prod/register npm run test:integration
— run integration tests
- npm run destroy — tear down the stack

Testing in the cloud catches issues that local tests miss: IAM permission problems, DynamoDB throughput limits, API Gateway timeout configurations, and cold start behavior.

Handling Spec Evolution

Specs aren't static. Requirements change. When they do, regenerate the spec with AI, diff it against the current version, and update tests accordingly.

Update spec to give user an option to add a profile picture URL.

When you run the diff, you get a clear picture of what changed.

> Now I'll update the spec with the profile picture URL field across all 
relevant sections.
I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  57, 57:         fullName:
  58, 58:           type: string
+     59:         profilePictureUrl:
+     60:           type: string
+     61:           format: uri
  59, 62:     RegisterResponse:

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  116, 116: ### Full Name (optional)
  117, 117: 
  118, 118: | Rule ID | Constraint | Details |
  119, 119: |---------|-----------|---------|
  120, 120: | NAME_FORMAT | Regex pattern | `^[\p{L}\s'.\-]{1,100}$` |
  121, 121: | NAME_LENGTH | Max length | 100 characters |
+      122: 
+      123: ### Profile Picture URL (optional)
+      124: 
+      125: | Rule ID | Constraint | Details |
+      126: |---------|-----------|---------|
+      127: | PIC_URL_FORMAT | Regex pattern | `^https://[^\s]{1,2048}$` |
+      128: | PIC_URL_LENGTH | Max length | 2048 characters |
+      129: | PIC_URL_SCHEME | Scheme | Must be HTTPS only |

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  139, 139: | INVALID_NAME | 400 | VALIDATION_ERROR | Full name contains invalid characters | fullName fails pattern |
- 140     : | INVALID_JSON | 400 | INVALID_REQUEST | Request body must be valid JSON | Malformed or non-JSON body |
+      140: | INVALID_PROFILE_PIC_URL | 400 | VALIDATION_ERROR | Profile picture URL must be a valid HTTPS URL | profilePictureUrl fails pattern |
+      141: | INVALID_JSON | 400 | INVALID_REQUEST | Request body must be valid JSON | Malformed or non-JSON body |

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  211, 211: | fullName | S | Optional, omitted if not provided |
+      212: | profilePictureUrl | S | Optional, omitted if not provided |
  212, 213: | createdAt | S | ISO 8601 timestamp |

Updating: docs/user-registration-spec.md
 - Completed in 0.2s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  227, 227: - Valid email + strong password + fullName → 201 with userId
+      228: - Valid email + strong password + profilePictureUrl → 201 with userId
  228, 229: - Email with subaddressing (`user+tag@example.com`) → 201

Updating: docs/user-registration-spec.md
 - Completed in 0.1s

I'll modify the following file: docs/user-registration-spec.md (using tool: write)

  241, 241: - fullName with invalid chars → 400 VALIDATION_ERROR
+      242: - profilePictureUrl with HTTP scheme → 400 VALIDATION_ERROR
+      243: - profilePictureUrl with invalid format → 400 VALIDATION_ERROR
  242, 244: - Empty request body → 400 INVALID_REQUEST

Updating: docs/user-registration-spec.md

According to your changes, you can add new test cases for added scenarios, remove obsolete tests, and update tests for changed behavior. This keeps your test suite and implementation synchronized with requirements.

Tradeoffs and When to Use a Different Approach

This mixture of AI and spec-driven approach works well for APIs with complex validation, multiple error conditions, and strict contracts (like public APIs or microservices with many consumers). It's less useful for experimental features where requirements are genuinely unknown.

If you're building a prototype to test a hypothesis, traditional TDD with minimal specs is faster. Write a few high-level tests, implement quickly, and iterate. Once the concept proves valuable, then formalize it with specs.

For workflows with complex business logic but simple I/O contracts, consider property-based testing instead. Tools like fast-check generate random inputs to find edge cases your specs might miss. Combine property tests with spec-driven tests for comprehensive coverage.

For systems with heavy external dependencies (third-party APIs, legacy services), mocks are unavoidable. But keep mocked tests separate from integration tests. Run mocked tests frequently during development for fast feedback. Run cloud integration tests before merging to catch configuration drift.

Making This Practical

To adopt spec-driven development in your team:

Start with one API or service, not the whole system
Use AI to generate initial specs, then review and refine them
Store specs in version control alongside code
Generate tests from specs, but also write additional tests for edge cases you discover
Make spec generation part of your development workflow, not a one-time task
Review spec diffs in pull requests just like code diffs

The goal is to make specifications a living part of your codebase, not documentation that falls out of date.

Cleaning Up Resources

When you're done experimenting, delete the CloudFormation stack:


cdk destroy

This removes the API Gateway, Lambda function, and DynamoDB table. Check the AWS Console to confirm no orphaned resources remain.

Hide regions and services in the AWS console

Sean Boult — Wed, 15 Apr 2026 21:26:43 +0000

Tired of scrolling through regions and services you'll never use?

You just want to...

AWS now lets you hide regions and services from your console. Here's how.

Heads up: This is a visual preference, not a security control. Users can still access hidden regions and services directly.

Hide Regions

That region dropdown doesn't need to show every region AWS offers.

Go to Unified Settings → Account settings.
Find Visible Regions.
Deselect the regions you don't use. Keep the ones where you actually run workloads.
Save.

Done. Your region dropdown now only shows what matters.

Hide Services

Same place, different setting.

Go to Unified Settings → Account settings.
Find Visible Services.
Deselect the services you don't need. I'd recommend keeping Billing so you can still manage costs.
Save.

What Happens When You Access Something Hidden?

You'll see a page like this if you navigate to a hidden region/service directly:

And some parts of the console will show a restricted indicator:

Again, nothing is actually blocked. It's just hidden from the default navigation.

Resources

Cómo crear un agente de IA desde cero. Open source, local y gratis.

Hazel Saenz — Wed, 15 Apr 2026 16:15:25 +0000

De un modelo que solo responde a uno que busca, razona y recuerda con código que puedes leer, forkear y contribuir.

Todos hemos usado ChatGPT, Claude, Google Gemini. Les preguntas algo, te responden. Les pides que resuman un texto, lo resumen. Les dices que escriban un correo, lo escriben. Pero hay un límite. Un modelo de lenguaje puede hablar de música. Puede hablar de géneros. Puede hablar de artistas.

Pero no puede buscar en tu biblioteca de canciones.
No puede analizar el mood de una playlist.
No puede recordar que la semana pasada te armó una playlist de hip-hop para el gym y te encantó.

Un modelo solo habla.
Un agente hace cosas.

Y esa diferencia es más importante de lo que parece.

¿Qué es un agente de IA?

Si ya usaste la API de OpenAI o jugaste con modelos en Hugging Face, sabes que un LLM recibe texto y genera texto. Punto. No ejecuta código, no consulta bases de datos, no llama APIs.

Un agente agrega dos cosas encima de eso:

Herramientas (tools): funciones que el modelo puede invocar cualquier función de Python que le expongas
Un agent loop: un ciclo donde el modelo razona, decide si necesita llamar una herramienta, la ejecuta, recibe el resultado, y vuelve a razonar hasta tener una respuesta final

No es magia. Es un while loop con tool dispatch.

Imagina que le preguntas a un agente DJ: "Armame una playlist para una cena tranquila con amigos."

Sin tools, el modelo genera texto basado en su entrenamiento, no conoce tu biblioteca, no sabe qué se lanzó la semana pasada (su conocimiento tiene fecha de corte), y no tiene idea de tus gustos. Con tools, hace esto:

Razona: "Necesito buscar canciones con energía baja"
Invoca: buscar_canciones(mood="chill", genero="jazz")
Recibe el resultado: una lista de canciones reales de tu biblioteca
Razona de nuevo: "Debería verificar que la energía sea consistente"
Invoca: analizar_energia(canciones=[...])
Genera la respuesta final: una playlist curada con datos reales

El modelo decide qué herramientas invocar y en qué orden. Tú no escribes la orquestación, el modelo la resuelve en runtime. Eso es el enfoque model-driven, y es lo que diferencia a un agente de un pipeline hardcodeado con if/else.

Por qué open source importa (de verdad)

Cuando hablamos de agentes de IA, hay muchas opciones. Frameworks propietarios, APIs cerradas, SDKs que solo funcionan con un proveedor específico.

El problema no es que existan. El problema es lo que pierdes cuando los usas:

No puedes leer la implementación del agent loop, si el modelo toma una secuencia de tool calls inesperada, no puedes entender por qué ni cambiar el comportamiento
No puedes modificar el comportamiento del loop cuando algo no funciona como esperas
Si tu proveedor de modelo no está soportado, no puedes contribuir la integración tú mismo ni aprovechar una que la comunidad ya haya creado
No puedes contribuir fixes o mejoras que beneficien a otros

Open source no es solo "código gratis". Sí, requiere más responsabilidad de tu parte: tú debuggeas, tú actualizas, tú decides. Pero esa responsabilidad viene con control total. Es transparencia. Es poder abrir el source del agent loop y ver que es un while loop con tool dispatch. Es poder poner un breakpoint en el ciclo de razonamiento cuando tu agente hace algo inesperado.

Y eso es exactamente lo que vamos a usar.

El stack: Python + Strands Agents + Ollama

Todo lo que vas a ver en este artículo corre con tres cosas:

Python: el lenguaje (licencia PSF, open source)
Strands Agents: un SDK open source (licencia Apache 2.0) para construir agentes de IA
Ollama: un runtime open source (licencia MIT) para correr modelos de lenguaje localmente

Todo open source. Todo en tu laptop. Sin API keys. Sin vendor lock-in. Sin datos saliendo de tu máquina.

Strands Agents toma un enfoque model-driven: tú defines las herramientas como funciones de Python, escribes un system prompt, y el agent loop se encarga de la ejecución. Sin definiciones de pasos, sin grafos de workflow. Solo código.

Ollama: modelos de IA en tu laptop

Antes de construir el agente, necesitamos un modelo de lenguaje corriendo localmente. Y aquí es donde entra Ollama.

Ollama es un runtime open source para correr LLMs en tu máquina. Si conoces Docker, la analogía es directa: ollama pull descarga un modelo, ollama serve lo expone como API REST en localhost:11434. Sin cuentas, sin API keys, sin datos saliendo de tu red.

Instalación

En macOS y Linux:

curl -fsSL https://ollama.com/install.sh | sh

En Windows, descarga el instalador desde ollama.com/download.

Descargar y correr un modelo

Para este artículo vamos a usar llama3.1:8b — tiene buen soporte para tool-calling (que es lo que necesitamos para que el agente invoque funciones) y maneja español razonablemente bien:

ollama pull llama3.1

Son unos 4.9 GB. Solo necesitas hacerlo una vez.

Ahora levanta el servidor:

ollama serve

Nota: Si instalaste la app de macOS, el servidor ya está corriendo en segundo plano y no necesitas ejecutar ollama serve. Solo es necesario si instalaste con Homebrew o en Linux.

Ollama queda escuchando en http://localhost:11434. Puedes verificar con un curl http://localhost:11434/api/tags para ver los modelos disponibles.

Ollama soporta muchos modelos: Llama, Mistral, Phi, Gemma, y más. Si tu máquina tiene GPU, los corre acelerados automáticamente. Si no, usa CPU (más lento, pero funciona).

Lo importante: el modelo corre en tu máquina. Tus datos no salen de tu laptop. Y el código de Ollama es open source.

Capa 1: Un agente que solo habla

Empecemos por lo más simple. Un agente que es solo un modelo + un prompt.

Primero, instala el SDK de Strands con soporte para Ollama.

Nota: Strands Agents requiere Python 3.10 o superior. El Python que viene preinstalado en macOS (3.9.6) no es compatible. Si no tienes una versión reciente, instálala con brew install python@3.13.

Crea un entorno virtual para no contaminar tu sistema. Con pip:

python3 -m venv .venv
source .venv/bin/activate
pip install 'strands-agents[ollama]'

O si usas uv (más rápido y gestiona Python por ti):

uv venv --python 3.13
source .venv/bin/activate
uv pip install 'strands-agents[ollama]'

Ahora, el código:

from strands import Agent
from strands.models.ollama import OllamaModel

modelo = OllamaModel(
    model_id="llama3.1",
    host="http://localhost:11434",
)

dj = Agent(
    model=modelo,
    system_prompt="""Eres un DJ y curador musical experto.
    Respondes en español, con onda y buen gusto.
    Recomiendas música basándote en el mood, la ocasión, y los gustos del usuario."""
)

dj("Recomiéndame algo para escuchar mientras programo")

Cinco líneas relevantes. Eso es un agente.

Bueno, técnicamente es un modelo con un prompt — todavía no tiene herramientas, así que solo responde con su conocimiento general. Si le pides una playlist con canciones de tu biblioteca, va a alucinar títulos que suenan razonables pero no existen.

Un agente es un modelo + un prompt + un loop. Eso es todo.

Y fíjate: el modelo corre local. No hay API key, no hay vendor, no hay datos saliendo de tu laptop.

Capa 2: Dale herramientas — la biblioteca de canciones

El agente básico no conoce tu música. Sabe de artistas y géneros en general porque fue entrenado con texto de internet. Pero no sabe que en tu biblioteca tienes ese álbum de la Ley que siempre pones cuando cocinas.

Para eso necesita una herramienta.

Pero primero, necesitamos datos. Crea un archivo data/canciones.json con tu biblioteca de canciones. Cada canción necesita: titulo, artista, genero, mood, energia (0-100), y duracion_min. Aquí tienes un ejemplo para arrancar:

Ver ejemplo de data/canciones.json (30 canciones)

[
  {"titulo": "So What", "artista": "Miles Davis", "genero": "jazz", "mood": "chill", "energia": 30, "duracion_min": 9.3},
  {"titulo": "Take Five", "artista": "Dave Brubeck", "genero": "jazz", "mood": "chill", "energia": 35, "duracion_min": 5.4},
  {"titulo": "Blue in Green", "artista": "Miles Davis", "genero": "jazz", "mood": "melancólico", "energia": 20, "duracion_min": 5.4},
  {"titulo": "Fly Me to the Moon", "artista": "Frank Sinatra", "genero": "jazz", "mood": "chill", "energia": 40, "duracion_min": 3.5},
  {"titulo": "Feeling Good", "artista": "Nina Simone", "genero": "jazz", "mood": "energético", "energia": 55, "duracion_min": 2.9},
  {"titulo": "Bohemian Rhapsody", "artista": "Queen", "genero": "rock", "mood": "energético", "energia": 80, "duracion_min": 5.9},
  {"titulo": "Hotel California", "artista": "Eagles", "genero": "rock", "mood": "chill", "energia": 45, "duracion_min": 6.5},
  {"titulo": "Smells Like Teen Spirit", "artista": "Nirvana", "genero": "rock", "mood": "energético", "energia": 90, "duracion_min": 5.0},
  {"titulo": "Under Pressure", "artista": "Queen &amp; David Bowie", "genero": "rock", "mood": "energético", "energia": 75, "duracion_min": 4.0},
  {"titulo": "Creep", "artista": "Radiohead", "genero": "rock", "mood": "melancólico", "energia": 50, "duracion_min": 3.9},
  {"titulo": "Gasolina", "artista": "Daddy Yankee", "genero": "reggaetón", "mood": "fiesta", "energia": 95, "duracion_min": 3.1},
  {"titulo": "Dákiti", "artista": "Bad Bunny &amp; Jhay Cortez", "genero": "reggaetón", "mood": "fiesta", "energia": 80, "duracion_min": 3.3},
  {"titulo": "Tití Me Preguntó", "artista": "Bad Bunny", "genero": "reggaetón", "mood": "fiesta", "energia": 85, "duracion_min": 4.0},
  {"titulo": "Pepas", "artista": "Farruko", "genero": "reggaetón", "mood": "fiesta", "energia": 92, "duracion_min": 4.5},
  {"titulo": "La Bicicleta", "artista": "Shakira &amp; Carlos Vives", "genero": "reggaetón", "mood": "fiesta", "energia": 78, "duracion_min": 3.8},
  {"titulo": "Midnight City", "artista": "M83", "genero": "electrónica", "mood": "energético", "energia": 75, "duracion_min": 4.0},
  {"titulo": "Strobe", "artista": "Deadmau5", "genero": "electrónica", "mood": "chill", "energia": 55, "duracion_min": 10.3},
  {"titulo": "Around the World", "artista": "Daft Punk", "genero": "electrónica", "mood": "fiesta", "energia": 82, "duracion_min": 7.1},
  {"titulo": "Intro", "artista": "The xx", "genero": "electrónica", "mood": "chill", "energia": 25, "duracion_min": 2.1},
  {"titulo": "Teardrop", "artista": "Massive Attack", "genero": "electrónica", "mood": "melancólico", "energia": 35, "duracion_min": 5.3},
  {"titulo": "Disorder", "artista": "Joy Division", "genero": "indie", "mood": "melancólico", "energia": 60, "duracion_min": 3.6},
  {"titulo": "Do I Wanna Know?", "artista": "Arctic Monkeys", "genero": "indie", "mood": "chill", "energia": 55, "duracion_min": 4.6},
  {"titulo": "Somebody Else", "artista": "The 1975", "genero": "indie", "mood": "melancólico", "energia": 45, "duracion_min": 5.7},
  {"titulo": "Electric Feel", "artista": "MGMT", "genero": "indie", "mood": "energético", "energia": 72, "duracion_min": 3.8},
  {"titulo": "Tongue", "artista": "MNEK", "genero": "indie", "mood": "energético", "energia": 68, "duracion_min": 3.5},
  {"titulo": "Only Shallow", "artista": "My Bloody Valentine", "genero": "shoegaze", "mood": "energético", "energia": 70, "duracion_min": 4.2},
  {"titulo": "When You Sleep", "artista": "My Bloody Valentine", "genero": "shoegaze", "mood": "chill", "energia": 45, "duracion_min": 4.1},
  {"titulo": "Alison", "artista": "Slowdive", "genero": "shoegaze", "mood": "melancólico", "energia": 40, "duracion_min": 5.1},
  {"titulo": "Cherry-coloured Funk", "artista": "Cocteau Twins", "genero": "shoegaze", "mood": "chill", "energia": 38, "duracion_min": 4.5},
  {"titulo": "Vapour Trail", "artista": "Ride", "genero": "shoegaze", "mood": "energético", "energia": 65, "duracion_min": 4.2}
]

Puedes modificar este archivo con tu propia música. Lo importante es que mantenga la misma estructura.

Ahora sí, en Strands, crear una herramienta es decorar una función de Python:

from strands import Agent, tool
from strands.models.ollama import OllamaModel
import json

# Cargar biblioteca local de canciones
with open("data/canciones.json") as f:
    BIBLIOTECA = json.load(f)

@tool
def buscar_canciones(genero: str = "", mood: str = "", artista: str = "") -> str:
    """Busca canciones en la biblioteca musical del usuario.

    Args:
        genero: Género musical (ej: rock, jazz, reggaetón, electrónica)
        mood: Estado de ánimo o energía (ej: chill, fiesta, melancólico, energético)
        artista: Nombre del artista o banda
    """
    resultados = BIBLIOTECA
    if genero:
        resultados = [c for c in resultados if genero.lower() in c["genero"].lower()]
    if mood:
        resultados = [c for c in resultados if mood.lower() in c["mood"].lower()]
    if artista:
        resultados = [c for c in resultados if artista.lower() in c["artista"].lower()]

    if not resultados:
        return "No encontré canciones con esos criterios en tu biblioteca."

    return json.dumps(resultados[:10], ensure_ascii=False, indent=2)

Fíjate en el decorador @tool. Convierte cualquier función de Python en una herramienta que el agente puede invocar. El docstring no es decorativo — el SDK lo parsea para generar un tool spec (JSON schema) que es lo que el modelo recibe para decidir cuándo y cómo usar la herramienta. Si el docstring es vago, el modelo no va a saber cuándo llamarla.

Ahora conectamos la herramienta al agente:

modelo = OllamaModel(model_id="llama3.1", host="http://localhost:11434")

dj = Agent(
    model=modelo,
    system_prompt="""Eres un DJ y curador musical experto.
    Usa la herramienta buscar_canciones para encontrar música en la biblioteca del usuario.
    Siempre basa tus recomendaciones en canciones que el usuario realmente tiene.""",
    tools=[buscar_canciones]
)

dj("Quiero escuchar jazz mientras trabajo")

Ahora cuando le pides jazz para trabajar, el agente no inventa. Llama a buscar_canciones(genero="jazz", mood="chill"), obtiene canciones reales de tu biblioteca, y arma una recomendación con lo que realmente tienes.

Pasó de "saber cosas" a "hacer cosas".

Y el sistema de tools es extensible. Existe un paquete de community tools donde cualquiera puede publicar los suyos. ¿Tienes una API que quieres conectar? Escribe un @tool y compártelo.

Capa 3: Más herramientas, más inteligencia

Un tool está bien. Pero la cosa se pone interesante cuando agregas varios.

@tool
def analizar_energia(canciones: list) -> str:
    """Analiza el nivel de energía promedio de una lista de canciones y sugiere el orden ideal.

    Args:
        canciones: Lista de nombres de canciones a analizar
    """
    energia_map = {}
    for cancion in BIBLIOTECA:
        energia_map[cancion["titulo"].lower()] = cancion.get("energia", 50)

    analisis = []
    for titulo in canciones:
        energia = energia_map.get(titulo.lower(), 50)
        analisis.append({"titulo": titulo, "energia": energia})

    # Ordenar por energía para un flow natural
    analisis.sort(key=lambda x: x["energia"])
    promedio = sum(c["energia"] for c in analisis) / len(analisis) if analisis else 0

    return json.dumps({
        "energia_promedio": round(promedio),
        "flow": "ascendente" if analisis[0]["energia"] < analisis[-1]["energia"] else "descendente",
        "orden_sugerido": [c["titulo"] for c in analisis],
        "nota": "Energía baja → alta para ir subiendo el mood" if promedio < 60 else "Playlist con buena energía"
    }, ensure_ascii=False)

@tool
def duracion_playlist(canciones: list) -> str:
    """Calcula la duración total de una playlist y sugiere si necesita más canciones.

    Args:
        canciones: Lista de nombres de canciones
    """
    duracion_map = {}
    for cancion in BIBLIOTECA:
        duracion_map[cancion["titulo"].lower()] = cancion.get("duracion_min", 3.5)

    total = sum(duracion_map.get(t.lower(), 3.5) for t in canciones)

    return json.dumps({
        "canciones": len(canciones),
        "duracion_total_min": round(total, 1),
        "duracion_formato": f"{int(total // 60)}h {int(total % 60)}min" if total >= 60 else f"{int(total)}min",
        "sugerencia": "Playlist corta, podrías agregar más canciones" if total < 30 else "Buena duración"
    }, ensure_ascii=False)

Ahora el agente tiene tres herramientas. Y aquí es donde se ve el agent loop en acción:

dj = Agent(
    model=modelo,
    system_prompt="""Eres un DJ y curador musical experto.
    Usa tus herramientas para armar playlists basadas en la biblioteca real del usuario.
    Considera el mood, la energía, y la duración para crear una experiencia coherente.""",
    tools=[buscar_canciones, analizar_energia, duracion_playlist]
)

dj("Armame una playlist de una hora para una fiesta en casa")

El agente no ejecuta las herramientas en un orden predefinido. No hay un pipeline que diga "primero busca, luego analiza, luego calcula duración". El modelo recibe los tool specs (nombre, descripción, parámetros) y en cada iteración del loop decide: ¿necesito más información? ¿Qué tool me la da? ¿Con qué parámetros?

En este caso: llama a buscar_canciones(mood="fiesta"), analiza la energía con analizar_energia(canciones=[...]) para ordenarlas con un flow ascendente, y verifica la duración con duracion_playlist(canciones=[...]) para cubrir la hora completa. Si la duración no alcanza, puede volver a llamar buscar_canciones con otros criterios.

Tú no orquestaste nada. El modelo resolvió la secuencia en runtime.

Nota sobre modelos locales: con llama3.1:8b, el agente invoca los tools correctamente pero a veces ignora los resultados y alucina canciones que no están en tu biblioteca. Esto es una limitación del tamaño del modelo (8B parámetros), no del SDK. Con una sola herramienta (Capa 2) funciona bien; con múltiples tools el modelo se confunde más fácilmente. Si necesitas tool-calling más confiable, usa un modelo más grande (llama3.1:70b) o un modelo cloud como Claude o GPT-4 (ver la sección "De tu laptop a la nube").

Y si quieres entender cómo funciona por dentro, el código está ahí. El agent loop de Strands no es una caja negra. Es código abierto que puedes leer en GitHub.

Capa 4: Memoria — el DJ te conoce

Hay un problema con todo lo que hemos construido hasta ahora.

Cada conversación empieza de cero.

Le dices "me encanta el indie rock", cierras la conversación, vuelves al día siguiente, y el agente no tiene idea de quién eres. Es como ir a un bar donde el DJ cambia cada vez que parpadeas.

Strands resuelve esto con session management. FileSessionManager persiste el historial de conversación a disco como archivos JSON, organizados por sesión y agente. Cuando el agente se inicializa con un session_id existente, carga los mensajes anteriores y el modelo los tiene como contexto.

from strands import Agent
from strands.models.ollama import OllamaModel
from strands.session.file_session_manager import FileSessionManager

modelo = OllamaModel(model_id="llama3.1", host="http://localhost:11434")

# El session manager guarda las conversaciones a disco
# session_id identifica al usuario, storage_dir es donde se guardan los archivos
session_manager = FileSessionManager(session_id="usuario-1", storage_dir="./sesiones")

dj = Agent(
    model=modelo,
    system_prompt="""Eres un DJ y curador musical experto.
    Recuerdas los gustos del usuario entre conversaciones.
    Si el usuario ya te dijo qué le gusta, úsalo para personalizar tus playlists.""",
    tools=[buscar_canciones, analizar_energia, duracion_playlist],
    session_manager=session_manager,
)

# Primera conversación
dj("Me encanta el indie rock y el shoegaze. No soporto el reggaetón.")

# ... tiempo después, otra conversación ...

# El agente recuerda
dj("Armame algo para el viernes")
# → Arma una playlist de indie rock y shoegaze, sin reggaetón

Pocas líneas y tu agente tiene continuidad.

Y aquí viene lo interesante desde el punto de vista open source: FileSessionManager es una implementación de la interfaz SessionManager. Guarda sesiones a disco como archivos JSON organizados por sesión y agente. Pero si quieres guardar sesiones en Redis, en Postgres, o en S3, implementas la interfaz y listo. Ya existen session managers de la comunidad, como el de AgentCore Memory. La arquitectura está diseñada para que la comunidad la extienda.

De tu laptop a la nube (en una línea)

Todo lo que hemos construido corre localmente. Ollama en tu máquina, modelo en tu máquina, datos en tu máquina.

Pero si quieres compartir tu agente con el mundo, necesitas algo más.

Y aquí está lo elegante de la arquitectura: el SDK abstrae el model provider detrás de una interfaz común. Cambiar de proveedor es cambiar la instanciación del modelo — el resto del código no se entera.

# Local con Ollama
from strands.models.ollama import OllamaModel
modelo = OllamaModel(model_id="llama3.1", host="http://localhost:11434")

# En la nube con Amazon Bedrock
from strands.models import BedrockModel
modelo = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0", region_name="us-east-1")

El resto del código del agente no cambia. Ni una línea. Los tools, el system prompt, el session manager: todo igual. Esto es posible porque Strands define una interfaz Model que todos los providers implementan — OllamaModel, BedrockModel, OpenAIModel, AnthropicModel, etc.

Esa es la arquitectura en capas:

La capa open source es la constante. El proveedor de abajo es la variable. Ollama, Bedrock, OpenAI, Anthropic, Google Gemini, LiteLLM: todos son plugins que implementan la misma interfaz. Sin esa capa de abstracción, estás atado al SDK del vendor con el que empezaste.

Lo que aprendiste

Un agente de IA no es magia. Es un modelo + herramientas + un loop de razonamiento.

Construimos un DJ de playlists capa por capa: primero un agente que solo habla, luego le dimos herramientas para buscar en una biblioteca real de canciones, después agregamos más tools y vimos cómo el modelo decide solo qué llamar y en qué orden, le dimos memoria para que recuerde tus gustos, y al final mostramos que el mismo código puede correr local o en la nube cambiando una línea.

Todo con Python, Strands Agents y Ollama. Todo open source. Todo en tu laptop.

Qué sigue

Si quieres ir más allá:

Documentación de Strands Agents — guías, ejemplos, y API reference
Repo de Strands en GitHub — el código fuente completo, licencia Apache 2.0
Community tools — herramientas creadas por la comunidad que puedes usar y extender
Ollama — para correr modelos localmente

El DJ sabe de música. ¿Qué vas a construir tú?

¿Te resultó útil este artículo? Compártelo con tu equipo o déjame saber en los comentarios qué agente te gustaría construir. Y si ya estás experimentando con Strands o con agentes de IA en general, me encantaría escuchar tu experiencia.

Lost in the AI Hype, I Started Small

Rohini Gaonkar — Wed, 15 Apr 2026 14:32:01 +0000

And it helped me get back into tech without drowning

TL;DR at the end

Coming back to tech after a (maternity) break is a strange feeling.

You’re excited but also unsure where to begin. There are new tools, new terminologies and new way of doing things we did for decades.

But I didn’t try to figure everything out at one go, I just picked one small thing.

For me, that “one small thing” was finally building my portfolio collection.

Over the years, my content - blog posts, YouTube videos, conference talks, GitHub repos, social posts all of them scattered across dev.to, GitHub, YouTube, Instagram, LinkedIn, and AWS channels - has been scattered across a dozen different platforms. DEV.to, community.aws, YouTube, GitHub (two accounts!), LinkedIn, SlideShare... you name it. 🙇‍♀️

More than 80 pieces of content, scattered across platforms since 2015!!!

And honestly? Maintaining my existing site rohinigaonkar.com felt harder than starting from scratch.

I wanted something simpler, a lightweight site I can update by editing a single file, push to GitHub, and it's live. Easy to navigate, easy to maintain. No fluff.

I built this as my first project back from maternity leave, and I did it with Kiro, an AI-powered IDE from AWS that I'd never used before. Two firsts at once. It turned out to be the perfect re-entry project.

Building It with Kiro: My First Impressions

This portfolio had been on my mental to-do list forever, so the timing felt right. And rather than spinning up a complex stack to shake off the rust, I decided to keep it simple and lean on an AI coding assistant to help me get back into the flow.

Here's what stood out about the experience, starting with the simplest features and building up.

Last one might surprise you!!! 🤯

1. Chat-Driven Development

The entire project was built through conversation.

I described what I wanted, "I have this website where I collect my content shared across multiple social media websites. it is one true place where any tech content I posted on the web be it dev.to, github, youtube, instagram, and any aws first party channels, all of this to be collected as a timeline. can we build something that can be refreshed on demand and build this portfolio. make it professional looking. ask more intelligent questions as we go.", and Kiro asked clarifying questions even before writing a single line of code.

It asked about static vs dynamic, hosting preferences, design vibe, and data source approach. It even asked me about my identity. That back-and-forth shaped the architecture before any code was generated.

Once I provided response to all the questions, it help build the initial structure and also walked me through it.

Notice how after every conversation, it shows how many credits each prompt consumes, in real-time. That was nice!

There is a spec-driven development mode as well, which I would be testing for something more complex than this static website.

2. Web Search

Kiro searched the web to find my existing content across platforms. It looked up my dev.to profile, GitHub repos, community.aws presence, YouTube channel, and even my current website at rohinigaonkar.com. This gave it real context about who I am and what content already exists, so the portfolio wasn't built with placeholder data, it was seeded with my actual content from day one.

3. Explore Real-Time File Changes

As Kiro generated and edited the files, I could see every change happening in real time through the explorer. Either click the "Follow" option or click on the little "diff button" highlighted with yellow square below.

For example, it created index.html or content.js, I could immediately open them, review the code, and see the diffs. When it later modified content.js to add YouTube videos or reclassify talks vs videos, I could see exactly what changed and why.

4. Trusting Frequently Run Commands

Kiro ran shell commands like curl to hit APIs and extract data. It asked my permission to run it once or add it to trusted list of commands.

I also liked how it provided my levels of trust, like I can just execute this particular command or partial or the base command.

In autopilot mode, I could trust these commands to execute without approving each one individually. This was especially useful during the YouTube oEmbed batch processing, where Kiro ran 16 consecutive curl commands to fetch video titles, approving each one manually would have been tedious.

5. Iterative Refinement Through Conversation

The project evolved through multiple rounds of feedback:

I pointed out that "talks" should only mean conference/meetup presentations, not YouTube tutorial videos - Kiro reclassified everything accordingly
I noted that some AWS "talks" were actually just YouTube embeds on my website - Kiro dug into the pages, extracted the real YouTube URLs, and recategorized them as videos
I shared my personal GitHub profile separately from my work one - Kiro pulled repos from both and updated the refresh script to handle multiple accounts

Each round of feedback made the portfolio more accurate without starting over or deleting some other important information.

6. The YouTube Challenge : Hitting Walls and Finding Workarounds

This was the most interesting part as YouTube is heavily locked down:

Direct fetch failed - webFetch on youtube.com returned empty content
Rendered mode failed - returned only JavaScript bootstrap code, no actual page content
Search was noisy - web searches for my videos returned generic results, not my specific content
RSS feeds blocked - YouTube's channel RSS wasn't accessible either

*But Kiro didn't give up!!! 💜 *

It found workarounds on its own:

oEmbed API - Kiro discovered that YouTube's oEmbed endpoint (youtube.com/oembed?url=...) returns video titles as JSON, and used curl to call it directly. This became the reliable method for all 16 videos I shared.
Squarespace page parsing - For videos embedded on my website, Kiro parsed the raw HTML to extract YouTube video IDs from Squarespace's embed block JSON (double HTML-unescaping the content to find URLs like youtube.com%2Fembed%2Fi0zQpJPfSdU).
Thumbnail URL extraction - It even tried extracting video IDs from ytimg.com/vi/VIDEO_ID/hqdefault.jpg thumbnail patterns as a fallback.

The iterative problem-solving here like trying one approach, hitting a wall, pivoting to another, felt very much like how a developer would debug a scraping problem.

I loved how Kiro told me what it tried, it failed and it was going to try something else. We also worked together for a process that was a good compromise for both of us. Maybe in future I will have an agent to simplify this, but for now this solves my purpose!

The Result

A live static portfolio at rohinigaonkar.github.io with ~80 entries spanning 2015–2025, filterable by type (blogs, videos, repos, talks, social), searchable, and refreshable on demand via a Node.js script that pulls from GitHub and dev.to APIs. All built through conversation in a single Kiro session.

What's Next

I'll keep adding content as I publish it. The refresh script makes the API-sourced stuff automatic, and the manual entries take about 30 seconds each. I might add dark mode at some point, and maybe an RSS feed. But right now, the simplicity is the feature.

More importantly, this project reminded me that coming back doesn't have to be intimidating.

If you're returning from a break and looking for a low-pressure way to get back into coding, I'd recommend picking a passion project and giving Kiro a try. You might surprise yourself with how quickly you get back into the zone.

And follow along as I explore this world of AI.

TL;DR:
Returning to tech after maternity leave felt overwhelming, so I started small by building a portfolio site to consolidate 80+ pieces of content scattered across platforms since 2015. Using AWS Kiro (an AI-powered IDE) for the first time, I built the entire project through conversation—no complex setup needed. Kiro helped with web searches, real-time file changes, iterative refinements, and creative problem-solving (especially when YouTube's APIs were locked down). The result: a live, searchable portfolio at rohinigaonkar.github.io that's easy to maintain. The lesson? Coming back doesn't have to be intimidating—pick one small passion project and let AI tools help you get back into the zone.

Amazon Bedrock for Beginners From First Prompt to AI Agent (Full Tutorial)

Morgan Willis — Tue, 14 Apr 2026 21:14:17 +0000

So you want to add AI to your application. Maybe you want to build a smart assistant, add a feature that analyzes user input, or you have an AI-powered side project you've been meaning to start.

On the surface, it sounds simple. Call a model, get a response. But once you actually try to build it, the questions start to stack up fast.

Which model do you use?
How do you call it from your application code?
What happens when you want the AI to interact with your own data or external systems?
And how do I control costs?

It can feel like you need to understand everything before you can build anything, but you don't.

Amazon Bedrock is a great place to start because it's a fully managed service on AWS that gives you API access to AI models from providers like Amazon, Anthropic, Meta, Mistral, and more. You don't need to set up servers, manage infrastructure, and you only pay for what you use.

On top of model access, Bedrock includes features like Knowledge Bases for connecting your own data, Guardrails for content safety, and tool use for interacting with the real world.

This post walks through Bedrock's main features with code examples you can run yourself in your own AWS account. Everything comes from the companion repo, which has full working implementations of each example. By the end, we'll combine everything into an AI agent using the Strands Agents SDK to build out a university FAQ chatbot.

A heads up before we start: we're going to do things step by step, and this could take a while if you're following along. Give yourself an hour or so if you're a total beginner. We'll work directly with the Bedrock APIs so you understand exactly how the pieces fit together. Then at the end, we'll take an easier approach that handles much of the complexity for you. Learning the fundamentals first will make everything make a lot more sense later.

If you prefer a video walkthrough, this post has an accompanying video that covers the same material with live demos:

Prerequisites

Before following along, you'll need:

Python 3.12+ installed on your machine
An AWS account with credentials configured locally
IAM User or Role Create an IAM user or role in your AWS account to follow along with the AWS Console steps, you cannot complete the tutorial using the root user.

You'll also need to install boto3, which is the Python SDK for interacting with AWS services programmatically. Run the following in the terminal in your IDE:

pip install boto3

Making API Calls to Amazon Bedrock

When you send a prompt to a model and receive a response, that process is called inference. You provide input, the model runs its computation, and it generates output.

For AI powered applications, you need to be able to run inference against models programmatically through an API. Bedrock exposes a set of APIs you can use. Let's start with the Converse API, which is the standard way to call models on Bedrock.

The Converse API uses the same standard request format regardless of which model you're talking to. That means you can switch from Amazon Nova to Meta Llama to Anthropic Claude Haiku but still use the same API.

Here's a complete first API call to Amazon Bedrock:

import boto3
import json

def use_converse_api():
    bedrock_runtime = boto3.client('bedrock-runtime', region_name='us-east-1')
    model_id = "us.amazon.nova-lite-v1:0"

    # Define a system prompt to set model behavior
    system_prompt = [
        {
            "text": "You are a helpful technical assistant who explains concepts clearly and concisely."
        }
    ]

    # User message
    user_message = "What is serverless computing?"

    # Use the Converse API
    response = bedrock_runtime.converse(
        modelId=model_id,
        system=system_prompt,
        messages=[
            {
                "role": "user",
                "content": [{"text": user_message}]
            }
        ],
        inferenceConfig={
            "temperature": 0.7,
            "maxTokens": 2000
        }
    )

    # Extract the response
    output_text = response['output']['message']['content'][0]['text']
    print(output_text)

    # Display token usage
    usage = response.get('usage', {})
    print(f"Input tokens: {usage.get('inputTokens', 'N/A')}")
    print(f"Output tokens: {usage.get('outputTokens', 'N/A')}")

if __name__ == "__main__":
    use_converse_api()

Let's break down the structure of this API call, because you'll see the same pattern throughout the rest of the examples:

At the top, we import boto3 and create a bedrock-runtime client. This client is how your Python code communicates with the Bedrock service over the network.

Then we define the model_id. We're using Amazon Nova Lite, a fast and cost-efficient model. Every model in Bedrock has a unique ID. You can find the full list in the supported model IDs documentation.

The call to converse() has three main parts:

system: The system prompt defines the model's role and behavior. Think of it as instructions for how the model should respond. The system prompt is sent with every inference request.
messages: The conversation between the user and the model. Each message has a role (either "user" or "assistant") and content. This structure lets the model understand who said what. In a real application, the user message would come from a frontend, a mobile app, or command line input. We're hardcoding it here to keep things simple.
inferenceConfig: Parameters that control how the model generates its response. temperature controls how random or creative the output is. Set it to 0.0 and you get the most predictable response every time, which is useful for tasks like classification or data extraction. Push it higher toward 1.0 and the output gets more varied, which works better for creative writing or brainstorming. maxTokens caps how long the response can be. Different models support different inference parameters, so check the documentation for the specific model you're using.

The Converse API is the recommended approach because it works the same across all models. Change the modelId from Nova to Llama to Mistral, and your code still works.

Understanding Tokens

Notice in the code above we printed token usage at the end of the script. Before we go further, you need to understand what tokens are, because they directly affect how much you pay.

A token is a small chunk of text. It might be a whole word, part of a word, or even punctuation. Different models break text into tokens in slightly different ways, and there is no universal standard. When you send a prompt to a model, your text gets broken into tokens. The model processes those tokens and generates new tokens as its response.

A short sentence like "What is serverless computing?" gets broken into several tokens. Longer prompts mean more input tokens. Longer responses mean more output tokens. You're billed for both, so the size of your prompt and the length of the model's response directly affect cost. Always set maxTokens to prevent runaway responses from driving up your bill.

Every model also has a context window, which is the maximum number of tokens it can handle in a single request. This is the model's working memory. Your input tokens and output tokens all need to fit inside the context window. If you exceed the window, then the API returns an error because it cannot process that many tokens in one call. This becomes important for long conversations and applications where you inject large amounts of data into the prompt for the model to reason over.

You can use the Bedrock pricing page to understand token costs for different models.

Multi-Turn Conversations

Up to this point, we've done single-turn interactions: one prompt, one response. But real applications usually need ongoing conversations where the model remembers what was said earlier.

Here's the thing though: models are stateless by design. Each API call is completely independent and the model doesn't remember anything from previous requests. You need to explicitly send the full conversation history with every call.

This is how all AI powered chat applications work. It seems like they remember everything you talked about between prompts, but that is only because the conversation history is collected and submitted into context through the prompt with every request.

That means when you are writing apps that need multi-turn conversations, your code is responsible for managing and sending the full context. Let's build a cooking assistant that demonstrates three conversation turns:

import boto3

def multi_turn_conversation():
    bedrock_runtime = boto3.client('bedrock-runtime', region_name='us-east-1')
    model_id = "us.amazon.nova-lite-v1:0"

    # System prompt sets the assistant's behavior
    system_prompt = [
        {
            "text": "You are a helpful cooking assistant. Provide concise recipe suggestions."
        }
    ]

    # Conversation history - we'll build this up with each turn
    conversation_history = []

    # Turn 1: Ask for recipe suggestions
    user_message_1 = "Suggest a quick dinner recipe with chicken."

    conversation_history.append({
        "role": "user",
        "content": [{"text": user_message_1}]
    })

    response_1 = bedrock_runtime.converse(
        modelId=model_id,
        system=system_prompt,
        messages=conversation_history,
        inferenceConfig={"temperature": 0.7, "maxTokens": 200}
    )

    assistant_message_1 = response_1['output']['message']['content'][0]['text']

    # Add assistant's response to history
    conversation_history.append({
        "role": "assistant",
        "content": [{"text": assistant_message_1}]
    })

    # Turn 2: Ask for modifications
    user_message_2 = "Can you make it vegetarian instead?"

    conversation_history.append({
        "role": "user",
        "content": [{"text": user_message_2}]
    })

    response_2 = bedrock_runtime.converse(
        modelId=model_id,
        system=system_prompt,
        messages=conversation_history,
        inferenceConfig={"temperature": 0.7, "maxTokens": 200}
    )

    assistant_message_2 = response_2['output']['message']['content'][0]['text']

    conversation_history.append({
        "role": "assistant",
        "content": [{"text": assistant_message_2}]
    })

    # Turn 3: Ask for cooking time
    user_message_3 = "How long will this take to prepare?"

    conversation_history.append({
        "role": "user",
        "content": [{"text": user_message_3}]
    })

    response_3 = bedrock_runtime.converse(
        modelId=model_id,
        system=system_prompt,
        messages=conversation_history,
        inferenceConfig={"temperature": 0.7, "maxTokens": 200}
    )

    assistant_message_3 = response_3['output']['message']['content'][0]['text']
    print(assistant_message_3)

if __name__ == "__main__":
    multi_turn_conversation()

The pattern is the same for every turn: append the user message to the conversation history, call the Converse API with the full history, then append the assistant's response back to the history.

The model can reference what was said in turn 1 when responding to turn 2, but only because you're resending everything. You're paying for those tokens each time too, which is why conversation history management matters for cost.

In production, you'd store conversation history somewhere persistent, like a database. When a user returns, you load their history and continue where they left off.

Showing you how to use the Converse API like this is essentially doing it the hard way, and we're doing this on purpose for learning purposes. In a real application, you also wouldn't have redundant code like this. You'd refactor common code into functions and collect user input dynamically.

There are higher-level libraries and frameworks that can handle a lot of that complexity for you, including managing the message history and formatting the request body. But we're working with the Bedrock APIs directly for now so you understand exactly how Bedrock and AI models actually work. Later, when I show you the simpler way using the Strands Agents SDK, you'll fully understand what's happening under the hood.

Tool Use (Function Calling)

Everything we've done has been purely text in, text out. The model generates a response based on its training data and whatever you include in the prompt. But this is problematic for real world usage.

You can’t rely on training data alone. Models have a knowledge cutoff based on when they were trained, and they don’t have access to real-time or external data like today’s weather, live content from the internet, or data stored in databases.

They don't know what's happening right now, and they can't take actions in the real world on their own.

That's where tool use comes in. Tools are functions that a model can request your application to run in order to interact with external systems. The model doesn't execute tools itself. It sends a structured request saying "I want to call this function with these arguments," and your code handles the actual execution.

This is how most modern AI applications work. A chatbot that does research for you using the internet? That's tool use. A coding assistant that reads files from your local disk? Tool use. A personal assistant bot that checks your calendar? Also tool use.

Now, this does get a bit involved when you're doing everything the hard way, but stick with me. This is important to understand when you are building a foundational understanding of how AI works.

Think of it like this:

1. You create tools in your code.
2. You write code to inform the model what tools exist and how to use them, this is often called a tool schema.
3. You send the model a prompt along with the tool schema.
4. The model reasons over the prompt and decides if it needs a tool to answer.
5. If it does need a tool, the model returns a response to your application code including information on which tool to call and with what arguments.
6. Your code runs the tool.
7. Your code sends the result of the tool call back to the model.
8. The model reasons over the tool result and works that information into its final response.

Here's the full tool use example following this flow:

import json
import boto3

# ---------------------------------------------------------------------------
# Step 1: Define your local Python functions
# ---------------------------------------------------------------------------
# These are regular Python functions. The model will never call them directly.
# Instead, the model will ASK us to call them by returning a tool_use block.

def get_weather(location, unit="fahrenheit"):
    """
    Simulate fetching weather data for a location.
    In a real app, this would call a weather API like OpenWeatherMap.
    """
    weather_data = {
        "location": location,
        "temperature": 58 if unit == "fahrenheit" else 14,
        "unit": unit,
        "condition": "Partly cloudy",
        "humidity": "72%",
        "wind": "8 mph NW",
    }
    return weather_data


# ---------------------------------------------------------------------------
# Step 2: Describe your functions as "tools" for the model
# ---------------------------------------------------------------------------
# The model needs a description of each tool so it knows:
#   - What the tool does (description)
#   - What inputs it expects (inputSchema)
#
# This is like writing documentation so someone else can use your function.

TOOL_CONFIG = {
    "tools": [
        {
            "toolSpec": {
                "name": "get_weather",
                "description": "Get the current weather for a given location.",
                "inputSchema": {
                    "json": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The city and state, e.g. 'San Francisco, CA'",
                            },
                            "unit": {
                                "type": "string",
                                "enum": ["fahrenheit", "celsius"],
                                "description": "Temperature unit (default: fahrenheit)",
                            },
                        },
                        "required": ["location"],
                    }
                },
            }
        }
    ]
}


# ---------------------------------------------------------------------------
# Step 3: Map tool names to actual Python functions
# ---------------------------------------------------------------------------
# When the model asks to use a tool, we look up the function by name here.

TOOL_FUNCTIONS = {
    "get_weather": get_weather,
}


def run_tool(tool_name, tool_input):
    """
    Look up a tool by name and call it with the provided input.
    Returns the result as a dictionary.
    """
    func = TOOL_FUNCTIONS.get(tool_name)
    if func is None:
        return {"error": f"Unknown tool: {tool_name}"}

    # ** unpacks the dict into keyword arguments:
    #   get_weather(**{"location": "Seattle"})  →  get_weather(location="Seattle")
    return func(**tool_input)


# ---------------------------------------------------------------------------
# Step 4: The main tool use loop
# ---------------------------------------------------------------------------

def tool_use_demo():
    bedrock = boto3.client("bedrock-runtime", region_name="us-east-1")
    model_id = "us.amazon.nova-lite-v1:0"

    user_message = "What's the weather like in Seattle right now?"

    messages = [
        {
            "role": "user",
            "content": [{"text": user_message}],
        }
    ]

    # First API call: send the message AND the tool definitions to the model
    response = bedrock.converse(
        modelId=model_id,
        messages=messages,
        toolConfig=TOOL_CONFIG,
        inferenceConfig={"temperature": 0.0, "maxTokens": 300},
    )

    stop_reason = response["stopReason"]
    assistant_message = response["output"]["message"]

    # Check: did the model ask to use a tool?
    if stop_reason == "tool_use":
        # Find the toolUse block in the response
        tool_use_block = None
        for block in assistant_message["content"]:
            if "toolUse" in block:
                tool_use_block = block["toolUse"]
                break

        tool_name = tool_use_block["name"]
        tool_input = tool_use_block["input"]
        tool_use_id = tool_use_block["toolUseId"]

        # Run the actual function
        result = run_tool(tool_name, tool_input)

        # Send the result back to the model
        messages.append(assistant_message)
        messages.append({
            "role": "user",
            "content": [
                {
                    "toolResult": {
                        "toolUseId": tool_use_id,
                        "content": [{"json": result}],
                    }
                }
            ],
        })

        # Second API call: model generates its final answer using the tool result
        final_response = bedrock.converse(
            modelId=model_id,
            messages=messages,
            toolConfig=TOOL_CONFIG,
            inferenceConfig={"temperature": 0.0, "maxTokens": 300},
        )

        final_text = final_response["output"]["message"]["content"][0]["text"]
        print(final_text)

if __name__ == "__main__":
    tool_use_demo()

Let's walk through what's happening:

Step 1 is defining the actual Python function. The tool in this case is a local function that simulates fetching weather data. In the real world, you'd swap this out by connecting it to a real API. The model will never call this function directly.

Step 2 is creating a tool schema that describes the function to the model. Think of this like writing documentation so the model knows how to use it. We give the tool a name, a description in natural language, and an input schema that lays out what parameters the tool accepts, their types, and whether they're required.

Step 3 is a dictionary that maps tool names to actual functions. When the model decides it needs a tool, it returns the name of the tool it wants to call. We need to be able to look that up and figure out which function to run. The run_tool function handles this dispatch.

Step 4 is the main loop. We call the Converse API with the user message and the tool config. The model sees the question, sees the available tools, and decides it needs the weather tool. It returns a tool_use block with the function name and arguments. Our code runs the actual function, then sends the result back to the model in a toolResult message. The model uses that real data to generate its final response.

The tool itself can be anything: a local function, an API call to another service, a database query, or a function running in the cloud. The pattern stays the same.

For more details, see the Bedrock tool use documentation.

RAG and Knowledge Bases

Tools are great, but one of the most common use cases for integrating AI into applications is to have it be able to reason over private data, but models don't have access to this data by default.

Models don't have access to your company's internal documentation, your product specs, or any of your proprietary data. If you ask a model about a companies internal processes, it's going to hallucinate something that seems plausible but is actually completely made up.

Retrieval Augmented Generation (RAG) is the common fix for this. The concept is simple: before you ask the model to generate an answer, you first search your own documents for relevant information. Then you include that data in the prompt. The model generates its response grounded in your actual data instead of relying only on what it learned during training.

Retrieve the data, augment the prompt, generate the response. That's where the abbreviation RAG comes from.

How the Retrieval Part Works

The retrieval step uses semantic search, which is different from traditional keyword search. Keyword search looks for exact word matches, while semantic search understands the meaning of the text and searches on that instead.

If your document says "customers can return items within 30 days," semantic search will find it when someone asks about "refund window" or "return period," even though those exact words don't appear. The words "queen" and "king" aren't a direct match either, but they're semantically similar because they both represent royalty. Semantic search finds that relationship but traditional search would not.

To make semantic search work, your data needs to be converted into numbers, or vectors, so the computer can compare meaning mathematically. Here's how the pipeline works:

Upload and Chunking: Upload your documents and then break them into smaller passages called chunks. A 50-page PDF would become many chunks. There are different chunking methods depending on your use case and data structure.
Embedding: Each chunk gets run through an embedding model, which converts the text into a vector, or a list of numbers that represents the meaning of that text. Think of it as a numerical fingerprint of what the text is about.
Storage: Those vectors get stored in a vector database, optimized for searching across vectors quickly.
Retrieval: When a user asks a question, that question also gets converted into a vector. The vector database queries the data and finds the chunks whose vectors are closest to the question's vector semantically. Those are your most relevant passages.
Generation: The relevant passages get included in the prompt passed to the model, and the model generates an answer grounded in that data.

RAG is powerful, but there's a lot of plumbing involved to make it all work. You have to manage the chunking strategy, run embeddings, pick and maintain a vector database, write retrieval logic, and keep everything in sync when documents change. Luckily, Bedrock does this for you.

Bedrock Knowledge Bases

Bedrock Knowledge Bases automate the entire RAG pipeline. You point it at your documents in S3 (or other sources like Confluence, SharePoint, or Salesforce), and it handles ingestion, chunking, embedding, and vector storage. Then you query it with a single API call.

For example, what if a university wanted to make a chatbot to help students find answers to frequently asked questions about course enrollment deadlines, financial aid policies, and general campus information. That is a perfect use case for RAG.

We'll incrementally build this university chatbot example throughout the rest of this post starting with knowledge base creation. If you want to follow along, use the companion repo which contains the full instructions. This includes sample FAQ documents about enrollment, financial aid, housing, and campus services that we will use as the private data.

To create a Knowledge Base, you need to upload your documents to Amazon S3, a data storage service, first. You can go to the Amazon S3 Console and create a new bucket. Then, upload the knowledge base documents to the bucket.

After that, go to the Bedrock console to Create a knowledge base. You'll connect the S3 bucket containing the FAQ documents, choose an embedding model (Amazon Titan Embed is a good default), and select a vector store. If you're just getting started, Amazon S3 Vectors is the simplest and most cost-effective option since it doesn't require you to provision a separate vector database. Then sync the data.

Once your Knowledge Base is created and synced, querying it is a single API call to Bedrock using retrieve_and_generate:

import boto3

# REPLACE THIS with your Knowledge Base ID
KNOWLEDGE_BASE_ID = "YOUR_KB_ID"  # From the Bedrock console
MODEL_ID = "us.amazon.nova-lite-v1:0"

def query_knowledge_base(question):
    bedrock_agent_runtime = boto3.client('bedrock-agent-runtime', region_name='us-east-1')

    # Use retrieve_and_generate to query the Knowledge Base
    response = bedrock_agent_runtime.retrieve_and_generate(
        input={
            'text': question
        },
        retrieveAndGenerateConfiguration={
            'type': 'KNOWLEDGE_BASE',
            'knowledgeBaseConfiguration': {
                'knowledgeBaseId': KNOWLEDGE_BASE_ID,
                'modelArn': MODEL_ID
            }
        }
    )

    # Extract the generated response
    output_text = response['output']['text']
    print(output_text)

    # Display source citations
    citations = response.get('citations', [])
    if citations:
        print("\nSources:")
        for idx, citation in enumerate(citations, 1):
            for reference in citation.get('retrievedReferences', []):
                location = reference.get('location', {})
                s3_location = location.get('s3Location', {})
                uri = s3_location.get('uri', 'Unknown')
                print(f"  [{idx}] {uri}")

if __name__ == "__main__":
    question = "When is spring break this year?"
    query_knowledge_base(question)

Notice the client is bedrock-agent-runtime, not bedrock-runtime. Knowledge Bases use a different API from the Converse API we've been working with.

The retrieve_and_generate call does both RAG steps in one step: it retrieves relevant documents using semantic search, then passes them to the model to generate a response. You get both the answer and citations pointing back to the source documents, so your users can verify where the information came from.

For more on creating and configuring Knowledge Bases, see the Bedrock Knowledge Bases documentation.

Guardrails (Content Safety)

You now know how to build an AI app that can access your data using RAG and interact with external systems through tools. But before you put something like this in front of real users, you need to think about what happens when people try to misuse it or when the model generates something it shouldn't.

When you put an AI application on the internet, you have to assume it will be abused. You can't fully trust user input, and you can't blindly trust model output either.

Guardrails are content filters that get enforced before and after the model is called. They sit outside the prompt as structural policies. You configure your guardrails once, reference them in your API calls, and they work across any model.

Available filters include:

Content filters: Detect harmful content like hate speech, violence, sexual content, and even prompt attacks like jailbreaks or prompt injection attempts, with adjustable severity thresholds
Denied topics: Block entire categories like "investment advice" or "medical diagnosis"
Word filters: Block specific words or phrases, including profanity
Sensitive information filters: Find and mask sensitive data like PII, social security numbers, credit cards, and email addresses
Contextual grounding checks: check model responses against a reference source to reduce hallucinations

To create a Guardrail, you can use the Bedrock console. You give the guardrail a name, configure the content filters with severity thresholds that make sense for your use case, and optionally add denied topics or PII filters. Once configured, create a version to get a guardrail ID and version number.

For the university chatbot, imagine a student tries to ask the assistant something inappropriate, like how to cheat on an exam or how to hack the university network. A guardrail can detect that type of request and block it before the model ever generates a response.

Here's how you add it to a Knowledge Base query:

import boto3

# REPLACE THESE with your actual IDs
KNOWLEDGE_BASE_ID = "YOUR_KB_ID"
GUARDRAIL_ID = "YOUR_GUARDRAIL_ID"
GUARDRAIL_VERSION = "1"
MODEL_ID = "us.amazon.nova-lite-v1:0"


def query_kb_with_guardrail(question):
    bedrock_agent = boto3.client("bedrock-agent-runtime", region_name="us-east-1")

    response = bedrock_agent.retrieve_and_generate(
        input={"text": question},
        retrieveAndGenerateConfiguration={
            "type": "KNOWLEDGE_BASE",
            "knowledgeBaseConfiguration": {
                "knowledgeBaseId": KNOWLEDGE_BASE_ID,
                "modelArn": MODEL_ID,
                "generationConfiguration": {
                    "guardrailConfiguration": {
                        "guardrailId": GUARDRAIL_ID,
                        "guardrailVersion": GUARDRAIL_VERSION,
                    },
                },
            },
        },
    )

    print(response["output"]["text"])


if __name__ == "__main__":
    question = "How can I cheat on my finals this year?"
    query_kb_with_guardrail(question)

To use a guardrail, all you have to do is add a generationConfiguration with the guardrail identifier and version number inside the knowledge base configuration. Everything else in your code stays exactly the same.

A normal question like "When is spring break?" passes through and gets answered normally. But "How can I cheat on my finals?" gets blocked by the guardrail before the model ever generates a response.

You can also add guardrails directly to Converse API calls using the guardrailConfig parameter:

response = bedrock_runtime.converse(
    modelId=model_id,
    messages=messages,
    guardrailConfig={
        'guardrailIdentifier': 'your-guardrail-id',
        'guardrailVersion': '1'
    }
)

For more details on guardrail configuration options, see the Bedrock Guardrails documentation.

Putting It All Together with an Agent

We've been doing everything the hard way on purpose so you could see how the pieces actually work. You might be thinking "that tool use code was a lot of work for one function call" and you'd be right.

Managing the message history, parsing tool requests, executing functions, and sending results back to the model manually is tedious. And it gets more complicated when the model needs multiple tools or several steps to complete a task.

Additionally, real-world applications need more than a single prompt and response with hardcoded user queries. You need to take dynamic input from the user and pass it to the model. Then the model might need to look up information, call tools, and take several steps before it can answer a question.

An agent is a system that lets the model do this. Instead of taking in one prompt and responding one time, it can think through the problem, decide what action to take next, use tools if needed, and repeat that process until it reaches a final answer. Under the hood, the model may be called multiple times as part of a loop until the task is complete.

Now we are going to switch to a using higher-level framework that handles much of the complexity around building AI applications for you.

Strands Agents SDK is an open-source framework from AWS that makes building AI agents straightforward. It integrates directly with Bedrock, though it supports any model provider, and handles the orchestration we've been doing manually.

Under the hood, when you use Amazon Bedrock as the model provider, it's calling the same Converse API we've been using throughout this post. That's why it was worth learning the fundamentals first. This should all make sense now rather than feeling like magic.

To get started with Strands, install the packages:

pip install strands-agents strands-agents-tools

Here's the university chatbot as a Strands agent that combines everything we covered: a Bedrock model, a Knowledge Base for university data, a custom tool for course lookups, and a guardrail for content safety:

import os
from strands import Agent, tool
from strands.models import BedrockModel
from strands_tools import retrieve

# ============================================================
# Configuration — Replace these with your resource IDs
# ============================================================

KNOWLEDGE_BASE_ID = "YOUR_KB_ID"
GUARDRAIL_ID = "YOUR_GUARDRAIL_ID"
GUARDRAIL_VERSION = "1"
MODEL_ID = "us.amazon.nova-lite-v1:0"
REGION = "us-east-1"


# ============================================================
# Custom Tool: Look Up Course Schedule
# ============================================================

@tool
def lookup_course(department: str, course_number: str) -> str:
    """Look up schedule and details for a specific course.

    Use this when a student asks about a particular class,
    like "When does CS 201 meet?" or "Who teaches BIO 101?"

    Args:
        department: The department code (e.g., "CS", "BIO", "ENG").
        course_number: The course number (e.g., "101", "201").

    Returns:
        Course details including schedule, instructor, and location.
    """
    # In a real app this would query a course catalog API
    courses = {
        "CS-101": {
            "title": "Introduction to Programming",
            "instructor": "Dr. Maria Chen",
            "schedule": "Mon/Wed/Fri 10:00 - 10:50 AM",
            "location": "Turing Engineering Building, Room 210",
            "credits": 3,
            "seats_available": 12,
        },
        "CS-201": {
            "title": "Data Structures",
            "instructor": "Prof. James Park",
            "schedule": "Tue/Thu 1:00 - 2:15 PM",
            "location": "Turing Engineering Building, Room 215",
            "credits": 3,
            "seats_available": 5,
        },
        "BIO-101": {
            "title": "General Biology I",
            "instructor": "Dr. Sarah Williams",
            "schedule": "Mon/Wed 2:00 - 3:15 PM",
            "location": "Science Hall, Room 105",
            "credits": 4,
            "seats_available": 20,
        },
        "ENG-102": {
            "title": "College Writing II",
            "instructor": "Prof. David Nguyen",
            "schedule": "Tue/Thu 9:30 - 10:45 AM",
            "location": "Humanities Building, Room 302",
            "credits": 3,
            "seats_available": 8,
        },
        "MATH-151": {
            "title": "Calculus I",
            "instructor": "Dr. Lisa Patel",
            "schedule": "Mon/Wed/Fri 11:00 - 11:50 AM",
            "location": "Math & Science Center, Room 120",
            "credits": 4,
            "seats_available": 15,
        },
    }

    key = f"{department.upper()}-{course_number}"
    if key in courses:
        c = courses[key]
        return (
            f"Course: {key} — {c['title']}\n"
            f"Instructor: {c['instructor']}\n"
            f"Schedule: {c['schedule']}\n"
            f"Location: {c['location']}\n"
            f"Credits: {c['credits']}\n"
            f"Seats available: {c['seats_available']}"
        )

    return f"No course found for {key}. Check the department code and course number."


# ============================================================
# Build the Agent
# ============================================================

def create_university_agent():
    """Create the University chatbot agent."""

    # The built-in retrieve tool reads this env var to find the KB
    os.environ["KNOWLEDGE_BASE_ID"] = KNOWLEDGE_BASE_ID
    os.environ["AWS_REGION"] = REGION

    bedrock_model = BedrockModel(
        model_id=MODEL_ID,
        region_name=REGION,
        temperature=0.3,
        max_tokens=2000,
        guardrail_id=GUARDRAIL_ID,
        guardrail_version=GUARDRAIL_VERSION
    )

    system_prompt = """You are the University virtual assistant.
You help students, prospective students, and parents find information about the university.

Your responsibilities:
- Answer questions about academics, admissions, financial aid, housing, dining, parking, the library, career services, and the academic calendar.
- Use the retrieve tool to search the knowledge base for university policies and FAQ answers before responding.
- Use the lookup_course tool when someone asks about a specific course schedule, instructor, or availability.
- Cite your sources when referencing specific policies or dates.

Guidelines:
- Be friendly and welcoming — remember, students may be stressed about deadlines.
- If you don't know the answer, say so and suggest they contact the relevant office.
- Keep answers concise and helpful."""

    agent = Agent(
        model=bedrock_model,
        tools=[retrieve, lookup_course],
        system_prompt=system_prompt,
    )

    return agent


# ============================================================
# Run the Agent
# ============================================================

def main():
    print("University Chatbot")
    print("=" * 60)
    print("Ask me about admissions, financial aid, housing, dining,")
    print("course schedules, the academic calendar, and more.")
    print("\nType 'quit' to exit.\n")

    agent = create_university_agent()

    while True:
        user_input = input("You: ").strip()
        if not user_input:
            continue
        if user_input.lower() in ("quit", "exit", "q"):
            print("Goodbye!")
            break

        print("\nAssistant: ", end="", flush=True)
        response = agent(user_input)
        print(f"\n{response}\n")


if __name__ == "__main__":
    main()

Let's walk through what's different here compared to the manual approach.

At the top, we import a few things from the Strands framework: Agent, the @tool decorator for creating custom tools, BedrockModel for the model provider, and the built-in retrieve tool from strands_tools which queries the Knowledge Base we created earlier.

Then we define our configuration. We need a Knowledge Base ID for RAG, a Guardrail ID for content filtering, and we're using Amazon Nova as our model. All things we've already set up and used individually.

The @tool decorator is how you define custom tools in Strands. We've got a lookup_course tool that simulates looking up course information. In a real application, this would query a database. Compare this to the manual tool use code from earlier and you'll notice there is no lengthy tool schemas, message parsing, or dispatch logic. You just write a function with a docstring and Strands handles the rest.

Strands also includes a built-in retrieve tool that works directly with Bedrock Knowledge Bases. You set the Knowledge Base ID as an environment variable, and the agent decides when to use it.

We created a BedrockModel instance with the model ID, region, inference parameters, and guardrail information. Then we defined the system prompt telling the agent it's a university chatbot and how it should handle requests. Finally, we created the agent with the model, the tools list (both custom and built-in), and the system prompt.

The last piece is the interactive loop. We read input from the command line and passed it to the agent. To call the agent, all you need is agent(user_input). The framework handles the entire agent loop: when the model needs a tool, Strands executes it and sends the result back to the model.

Multi-turn conversation management is handled too because each call maintains context from previous turns as long as the program is running.

Under the hood, Strands is calling the Converse API and using the different Bedrock features we covered throughout. This should all make a lot more sense now than if you jumped right into the agent framework.

The Strands documentation has more examples and configuration options.

What's Next

We covered a lot of ground. You now have the knowledge you need to start building real applications with AI on AWS using Amazon Bedrock.

Here are some areas to explore as your application grows:

Prompt caching can significantly reduce costs on repeated context. If you have a large system prompt or tool definitions that don't change between requests, caching avoids reprocessing those tokens every time.
Cross-region inference distributes load across AWS regions to balance the inference load. Instead of hitting limits in one region and failing, Bedrock can route your requests globally.
CloudWatch monitoring tracks token usage, latency, throttling, and error rates. Setting up monitoring early helps you catch cost spikes and performance issues before they become problems.

The companion repo has the complete code for every example in this post. Clone it, run the examples, and try adapting them to your own use case. Take one of these examples and adapt it to a new use case to push your learning even further and remember to always learn the fundamentals first.

Deploy OpenClaw on AWS: Choose the right options for your AI workload

Channy Yun — Tue, 14 Apr 2026 06:43:29 +0000

Since introducing OpenClaw on Amazon Lightsail on March 4, 2026, customers ranging from individual developers to enterprises have requested deployment options tailored to their specific workload requirements. This post presents four AWS offerings for running OpenClaw, each optimized for different use cases, organizational requirements, and scale.

Use this comparison to choose the deployment option that best fits your workload requirements. Amazon Lightsail provides simplicity for individual developers, while Amazon Elastic Compute Cloud (Amazon EC2) offers greater control and deeper AWS service integration. Amazon Bedrock AgentCore delivers a serverless approach for variable agentic AI workloads, and Amazon Elastic Kubernetes Service (Amazon EKS) provides enterprises with multi-tenant isolation and advanced orchestration capabilities.

The following sections explain how to get started with each deployment option.

OpenClaw on Amazon Lightsail
You can deploy OpenClaw using a prebuilt blueprint in Amazon Lightsail. With just a few clicks, you launch a fully configured instance with OpenClaw already integrated with Amazon Bedrock. The setup includes built-in security through device pairing, ensuring only authorized devices can access your AI assistant.

To get started, visit my previous blog post and getting started guide in the AWS documentation.

I want to introduce the Agent in Action, a hands-on lab guide built by Jorge Rodriguez, an AWS community leader. You can build a functional AI agent from scratch in about 45 minutes with OpenClaw on Amazon Lightsail. You’ll get web search capabilities and human-sounding voice responses powered by Amazon Bedrock.

OpenClaw on Amazon EC2
For those who need deeper AWS integration and control, Amazon EC2 provides the flexibility you need. Using AWS Graviton processors, you can save 20-40% on compute costs compared to x86 instances. AWS Systems Manager Session Manager provides secure shell access without exposing SSH ports to the internet. Amazon Virtual Private Cloud (Amazon VPC) endpoints ensure your traffic never leaves the AWS network, and AWS CloudTrail automatically logs every API call for compliance and auditing.

Follow this hands-on lab guide to deploy EC2 instances. If you want to deploy with AWS CloudFormation templates, visit the AWS Sample project.

OpenClaw on Amazon Bedrock AgentCore
While Lightsail and EC2 work well for getting started, they aren’t ideal for multi-user scenarios. Each user requires a dedicated instance, which limits scalability and lacks built-in user isolation. Additionally, you pay for compute resources whether they’re being used or not. For serverless deployments, Amazon Bedrock AgentCore offers a better solution.

Amazon Bedrock AgentCore is a purpose-built serverless runtime specifically designed for AI agents. You can focus on your agent logic, skills, and prompts, while AWS manages scaling, security, and availability. You can deploy OpenClaw on Bedrock AgentCore with this AWS Sample project.

The architecture supports asynchronous invocation—AWS Lambda immediately acknowledges the webhook, stores the message in Amazon DynamoDB, then invokes AgentCore in the background as an asynchronous event. The agent processes at its own pace and responds through the channel. This decoupling ensures no timeouts, provides built-in retry logic, and creates an audit trail of all interactions. It’s a production-grade pattern that handles the reality of serverless cold starts gracefully.

This sample project provides a deployment with Infrastructure-as-Code using AWS Cloud Development Kit (CDK). Clone the GitHub repository, run the deployment script, and within minutes you have a production-ready OpenClaw microVM running on Bedrock AgentCore.

I recommend that you use Kiro, an agentic AI development tool, to simplify the installation process and onboard quickly. Kiro will help you through the entire process of configuring a development environment, identifying dependencies, and deploying to AWS.

OpenClaw on Amazon EKS
Multi-tenancy represents the defining challenge for enterprise OpenClaw deployments. Amazon EKS with virtual machine (VM)-level isolation delivers the operational simplicity of shared infrastructure combined with the security advantages of dedicated VMs. Each tenant’s workload runs in a lightweight VM, providing hardware-level isolation while maintaining Kubernetes’s orchestration benefits. This approach has been validated in production by financial services and healthcare organizations with strict compliance requirements.

For multi-tenancy deployments of OpenClaw with Amazon EKS, there are two complementary approaches:

Kata container builds a standard implementation of lightweight VMs that perform like containers, but provide the workload isolation and security advantages of VMs. It’s application-agnostic, treating OpenClaw like any other workload. To getting started, visit the Multi-tenancy OpenClaw on EKS and OpenClaw on EKS with Kata Containers and LiteLLM.

OpenClaw Kubernetes Operator directly deploys and manages OpenClaw AI agent instances in Kubernetes clusters with production-grade security, observability, and lifecycle management. To get started, visit the Amazon EKS deployment guide.

You can think of the Kata Container as providing the foundation and the OpenClaw Kubernetes Operator as the specialized orchestration layer. You can choose these open source-based sample architectures for organizations serving hundreds or thousands of OpenClaw users from a single Kubernetes cluster.

Wrap up
Choose the deployment option that matches your requirements and scale. For individual developers and early experiments, Amazon Lightsail provides the fastest path—pre-configured, simple, and ready in minutes. Startups with AWS experience should consider Amazon EC2 for better integration and control. Amazon Bedrock AgentCore is transformative for teams without operation resources—it’s serverless, auto-scaling, and cheaper for other multi-user scenarios. Finally, enterprises with complex security requirements and multiple teams should use Amazon EKS for its VM-level isolation, sophisticated orchestration, and production-proven scalability.

You can start simple and evolve—begin with Lightsail for prototyping, then migrate to Bedrock AgentCore or EKS as your needs grow.

— Channy

AI Context Window Overflow: Memory Pointer Fix

Elizabeth Fuentes L — Mon, 13 Apr 2026 23:37:52 +0000

Context window overflow occurs when an AI agent's tool outputs exceed the token limit the large language model (LLM) can process at once. The agent doesn't crash; it silently truncates data, loses earlier context, or produces incomplete results. This post shows how the Memory Pointer Pattern fixes it: from single-agent to multi-agent coordination where 145KB of data never enters any LLM context.

This demo uses Strands Agents. The Memory Pointer Pattern is framework-agnostic and can be applied with LangGraph, AutoGen, or other agent frameworks that support tool context.

Working code: github.com/aws-samples/sample-why-agents-fail

Series: Why AI Agents Fail

Context Window Overflow (this post) — Memory Pointer Pattern for large data
MCP Tools That Never Respond — Async pattern for slow external APIs
AI Agent Reasoning Loops — Detect and block repeated tool calls

The Problem: Agents Can't Handle Large Tool Outputs

When an AI agent calls a tool that returns large data (server logs, database results, file contents), the response can overflow the LLM's context window. The agent doesn't crash with a clear error. It silently degrades: truncating data, losing context, or failing to complete the task.

Research from IBM (Solving Context Window Overflow in AI Agents, 2025) quantifies this:

In Materials Science workflows, tool outputs can reach 2M+ elements
Traditional approach consumed 20,822,181 tokens and failed
The same workflow with memory pointers used 1,234 tokens and succeeded
That's a reduction of over 16,000x in this workflow

Community observation (Context Window Limits Explained, Airbyte 2025) confirms teams discover these limits "the hard way" through silent errors. The agent appears to work but produces incomplete or wrong results.

The concept of passing references instead of raw data has also been validated in multi-agent settings. Research from Amazon (Towards Effective GenAI Multi-Agent Collaboration, 2024) introduces "payload referencing," where agents exchange pointers to shared data instead of embedding large payloads in messages. This improved performance on code-intensive tasks by 23% and achieved 90% end-to-end goal success rates in enterprise benchmarks. This is exactly what we implement below with Strands Swarm.

Why This Happens

When the tool output is small (a few KB), this works fine. But when a tool returns 200KB of server logs:

The full output gets injected into the conversation
The LLM's context window fills up
Older context (including the original question) gets pushed out
The LLM can't reason about the data because it can't see it all
The agent either fails or produces incomplete answers

Solution 1: Single Agent with Strands ToolContext

The first approach uses agent.state, a native key-value store scoped to each agent instance. Tools write large data there via ToolContext and return a short pointer string to the context:

from strands import Agent, tool, ToolContext

# context=True injects ToolContext as the last parameter — required to access agent.state
@tool(context=True)
def fetch_application_logs(app_name: str, tool_context: ToolContext, hours: int = 24) -> str:
    """Fetch application logs. Returns a memory pointer for large datasets."""
    logs = generate_logs(app_name, hours)  # Could be 200KB+

    if len(str(logs)) > 20_000:  # Threshold: store externally above 20KB
        pointer = f"logs-{app_name}"
        # Store the full payload in agent.state — it never enters the LLM context
        tool_context.agent.state.set(pointer, logs)
        # Return only the pointer key (52 bytes) — this is all the LLM sees
        return f"Data stored as pointer '{pointer}'. Use analyze tools to query it."
    return str(logs)  # Small enough to return directly

@tool(context=True)
def analyze_error_patterns(data_pointer: str, tool_context: ToolContext) -> str:
    """Analyze errors — resolves pointer from agent.state."""
    # Retrieve the full dataset from agent.state using the pointer key
    data = tool_context.agent.state.get(data_pointer)
    errors = [e for e in data if e["level"] == "ERROR"]
    # Return a summary (not raw data) — keeps the response small
    return f"Found {len(errors)} errors across {len(set(e['service'] for e in errors))} services"

The LLM never sees the 200KB. It only sees "Data stored as pointer 'logs-payment-service'" (52 bytes). The next tool reads the full data from agent.state and returns a summary. Strands handles this natively, with no global dicts, no hashlib, no external infrastructure.

Single Agent Results

Metric	Without Pointers	With Memory Pointers
Data in context	214KB (full logs)	52 bytes (pointer)
Agent behavior	Truncates/fails	Processes all data
Errors detected	Partial	Complete (all services)

Solution 2: Multi-Agent with Strands Swarm

A single agent works for linear pipelines. But real-world incident response involves specialized roles: someone fetches data, someone analyzes it, someone writes the report. Strands Swarm coordinates multiple agents autonomously: define agents with different tools, and the Swarm handles handoffs.

This is the same "payload referencing" pattern from the Amazon multi-agent collaboration paper. Agents exchange pointers to shared data instead of passing raw payloads. The difference is that Strands Swarm handles the coordination automatically, and provides invocation_state as the official API for sharing data across agents.

from strands import Agent, tool, ToolContext
from strands.multiagent import Swarm

# invocation_state is a dict shared across all agents in the Swarm — the cross-agent store
@tool(context=True)
def fetch_application_logs(app_name: str, tool_context: ToolContext, hours: int = 6) -> str:
    logs = generate_logs(hours)  # 145KB+
    pointer = f"logs-{app_name}"
    # Store in invocation_state so all downstream agents can access it without re-fetching
    tool_context.invocation_state[pointer] = logs
    # Only the pointer string travels through the LLM context to the next agent
    return f"Stored as '{pointer}'. Hand off to analyzer."

@tool(context=True)
def analyze_error_patterns(logs_pointer: str, tool_context: ToolContext) -> str:
    # Resolve the pointer to the full dataset — no LLM context consumed
    logs = tool_context.invocation_state.get(logs_pointer)
    errors = [l for l in logs if l["level"] == "ERROR"]
    result = {"total_errors": len(errors)}  # additional fields omitted for brevity
    # Store analysis results as another pointer for the reporter agent
    tool_context.invocation_state["error_analysis"] = result
    return json.dumps(result)

# Each agent has a focused role; the Swarm decides the handoff order autonomously
collector = Agent(name="collector", tools=[fetch_application_logs], model=MODEL)
analyzer = Agent(name="analyzer", tools=[analyze_error_patterns, detect_latency_anomalies], model=MODEL)
reporter = Agent(name="reporter", tools=[generate_incident_report], model=MODEL)

swarm = Swarm([collector, analyzer, reporter], entry_point=collector)
result = swarm("Fetch logs, analyze, and generate incident report.")

The Swarm automatically:

Starts with the collector, which fetches 145KB of logs and stores them in invocation_state
The collector hands off to the analyzer with the pointer "logs-payment-service"
The analyzer runs error and latency analysis, stores results in invocation_state, hands off to the reporter
The reporter generates the final incident report

No orchestration code or manual handoff logic is needed. Each agent has its own tools and the Swarm figures out the flow from the agent descriptions and the task. All data sharing happens via tool_context.invocation_state, the same ToolContext API used in single-agent, with a different store.

Swarm Results

Status: COMPLETED
Agents: collector → analyzer → reporter
Time: ~14s
Shared store:
  logs-payment-service: 145,310 bytes
  error_analysis: 135 bytes
  latency_analysis: 70 bytes

145KB of logs processed by three agents. None of it ever entered any LLM context window.

Follow-up Investigation

After the swarm completes, the data stays in the shared store. A separate investigator agent can drill into specific services without re-fetching:

# The investigator reuses invocation_state populated by the swarm — no data re-fetch needed
investigator = Agent(
    name="investigator",
    tools=[get_error_details, analyze_error_patterns],
    model=MODEL,
)

# Each question resolves the pointer from invocation_state and runs analysis in-memory
investigator("Which service had the most errors?")
investigator("Show me the error logs for cache-layer")
investigator("What status codes are those errors returning?")
# All queries read from the same 145KB already in invocation_state — no re-fetch, no context overflow

When to Use Each Approach

Single agent + agent.state — linear pipelines where one agent handles fetch + analyze + report. Use ToolContext to access tool_context.agent.state from tools.

Swarm + invocation_state — specialized roles, complex workflows, or when you want autonomous coordination. Use ToolContext to access tool_context.invocation_state — the official Strands API for multi-agent data sharing. The Swarm handles handoffs, timeouts, and repetitive handoff detection.

Both — use SlidingWindowConversationManager as additional protection. It automatically trims conversation history and handles ContextWindowOverflowException with retry.

These approaches are part of context engineering for AI agents: the practice of deciding what information enters the LLM's context window and when.

Try It Yourself

You need Python 3.9+, uv, and an OpenAI API key.

git clone https://github.com/aws-samples/sample-why-agents-fail
cd sample-why-agents-fail/stop-ai-agents-wasting-tokens/01-context-overflow-demo
uv venv && uv pip install -r requirements.txt
export OPENAI_API_KEY="your-key-here"

uv run python test_context_overflow.py   # Single-agent: 4 scenarios
uv run python swarm_demo.py              # Multi-agent: Collector → Analyzer → Reporter

Or open test_context_overflow.ipynb in Kiro, VS Code, or your preferred notebook environment.

Key Takeaways

Context overflow is silent — agents don't crash, they produce wrong results
Memory pointers solve it — store large data externally, pass references
>16,000x token reduction — validated by IBM Research on the Materials Science benchmark
Single-agent uses agent.state — @tool(context=True) + ToolContext to store and retrieve data outside context
Multi-agent uses invocation_state — same ToolContext API, shared across all agents in the Swarm. No orchestration code needed
Data persists for follow-up — after the pipeline completes, stored data is available for investigation without re-fetching

Frequently Asked Questions

Why do AI agents run out of context?

AI agents run out of context when tool responses are injected directly into the LLM conversation history. Each response consumes tokens. When cumulative tool outputs exceed the model's context window limit, the LLM loses earlier context, truncates data, or fails entirely. This happens silently: the agent appears to work but produces incomplete or wrong results.

What is the Memory Pointer Pattern for AI agents?

The Memory Pointer Pattern stores large tool outputs (logs, datasets, query results) in external state instead of the LLM context window. Tools return a short reference key (the "pointer") that subsequent tools use to retrieve the full data. IBM Research validated this pattern with a reduction of over 16,000x on the Materials Science benchmark.

How does agent.state differ from invocation_state in Strands Agents?

agent.state is scoped to a single agent instance. Use it for linear pipelines where one agent handles all steps. invocation_state is shared across all agents in a Strands Swarm. Use it when multiple specialized agents need to exchange data without passing large payloads through the LLM context.

Can I use the Memory Pointer Pattern with LangGraph or other frameworks?

Yes. The pattern requires two capabilities: a shared key-value store accessible from tools, and the ability to pass short reference strings through the LLM context. LangGraph provides this through its state management, AutoGen through shared memory, and CrewAI through task context. The Strands implementation uses ToolContext as the native API.

References

Research

Solving Context Window Overflow in AI Agents — IBM Research, Nov 2025
Towards Effective GenAI Multi-Agent Collaboration — Amazon, Dec 2024
Context Window Limits Explained — Airbyte blog (community observation), Dec 2025
Efficient On-Device Agents via Adaptive Context Management — Nov 2025

Implementation

Strands Agent State — ToolContext and agent.state
Strands Swarm — Multi-agent orchestration
Strands Conversation Management — Sliding window and context overflow

Have you hit context window limits in your agents? What strategies worked for you? Share in the comments.

Next in this series: MCP Tools That Never Respond — async patterns for slow external APIs.

All code in this series is open source under the MIT-0 License. Star the repository to follow updates.

Gracias!

🇻🇪Dev.to - Linkedin - GitHub - Twitter - Instagram - Youtube

DEV Community: AWS

Multi-step workflows que sobreviven fallos

El replay model por dentro

Anatomía de un checkpoint

Consideraciones sobre el tamaño de los datos

Rompiendo cosas a propósito — Escenario 1: Fallo transitorio

Simulando un fallo de red en el resize

Qué pasa cuando lo ejecutas

Estrategias de reintento

Exponential backoff: por qué importa

Aplicando retry strategy al step de watermark

Qué errores reintentar y cuáles no

Rompiendo cosas a propósito — Escenario 2: Fallo permanente

Simulando un archivo corrupto

Qué está pasando aquí

El patrón de compensación

Errores fuera de los steps

La regla: todo lo que puede fallar va dentro de un step

¿Qué es idempotencia?

La analogía del elevador

En software

Cómo hacer idempotente lo que no lo es

Idempotencia en Durable Functions: la regla que nadie te dice

El ejemplo del procesamiento de imágenes

Checklist de idempotencia para tus steps

AT_MOST_ONCE_PER_RETRY: la red de seguridad del SDK

Rompiendo cosas a propósito — Escenario 3: Timeout de la función

Pero espera... ¿y el durableConfig.executionTimeout?

Monitoreando fallos en la consola

Tips para debugging efectivo

Patrones de resiliencia

1. Retry con backoff exponencial

2. Compensación

3. Circuit breaker manual

4. Dead letter queue para workflows irrecuperables

Lo que aprendiste

Qué sigue

Como funciona um site na internet

Como sites são criados?

Onde moram os sites que vemos na internet?

Como podemos dar um nome bonito aos nossos sites?

Como acessamos o conteúdo de um site?

Deixando sites mais rápidos: a mágica do cache

Conclusão

Two Pointers en entrevistas técnicas: 3 problemas resueltos

¿Qué son los problemas de entrevistas técnicas?

¿Qué es Two Pointers?

¿Qué técnicas incluye?

¿Cómo saber cuál técnica usar?

Opposite direction: Verificar un palíndromo

¿Cómo lo pensamos?

Solución paso a paso

Fast and slow: Remove Duplicates

¿Cómo lo pensamos?

Solución paso a paso

Parallel pointers: Intersección de dos arrays

¿Cómo lo pensamos?

Solución paso a paso

Resumen

Build your own blog post view counter on AWS Free Tier

What you're building

Prerequisites

Project setup

Step 1: The DynamoDB table

Step 2: The Lambda function

Step 3: The infrastructure

Step 4: Deploy

Step 5: Add it to your blog

Step 6: Check your view counts

How much does this cost?

What you just learned

Cleanup

What to try next

¿Qué es un Modelo de IA? Explicación sencilla

1. ¿Qué es un modelo?

2. ¿Cómo interactúas con un modelo?

3. ¿Cómo elijo un modelo?

Generación de texto

Multimodalidad

Ventana de contexto

Pero espera... ¿y el `durableConfig.executionTimeout`?