<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
    <channel>
        <title>Blog de Gerardo Arroyo - Compartiendo experiencias reales con AWS</title>
        <description>Blog de Gerardo Arroyo sobre temas relacionados con AWS y Java</description>
        <link>https://gerardo.dev/</link>
        <atom:link href="https://gerardo.dev/feed.xml" rel="self" type="application/rss+xml"/>
        <pubDate>Fri, 13 Nov 2026 17:41:35 -0600</pubDate>
        <lastBuildDate>Fri, 13 Nov 2026 17:41:35 -0600</lastBuildDate>
        <generator>Jekyll v4.4.1</generator>
        
            <item>
                <title>Bedrock Prompt Shortening: 6 optimizaciones, 0 cambios y un +45% falso</title>
                <description>&lt;p&gt;En el artículo del &lt;a href=&quot;/agentcore-optimization-loop.html&quot; target=&quot;_blank&quot;&gt;Optimization Loop de AgentCore&lt;/a&gt; dejé que AWS reescribiera el system prompt de mi agente DevOps. La recomendación fue buena, pero tuvo un efecto que en ese momento no medí: el prompt creció. El optimizador conservó todo lo que yo había escrito y le agregó dos bloques nuevos.&lt;/p&gt;

&lt;p&gt;La documentación de Advanced Prompt Optimization lo reconoce: por defecto optimiza solo por calidad, sin ninguna restricción de longitud, y un prompt optimizado puede terminar más largo que el original. Más largo significa más tokens de entrada en cada llamada y, potencialmente, más tiempo hasta el primer token.&lt;/p&gt;

&lt;p&gt;El &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/10/bedrock-prompt-optimization-shortening/&quot; target=&quot;_blank&quot;&gt;20 de octubre de 2026 AWS anunció&lt;/a&gt; una opción para eso, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;shortenPrompt&lt;/code&gt;, que le pide al optimizador un prompt más corto que el original y con un puntaje igual o mejor. Si no lo encuentra, te devuelve el tuyo.&lt;/p&gt;

&lt;p&gt;Quería responder una pregunta concreta: &lt;strong&gt;¿cuánto me ahorra acortar un prompt que ya funciona, y a partir de qué volumen vale la pena?&lt;/strong&gt; Para eso usé el prompt real del clasificador de mi agente de noticias, las 205 clasificaciones que hizo en producción como referencia y tres modelos objetivo. El resultado no fue el que esperaba, y tampoco por las razones que esperaba.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;&lt;strong&gt;📌 TL;DR — Lo que encontré&lt;/strong&gt;&lt;/p&gt;

  &lt;ul&gt;
    &lt;li&gt;En las &lt;strong&gt;seis optimizaciones&lt;/strong&gt; (tres modelos, con y sin &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;shortenPrompt&lt;/code&gt;), el prompt que devolvió el servicio es &lt;strong&gt;idéntico al original&lt;/strong&gt;, carácter por carácter. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compressionRatio = 1.0&lt;/code&gt; en los tres modelos.&lt;/li&gt;
    &lt;li&gt;Un job reportó &lt;strong&gt;+45% de mejora&lt;/strong&gt; (0.575 → 0.833) para ese prompt idéntico. La causa: 12 inferencias fallidas del lado original, con cero tokens, puntuadas como 0.&lt;/li&gt;
    &lt;li&gt;Otro job terminó en &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Completed&lt;/code&gt; con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SUCCESS&lt;/code&gt;&lt;/strong&gt; aunque el optimizador falló en &lt;strong&gt;684 de 689 llamadas&lt;/strong&gt;. Solo lo vi en las métricas de error de CloudWatch.&lt;/li&gt;
    &lt;li&gt;Aun con el 30% de recorte del ejemplo del anuncio, a mi volumen (~267 llamadas al mes) el job tardaría entre &lt;strong&gt;9 y 55 años&lt;/strong&gt; en pagarse.&lt;/li&gt;
    &lt;li&gt;El mismo prompt con la misma noticia mide &lt;strong&gt;1,621 tokens en Haiku 5.5, 1,132 en Haiku 4.5 y 917 en Nova 2 Lite&lt;/strong&gt;. El servicio lo cuenta como 600 en los tres.&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;qué-es-advanced-prompt-optimization-y-qué-agrega-shortenprompt&quot;&gt;Qué Es Advanced Prompt Optimization y Qué Agrega &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;shortenPrompt&lt;/code&gt;&lt;/h2&gt;

&lt;p&gt;Advanced Prompt Optimization es el optimizador completo de Bedrock, distinto del &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;OptimizePrompt&lt;/code&gt; simple. Le entregas un archivo JSONL con tus plantillas (variables con doble llave, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{{variable}}&lt;/code&gt;), hasta 100 muestras de evaluación por plantilla y un método de evaluación: el juez por defecto, criterios en texto libre (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;steeringCriteria&lt;/code&gt;), un LLM como juez con tu rúbrica, o un Lambda propio. El servicio corre un ciclo de inferencia, evaluación y reescritura sobre cada modelo objetivo y te devuelve un prompt optimizado por modelo. Un job acepta hasta 10 plantillas y 5 modelos, y la documentación habla de 15 a 20 minutos para un prompt con pocas muestras y de varias horas para muchas. Mis jobs tardaron 14 y 29 minutos.&lt;/p&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;shortenPrompt&lt;/code&gt; se activa &lt;strong&gt;por plantilla, dentro del JSONL&lt;/strong&gt;, no en la llamada a la API:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;version&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;bedrock-2026-05-14&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;templateId&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;news-classifier-shorten&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;promptTemplate&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;optimizationConfig&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;shortenPrompt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;customEvaluationMetricLabel&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;clasificacion_vs_produccion&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;evaluationMetricLambdaArn&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:lambda:us-east-1:&amp;lt;cuenta&amp;gt;:function:apo-news-classification-evaluator&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;evaluationSamples&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;...&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;La lógica de retorno es simple: el prompt acortado se devuelve &lt;strong&gt;solo si es más corto y puntúa al menos igual&lt;/strong&gt; que el original. Si falla cualquiera de las dos condiciones, recibes tu prompt original con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compressionRatio = 1.0&lt;/code&gt;. El ratio es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;optimizedTokenCount / originalTokenCount&lt;/code&gt;, medido sobre la plantilla y no sobre el prompt con las variables sustituidas.&lt;/p&gt;

&lt;p&gt;Sobre el costo, la documentación dice que &lt;strong&gt;no hay un cargo propio del servicio&lt;/strong&gt;: pagas los tokens que consume. La página de precios da la fórmula: unas &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;16 × N&lt;/code&gt; inferencias del modelo objetivo por plantilla, donde N es el número de muestras, más el optimizador (hoy Claude Sonnet 4.6) con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;101 × (3700 + 0.35 × P)&lt;/code&gt; tokens de entrada, donde P son los tokens de tu plantilla. Los tokens de salida del optimizador no tienen fórmula.&lt;/p&gt;

&lt;h2 id=&quot;el-experimento&quot;&gt;El Experimento&lt;/h2&gt;

&lt;h3 id=&quot;el-prompt-el-clasificador-de-mi-agente-de-noticias&quot;&gt;El prompt: el clasificador de mi agente de noticias&lt;/h3&gt;

&lt;p&gt;Mi agente procesa el RSS de AWS tres veces al día. Desde finales de septiembre el modelo ya no calcula la relevancia: solo &lt;strong&gt;clasifica&lt;/strong&gt; cada noticia en un tema (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;topic_tier&lt;/code&gt;) y un tipo de cambio (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;change_type&lt;/code&gt;), y una rúbrica con pesos editables calcula la nota de 0 a 10. Si la nota llega a 6 se genera un post; si llega a 7, la noticia entra al newsletter.&lt;/p&gt;

&lt;p&gt;Elegí este prompt por tres razones. Tiene una respuesta objetiva, así que se puede evaluar sin un juez subjetivo. Corre todos los días, así que tiene un volumen real contra el cual calcular el ahorro. Y ya era compacto, unos 1,900 caracteres: si el shortening encuentra algo que recortar aquí, lo encontrará en casi cualquier prompt. Un fragmento:&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;topic_tier: el tema al que pertenece el servicio o la capacidad (elige el más específico):
• genai_agentes: Bedrock, IA generativa, agentes, MCP, Amazon Quick, AgentCore, SageMaker AI
• serverless_core: Lambda, Step Functions, API Gateway, EventBridge, DynamoDB
...
change_type: qué tipo de cambio anuncia la noticia (juzga el cambio, no el servicio):
• nueva_capacidad: una función o servicio que antes no existía
• mejora: una mejora incremental de algo que ya existía (límites, rendimiento, integraciones)
...
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;la-referencia-lo-que-decidió-producción&quot;&gt;La referencia: lo que decidió producción&lt;/h3&gt;

&lt;p&gt;No etiqueté nada a mano. La referencia de cada noticia es la clasificación que hizo producción, guardada en DynamoDB: &lt;strong&gt;205 noticias&lt;/strong&gt; clasificadas entre el 30 de septiembre y el 22 de octubre de 2026. Partí el conjunto de forma determinística, por hash del ID: &lt;strong&gt;60 noticias para el optimizador y 145 de holdout&lt;/strong&gt; que nunca ve.&lt;/p&gt;

&lt;p&gt;Con esta referencia no mido si el prompt acortado acierta más, sino si se comporta igual que el actual. Para un acortamiento me parece la pregunta correcta: busco un prompt más barato que no rompa nada, es decir, una prueba de regresión. La desventaja es que si producción se equivocaba, el optimizador aprende a repetir el error.&lt;/p&gt;

&lt;h3 id=&quot;el-evaluador-un-lambda-determinístico&quot;&gt;El evaluador: un Lambda determinístico&lt;/h3&gt;

&lt;p&gt;Advanced Prompt Optimization ofrece cuatro formas de evaluar, y descarté tres. El juez por defecto califica exactitud, completitud y &lt;em&gt;Expression Quality&lt;/em&gt;, y este último criterio premia respuestas cortas, así que habría optimizado la brevedad de la salida en lugar de la clasificación. Los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;steeringCriteria&lt;/code&gt; son demasiado vagos para una tarea con respuesta exacta. Un LLM como juez agrega costo, porque el juez lee prompt, respuesta y referencia en cada evaluación, y suma su propio ruido a algo que se resuelve comparando dos valores.&lt;/p&gt;

&lt;p&gt;Me quedé con un Lambda. El contrato que exige el servicio es simple: recibes &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&quot;preds&quot;: [...], &quot;golds&quot;: [...]}&lt;/code&gt; y devuelves &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&quot;score&quot;: float, &quot;scores&quot;: [...]}&lt;/code&gt;, más alto es mejor. Mi regla: si la salida no es un JSON válido con todas las claves y valores permitidos, la muestra vale 0; si lo es, suma 0.5 por acertar el tema y 0.5 por acertar el tipo de cambio.&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;compute_score&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;preds&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;golds&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Contrato JSON obligatorio; 0.5 por topic_tier correcto y 0.5 por change_type correcto.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;scores&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;score_one&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;p&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;g&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;p&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;g&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;zip&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;preds&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;golds&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)]&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;score&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;sum&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;scores&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;scores&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;scores&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;0.0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;scores&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;scores&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El servicio lee el docstring como descripción de la métrica y revisa el código completo antes de usarlo. Esa revisión me costó el primer job; lo cuento en los gotchas.&lt;/p&gt;

&lt;h3 id=&quot;la-plantilla-qué-puede-tocar-el-optimizador-y-qué-no&quot;&gt;La plantilla: qué puede tocar el optimizador y qué no&lt;/h3&gt;

&lt;p&gt;En producción el prompt va como system, la noticia como mensaje de usuario, y la salida usa &lt;a href=&quot;/bedrock-structured-outputs.html&quot; target=&quot;_blank&quot;&gt;Structured Outputs&lt;/a&gt;. Advanced Prompt Optimization recibe una sola plantilla de texto y no acepta structured outputs, así que el contrato JSON tiene que vivir dentro del prompt. Lo protegí con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;advpo:exclude&amp;gt;&lt;/code&gt;: el optimizador puede reescribir las instrucciones de clasificación, pero no la noticia ni el formato de salida.&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&amp;lt;advpo:exclude&amp;gt;Noticia a clasificar:
Título: {{title}}
Descripción: {{description}}

Responde ÚNICAMENTE con un objeto JSON, sin texto antes ni después, con exactamente estas claves:
change_type, topic_tier, topic, reason, keyPoints (lista de textos) y emojis (lista de textos).
En topic_tier y change_type usa solo las claves listadas arriba.&amp;lt;/advpo:exclude&amp;gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;En el mismo job puse dos copias idénticas de la plantilla, una optimizada solo por calidad (el comportamiento por defecto) y otra con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;shortenPrompt: true&lt;/code&gt;, para compararlas en las mismas condiciones.&lt;/p&gt;

&lt;h3 id=&quot;tres-modelos-y-dos-cuentas&quot;&gt;Tres modelos y dos cuentas&lt;/h3&gt;

&lt;p&gt;Esta parte del diseño cambió sobre la marcha. Desde el 8 de octubre, mi agente consume Claude Haiku 5.5 por la API de Anthropic, no por Bedrock. Advanced Prompt Optimization solo optimiza modelos de Bedrock, y mi cuenta de trabajo no puede invocar Haiku 5.5 en Bedrock. La cuenta que sí puede no tenía enviado el formulario de casos de uso de Anthropic, así que ahí no corría Haiku 4.5.&lt;/p&gt;

&lt;p&gt;Terminé corriendo un job por cuenta, con los mismos datos y el mismo evaluador: &lt;strong&gt;Claude Haiku 5.5&lt;/strong&gt; (el modelo de producción) en una, y &lt;strong&gt;Claude Haiku 4.5&lt;/strong&gt; (el de producción hasta el 8 de octubre) más &lt;strong&gt;Amazon Nova 2 Lite&lt;/strong&gt; en la otra. Nova es el modelo que dejé en marzo porque no soportaba structured outputs; como Advanced Prompt Optimization trabaja con texto plano, aquí esa limitación no importa. Ese mismo formulario faltante terminó afectando también el job de Haiku 5.5, como explico en el Hallazgo 3.&lt;/p&gt;

&lt;h3 id=&quot;hipótesis-escritas-antes-de-ver-resultados&quot;&gt;Hipótesis, escritas antes de ver resultados&lt;/h3&gt;

&lt;p&gt;Seguí el mismo método de los artículos anteriores: antes de leer el resultado de los jobs escribí cada hipótesis con el criterio que la refutaría.&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;H1 — El shortening encuentra algo que recortar.&lt;/strong&gt; Al menos un modelo devuelve &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compressionRatio &amp;lt; 0.9&lt;/code&gt;. Se refuta si los tres devuelven 1.0 o un ratio mayor a 0.9.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;H2 — El prompt acortado se comporta igual en el holdout.&lt;/strong&gt; La diferencia de score contra el original, en el mismo modelo, queda dentro del piso de ruido. Se refuta si cae por debajo de ese piso.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;H3 — A mi volumen, el ahorro no paga el job.&lt;/strong&gt; Con ~267 llamadas al mes, el ahorro mensual no cubre el costo del job en menos de 12 meses en ningún modelo. Se refuta si algún modelo recupera el costo en un año o menos.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;H4 — Los prompts optimizados no son portables.&lt;/strong&gt; El prompt optimizado para un modelo pierde más que el piso de ruido al correrlo en otro. Se refuta si rinden igual en los tres modelos.&lt;/li&gt;
&lt;/ol&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;📋 &lt;strong&gt;Desviaciones registradas&lt;/strong&gt;: (1) el diseño original usaba solo Nova 2 Lite, porque Haiku 5.5 no estaba disponible en Bedrock en mi cuenta de trabajo; (2) pasé a tres modelos repartidos en dos cuentas; (3) el job corre Haiku 5.5 con su configuración por defecto, que piensa, distinta de la de producción (ver gotchas); (4) los dos primeros jobs fallaron por el validador de código del Lambda; (5) detuve un job con el evaluador viejo, y su ventana se cruza unos minutos con el job bueno de esa cuenta, lo que infla un poco los costos medidos ahí; (6) mi línea base del holdout corrió en paralelo con el job de Haiku 4.5.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Todo el código está en &lt;a href=&quot;https://github.com/codecr/bedrock-prompt-shortening&quot; target=&quot;_blank&quot;&gt;github.com/codecr/bedrock-prompt-shortening&lt;/a&gt;: scripts numerados del 01 al 07, el evaluador y el cleanup.&lt;/p&gt;

&lt;h2 id=&quot;línea-base-cuánto-difiere-el-prompt-de-sí-mismo&quot;&gt;Línea Base: Cuánto Difiere el Prompt de Sí Mismo&lt;/h2&gt;

&lt;p&gt;Antes de mirar ningún prompt optimizado corrí el original sobre las 145 noticias del holdout, dos veces en cada modelo. La segunda corrida es importante porque el modelo no es determinístico: si dos variantes difieren menos de lo que el prompt original difiere de sí mismo, esa diferencia no significa nada. Haiku 5.5 corrió como en producción, sin thinking y con esfuerzo bajo.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Modelo&lt;/th&gt;
      &lt;th&gt;Score vs producción&lt;/th&gt;
      &lt;th&gt;Contrato JSON&lt;/th&gt;
      &lt;th&gt;Coincide consigo mismo&lt;/th&gt;
      &lt;th&gt;Tokens in / out&lt;/th&gt;
      &lt;th&gt;TTFT mediana&lt;/th&gt;
      &lt;th&gt;Costo por 1,000 llamadas&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Haiku 5.5&lt;/td&gt;
      &lt;td&gt;0.848&lt;/td&gt;
      &lt;td&gt;100%&lt;/td&gt;
      &lt;td&gt;133/145 (91.7%)&lt;/td&gt;
      &lt;td&gt;1,621 / 334&lt;/td&gt;
      &lt;td&gt;1.11 s&lt;/td&gt;
      &lt;td&gt;$0.36&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Haiku 4.5&lt;/td&gt;
      &lt;td&gt;0.840&lt;/td&gt;
      &lt;td&gt;100%&lt;/td&gt;
      &lt;td&gt;128/145 (88.3%)&lt;/td&gt;
      &lt;td&gt;1,132 / 284&lt;/td&gt;
      &lt;td&gt;0.66 s&lt;/td&gt;
      &lt;td&gt;$2.81&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Amazon Nova 2 Lite&lt;/td&gt;
      &lt;td&gt;0.760&lt;/td&gt;
      &lt;td&gt;100%&lt;/td&gt;
      &lt;td&gt;140/145 (96.6%)&lt;/td&gt;
      &lt;td&gt;917 / 191&lt;/td&gt;
      &lt;td&gt;0.47 s&lt;/td&gt;
      &lt;td&gt;$0.83&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Nova es el más estable y el que menos coincide con producción: repite su respuesta el 96.6% de las veces, pero ser consistente no lo hace más exacto. Haiku 5.5 no llega a 1.0 ni contra referencias que en su mayoría generó él mismo, porque en producción corre con system prompt separado y structured outputs, y cambiar la forma de llamar al modelo ya mueve el resultado. Y el piso de ruido es alto: el mismo prompt cambia la clasificación de entre 5 y 17 noticias de 145 entre una corrida y otra. Una mejora menor que eso no se distingue del azar.&lt;/p&gt;

&lt;p&gt;Un dato de negocio: con la rúbrica activa, la clasificación de Haiku 5.5 cambia la decisión de generar un post en 10 de las 145 noticias respecto de lo que decidió producción. Ese margen de error ya existe hoy en mi pipeline, y no lo había medido.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔢 &lt;strong&gt;ProTip #1&lt;/strong&gt;: El mismo texto no mide lo mismo en todos los modelos. Mi prompt con la misma noticia son 1,621 tokens en Haiku 5.5 contra 1,132 en Haiku 4.5: un 43% más. Antes de calcular cuánto te ahorra recortar un prompt, mide sus tokens &lt;strong&gt;en el modelo donde va a correr&lt;/strong&gt;. Y no uses el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;originalTokenCount&lt;/code&gt; del job para eso: el servicio contó mi plantilla como 600 tokens en los tres modelos, con un conteo propio que no es el del tokenizador que te cobra.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-1-seis-optimizaciones-cero-cambios&quot;&gt;Hallazgo 1: Seis Optimizaciones, Cero Cambios&lt;/h2&gt;

&lt;p&gt;Este es el resultado completo de los dos jobs. «Idéntico» significa idéntico carácter por carácter al original, una vez quitadas las etiquetas &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;advpo:exclude&amp;gt;&lt;/code&gt;, que el servicio siempre elimina.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Modelo&lt;/th&gt;
      &lt;th&gt;Plantilla&lt;/th&gt;
      &lt;th&gt;Score original → “optimizado”&lt;/th&gt;
      &lt;th&gt;compressionRatio&lt;/th&gt;
      &lt;th&gt;Inferencias fallidas (orig / opt)&lt;/th&gt;
      &lt;th&gt;¿Cambió el prompt?&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Haiku 5.5&lt;/td&gt;
      &lt;td&gt;calidad&lt;/td&gt;
      &lt;td&gt;0.808 → 0.850&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;0 / 0&lt;/td&gt;
      &lt;td&gt;No&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Haiku 5.5&lt;/td&gt;
      &lt;td&gt;shorten&lt;/td&gt;
      &lt;td&gt;0.825 → 0.825&lt;/td&gt;
      &lt;td&gt;1.0&lt;/td&gt;
      &lt;td&gt;0 / 0&lt;/td&gt;
      &lt;td&gt;No&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Haiku 4.5&lt;/td&gt;
      &lt;td&gt;calidad&lt;/td&gt;
      &lt;td&gt;0.575 → 0.833&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;12 / 0&lt;/td&gt;
      &lt;td&gt;No&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Haiku 4.5&lt;/td&gt;
      &lt;td&gt;shorten&lt;/td&gt;
      &lt;td&gt;0.625 → 0.625&lt;/td&gt;
      &lt;td&gt;1.0&lt;/td&gt;
      &lt;td&gt;13 / 13&lt;/td&gt;
      &lt;td&gt;No&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Nova 2 Lite&lt;/td&gt;
      &lt;td&gt;calidad&lt;/td&gt;
      &lt;td&gt;0.708 → 0.708&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;1 / 1&lt;/td&gt;
      &lt;td&gt;No&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Nova 2 Lite&lt;/td&gt;
      &lt;td&gt;shorten&lt;/td&gt;
      &lt;td&gt;0.708 → 0.708&lt;/td&gt;
      &lt;td&gt;1.0&lt;/td&gt;
      &lt;td&gt;0 / 0&lt;/td&gt;
      &lt;td&gt;No&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;H1 queda refutada: ningún modelo devolvió un ratio menor a 1.0. Pero de las seis filas, solo las dos de Nova son un resultado limpio.&lt;/p&gt;

&lt;p&gt;En Nova 2 Lite el optimizador trabajó, el modelo respondió casi todas las inferencias y el servicio no encontró un prompt mejor ni uno más corto que puntuara igual. Para un prompt que ya era compacto, evaluado con un criterio estricto, es una respuesta razonable: no había nada que recortar sin perder calidad. Cuando devuelve el original, el servicio copia la medición del original en las métricas «optimizadas», y por eso las dos columnas son iguales hasta el último decimal.&lt;/p&gt;

&lt;p&gt;Haiku 4.5 y Haiku 5.5 no son casos limpios, por dos razones distintas que el resultado del job no menciona.&lt;/p&gt;

&lt;h2 id=&quot;hallazgo-2-el-45-que-no-existió&quot;&gt;Hallazgo 2: El +45% que No Existió&lt;/h2&gt;

&lt;p&gt;Volvamos a la tercera fila. Para Haiku 4.5, optimizando solo por calidad, el resumen del job reporta que el score subió de &lt;strong&gt;0.575 a 0.833&lt;/strong&gt;, un 45%, y el tiempo promedio hasta el primer token bajó de 1.12 s a 0.60 s. El prompt “optimizado” es idéntico al original.&lt;/p&gt;

&lt;p&gt;Revisé el archivo de resultados muestra por muestra. Del lado original, &lt;strong&gt;12 de las 60 inferencias volvieron vacías&lt;/strong&gt;: respuesta en blanco, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;inputTokens: 0&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;outputTokens: 0&lt;/code&gt;, latencia cero. El evaluador recibió un texto vacío, que no es un JSON válido, y lo puntuó 0. Del lado «optimizado» no falló ninguna. La mejora sale completa de esas 12 llamadas fallidas.&lt;/p&gt;

&lt;p&gt;Las métricas de Bedrock en CloudWatch muestran qué pasó: en la ventana del job, Haiku 4.5 registró &lt;strong&gt;607 errores de servidor&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvocationServerErrors&lt;/code&gt;). Una parte puede ser mía: mi línea base del holdout corrió 230 llamadas contra el mismo modelo en paralelo, y mi cliente reintentaba los 5xx. Pero las 25 inferencias vacías del job son del job. La cuota no fue el problema: Haiku 4.5 tiene 10,000 solicitudes por minuto en esa cuenta.&lt;/p&gt;

&lt;p&gt;En esa misma fila hay otro detalle. Aun excluyendo las 12 fallidas, el original saca 0.719 contra 0.833 para el mismo texto en el mismo job. Es el mismo piso de ruido de la línea base, ahora dentro del job: con 60 muestras y un modelo que coincide consigo mismo el 88% de las veces, dos mediciones del mismo prompt difieren por más de 10 puntos.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #2&lt;/strong&gt;: No le creas al &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;averageScore&lt;/code&gt; del resumen. Antes de aceptar un prompt optimizado, haz dos cosas que el servicio no hace por ti: compara el texto del prompt contra el original (en mis seis casos era idéntico), y cuenta en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;dataset[]&lt;/code&gt; cuántas muestras tienen &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;outputTokens: 0&lt;/code&gt;. Una inferencia fallida entra al promedio como un 0.0 más, y en mi caso produjo una mejora de 45% sobre un prompt que no cambió. El script &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;05_fetch_results.py&lt;/code&gt; del repo hace las dos verificaciones.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-3-success-sin-optimizador&quot;&gt;Hallazgo 3: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SUCCESS&lt;/code&gt; Sin Optimizador&lt;/h2&gt;

&lt;p&gt;El job de Haiku 5.5 terminó en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Completed&lt;/code&gt;, con las dos entradas en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SUCCESS&lt;/code&gt;, sin errores en el archivo de resultados y con un +5% de mejora en la plantilla de calidad (0.808 → 0.850) para, otra vez, un prompt idéntico al original. Ese +5% es del tamaño de lo que el mismo prompt varía consigo mismo: en mi línea base, Haiku 5.5 cambió la clasificación de 12 de 145 noticias entre dos corridas. Por sí solo no dice nada. El problema estaba en las métricas del optimizador.&lt;/p&gt;

&lt;p&gt;Haiku 5.5 hizo 1,925 inferencias en la ventana del job. La fórmula de precios predice &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;16 × 60 × 2 = 1,920&lt;/code&gt;: el modelo objetivo trabajó exactamente lo esperado. Pero el optimizador, Claude Sonnet 4.6, registró &lt;strong&gt;689 invocaciones y 684 errores de cliente&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvocationClientErrors&lt;/code&gt;), con apenas 7,756 tokens de entrada en total. En la otra cuenta, el mismo optimizador consumió 2.49 millones de tokens.&lt;/p&gt;

&lt;p&gt;La causa la encontré invocando Sonnet 4.6 a mano en esa cuenta: &lt;em&gt;“Model use case details have not been submitted for this account”&lt;/em&gt;. Es el mismo formulario de Anthropic que me impedía usar Haiku 4.5 ahí. El optimizador corre con &lt;strong&gt;mis&lt;/strong&gt; credenciales, no con un rol del servicio, y mi cuenta no podía invocarlo. El job no lo detectó al crearse ni lo reportó en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;failureMessage&lt;/code&gt; o en las entradas del resultado. Evaluó el prompt original, no pudo generar candidatos y me lo devolvió con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SUCCESS&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Este tipo de falla es difícil de detectar porque el resultado se ve normal. Si no hubiera revisado CloudWatch para calcular costos, habría escrito que Haiku 5.5 no encontró nada que recortar.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #3&lt;/strong&gt;: Advanced Prompt Optimization no usa un rol de servicio: invoca los modelos objetivo, &lt;strong&gt;el optimizador&lt;/strong&gt; y tu Lambda con las credenciales de quien crea el job (Forward Access Session). Antes de lanzar un job, verifica que tu cuenta pueda invocar Claude Sonnet 4.6 con una llamada de prueba. El servicio valida al crear el job que puedas invocar los modelos objetivo (&lt;em&gt;“No inference API is accessible for model”&lt;/em&gt;), pero no valida el optimizador. Y después de cada job, revisa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvocationClientErrors&lt;/code&gt; de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us.anthropic.claude-sonnet-4-6&lt;/code&gt; en las métricas de Bedrock de CloudWatch.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-4-habría-valido-la-pena&quot;&gt;Hallazgo 4: ¿Habría Valido la Pena?&lt;/h2&gt;

&lt;p&gt;Ningún prompt cambió, así que no hay ahorro medido. Aun así, la pregunta original se puede responder con los costos reales de los jobs, suponiendo que el shortening hubiera logrado lo del ejemplo del anuncio: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compressionRatio = 0.7&lt;/code&gt;, un 30% menos de tokens en la plantilla.&lt;/p&gt;

&lt;p&gt;Según CloudWatch, los jobs consumieron:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Modelo&lt;/th&gt;
      &lt;th&gt;Rol en el job&lt;/th&gt;
      &lt;th&gt;Invocaciones&lt;/th&gt;
      &lt;th&gt;Tokens in / out&lt;/th&gt;
      &lt;th&gt;Costo&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Sonnet 4.6&lt;/td&gt;
      &lt;td&gt;Optimizador (4 pares)&lt;/td&gt;
      &lt;td&gt;384&lt;/td&gt;
      &lt;td&gt;2,488,824 / 262,585&lt;/td&gt;
      &lt;td&gt;$12.55&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Haiku 4.5&lt;/td&gt;
      &lt;td&gt;Objetivo&lt;/td&gt;
      &lt;td&gt;3,396&lt;/td&gt;
      &lt;td&gt;3,152,146 / 766,911&lt;/td&gt;
      &lt;td&gt;$7.69&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Amazon Nova 2 Lite&lt;/td&gt;
      &lt;td&gt;Objetivo&lt;/td&gt;
      &lt;td&gt;2,811&lt;/td&gt;
      &lt;td&gt;2,673,178 / 553,897&lt;/td&gt;
      &lt;td&gt;$2.41&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Haiku 5.5&lt;/td&gt;
      &lt;td&gt;Objetivo&lt;/td&gt;
      &lt;td&gt;1,925&lt;/td&gt;
      &lt;td&gt;3,107,401 / 1,021,435&lt;/td&gt;
      &lt;td&gt;$0.90&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Sonnet 4.6&lt;/td&gt;
      &lt;td&gt;Optimizador fallido (2 pares)&lt;/td&gt;
      &lt;td&gt;689&lt;/td&gt;
      &lt;td&gt;7,756 / 2,733&lt;/td&gt;
      &lt;td&gt;$0.07&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Total: &lt;strong&gt;$23.61&lt;/strong&gt;, más alrededor de $1.40 de la validación en el holdout. Las cifras de Haiku 4.5 y Nova incluyen unos minutos del job que detuve, así que un job limpio sale algo más barato. El optimizador es la parte más cara: unos $3.14 por cada par plantilla-modelo.&lt;/p&gt;

&lt;p&gt;Con esos datos calculé el costo de optimizar una plantilla para un modelo y lo que ahorraría al mes a mi volumen real (205 noticias en 23 días, unas 267 llamadas al mes), con el 30% de recorte sobre los 600 tokens de la plantilla:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Modelo&lt;/th&gt;
      &lt;th&gt;Costo del job (1 plantilla)&lt;/th&gt;
      &lt;th&gt;Ahorro al mes&lt;/th&gt;
      &lt;th&gt;Se paga en&lt;/th&gt;
      &lt;th&gt;Llamadas al mes para pagarlo en un mes&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Haiku 5.5&lt;/td&gt;
      &lt;td&gt;$3.48&lt;/td&gt;
      &lt;td&gt;$0.0053&lt;/td&gt;
      &lt;td&gt;55 años&lt;/td&gt;
      &lt;td&gt;175,955&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Claude Haiku 4.5&lt;/td&gt;
      &lt;td&gt;$5.83&lt;/td&gt;
      &lt;td&gt;$0.0529&lt;/td&gt;
      &lt;td&gt;9 años&lt;/td&gt;
      &lt;td&gt;29,453&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Amazon Nova 2 Lite&lt;/td&gt;
      &lt;td&gt;$3.93&lt;/td&gt;
      &lt;td&gt;$0.0159&lt;/td&gt;
      &lt;td&gt;21 años&lt;/td&gt;
      &lt;td&gt;66,168&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;!-- Fuente: 07_report.py, bloque &quot;Hipotético ratio 0.7&quot;. Precios regionales us-east-1 por millón de tokens, verificados con la AWS Price List API el 2026-10-22: Haiku 5.5 $0.11/$0.55, Haiku 4.5 $1.10/$5.50, Nova 2 Lite $0.33/$2.75, Sonnet 4.6 $3.30/$16.50. --&gt;

&lt;p&gt;H3 se confirma con mucho margen. La tabla muestra además que acortar rinde más en el modelo más caro: Haiku 4.5 cuesta 10 veces más por token de entrada que Haiku 5.5 en Bedrock. En el modelo de producción, que es el más barato, acortar importa menos. Mi tabla subestima un poco el ahorro en Haiku 5.5, porque calcula sobre los 600 tokens que cuenta el servicio y no sobre los que cobra su tokenizador; aun corrigiendo eso, el orden de magnitud no cambia.&lt;/p&gt;

&lt;p&gt;Esto no significa que el shortening no sirva, sino que la cuenta depende más del volumen que del porcentaje de recorte. Con unas 30,000 llamadas al mes en Haiku 4.5, o unas 176,000 en Haiku 5.5, el job se paga en un mes. Con 267, no se paga.&lt;/p&gt;

&lt;p&gt;Sobre la latencia, el otro beneficio que menciona el anuncio, no tengo nada que medir: sin un prompt más corto no hay diferencia de TTFT. La mejora que muestra el resumen del job (1.12 s → 0.60 s en Haiku 4.5) son dos mediciones del mismo texto, tomadas mientras el modelo devolvía errores de servidor; no se las atribuyo al prompt.&lt;/p&gt;

&lt;h2 id=&quot;lo-que-la-documentación-no-te-dice&quot;&gt;Lo que la Documentación No Te Dice&lt;/h2&gt;

&lt;p&gt;Además de los hallazgos anteriores, estos son los gotchas que me costaron un job o un buen rato.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🧪 &lt;strong&gt;ProTip #4&lt;/strong&gt;: En &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;modelConfigurations&lt;/code&gt;, el campo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;additionalModelRequestFields&lt;/code&gt; solo acepta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;topK&lt;/code&gt;. Intenté pasar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;thinking: disabled&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;output_config.effort: low&lt;/code&gt; para Haiku 5.5, como lo corro en producción, y el job se rechazó al crearse: &lt;em&gt;“contains unsupported keys: [output_config, thinking]. Supported keys: [topK]”&lt;/em&gt;. El optimizador ajusta el prompt para Haiku 5.5 con su configuración por defecto, que usa thinking: en una muestra de 12 noticias eso fue un 57% más de tokens de salida y 0.75 s más de latencia que la configuración de producción, con el mismo score. En la práctica optimizas para una configuración distinta de la que vas a correr.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🛑 &lt;strong&gt;ProTip #5&lt;/strong&gt;: El servicio revisa el código de tu Lambda evaluador antes de usarlo, y lo rechaza si encuentra algo que considera peligroso. Mi primer job falló con &lt;em&gt;“Metric code validation failed: Uses potentially dangerous builtin: compile()”&lt;/em&gt; por un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;re.compile()&lt;/code&gt;: el análisis no distingue el método de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;re&lt;/code&gt; del builtin &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compile&lt;/code&gt;. Usa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;re.match(patron, texto)&lt;/code&gt; directamente. El job tampoco falla al crearse: falla unos tres minutos después, con un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;failureMessage&lt;/code&gt; genérico que te manda al archivo de resultados en S3, donde está el motivo real por entrada.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⏱️ &lt;strong&gt;ProTip #6&lt;/strong&gt;: Los estados terminales de un job son &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Completed&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Failed&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Stopped&lt;/code&gt; &lt;strong&gt;y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PartiallyCompleted&lt;/code&gt;&lt;/strong&gt;. El loop de espera del sample oficial solo considera los tres primeros, así que con un resultado parcial se queda esperando para siempre.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;También encontré algunas diferencias entre la guía de usuario y la API real:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;La operación de borrado es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BatchDeleteAdvancedPromptOptimizationJob&lt;/code&gt;, en singular (la guía usa el plural), y devuelve &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;advancedPromptOptimizationJobs[]&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;errors[]&lt;/code&gt;.&lt;/li&gt;
  &lt;li&gt;La respuesta de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ListAdvancedPromptOptimizationJobs&lt;/code&gt; usa la clave &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;jobSummaries&lt;/code&gt;, no la que muestra el ejemplo de la guía.&lt;/li&gt;
  &lt;li&gt;El parámetro de cifrado se llama &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;encryptionKeyArn&lt;/code&gt;, no &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;encryptionConfig&lt;/code&gt;.&lt;/li&gt;
  &lt;li&gt;La página de evaluación pide una resource-based policy para que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock.amazonaws.com&lt;/code&gt; invoque tu Lambda; la de prerrequisitos dice que el servicio lo invoca con tus credenciales. Yo configuré las dos cosas.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;veredicto-de-las-hipótesis&quot;&gt;Veredicto de las Hipótesis&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Hipótesis&lt;/th&gt;
      &lt;th&gt;Resultado&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;H1 — El shortening encuentra algo que recortar&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Refutada.&lt;/strong&gt; &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compressionRatio = 1.0&lt;/code&gt; en los tres modelos. El único resultado limpio, Nova 2 Lite, devolvió el original.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H2 — El prompt acortado se comporta igual en el holdout&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;No se pudo probar.&lt;/strong&gt; No hubo prompt acortado.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H3 — A mi volumen, el ahorro no paga el job&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Confirmada.&lt;/strong&gt; Ni siquiera con un 30% de recorte hipotético: entre 9 y 55 años.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H4 — Los prompts optimizados no son portables&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;No se pudo probar.&lt;/strong&gt; Los seis prompts “optimizados” son el original.&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Dos de las cuatro hipótesis quedaron sin probar. La matriz de portabilidad que tenía preparada no tenía sentido con seis prompts iguales, así que no la corrí.&lt;/p&gt;

&lt;h2 id=&quot;límites-del-experimento&quot;&gt;Límites del Experimento&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Una plantilla, un dominio.&lt;/strong&gt; Mi prompt ya era compacto y la tarea tiene respuesta exacta. Con un prompt largo y redundante, el shortening probablemente sí recortaría. No corrí ese control positivo, así que no puedo separar «el servicio no recorta» de «mi prompt no tenía nada que recortar». El caso de Nova sugiere lo segundo.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;La referencia es producción, no la verdad.&lt;/strong&gt; Mido regresión, no exactitud.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;60 muestras y un solo job por modelo.&lt;/strong&gt; No sé cuánto varía el optimizador entre corridas del mismo job.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Haiku 5.5 se optimizó con una configuración distinta a la de producción&lt;/strong&gt;, y su job no tuvo optimizador funcional. Ese resultado no cuenta.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Haiku 4.5 tuvo errores de servidor&lt;/strong&gt; durante el job, y mi propia línea base corría en paralelo contra el mismo modelo.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Producción no corre en Bedrock&lt;/strong&gt; sino en la API de Anthropic, así que aunque el prompt hubiera cambiado, llevarlo a producción habría sido otro experimento.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;La decisión humana no sirve como segunda referencia&lt;/strong&gt;: de las noticias del dataset con post, 133 fueron aprobados y solo 3 rechazados.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;Volvamos a la pregunta del inicio: ¿cuánto me ahorra acortar un prompt que ya funciona?&lt;/p&gt;

&lt;p&gt;En mi caso, nada, por dos razones. Mi prompt ya era compacto, y el único resultado limpio del experimento devolvió el original. Y aun si lo hubiera recortado un 30%, a 267 llamadas al mes el ahorro sería de centavos por año contra un job de varios dólares. Acortar prompts es una optimización de volumen, y conviene hacer la cuenta antes de lanzar el job: tokens ahorrados por llamada, por llamadas al mes, por precio por token, contra unos $3 a $6 por plantilla y modelo.&lt;/p&gt;

&lt;p&gt;Lo que más me sirvió del ejercicio fue ver cómo reporta el servicio. En un día obtuve un +45% de mejora que salió de inferencias fallidas contadas como cero, y un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SUCCESS&lt;/code&gt; de un job cuyo optimizador nunca pudo ejecutarse. Ninguno de los dos casos aparece en el resultado del job. Los encontré comparando el texto del prompt devuelto y revisando las métricas de error de CloudWatch.&lt;/p&gt;

&lt;p&gt;Me pasó algo parecido con el &lt;a href=&quot;/agentcore-optimization-loop.html&quot; target=&quot;_blank&quot;&gt;A/B test del Optimization Loop&lt;/a&gt;: el número que reporta un optimizador hay que verificarlo por fuera antes de tomar una decisión con él.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚀 &lt;strong&gt;ProTip Final&lt;/strong&gt;: Antes de optimizar un prompt por costo, calcula el punto de equilibrio con tu volumen real y el precio del modelo donde corre. Si no se paga en un año, no tiene sentido correrlo por costo; córrelo solo si tienes un problema de calidad que resolver. Y si lo corres, revisa tres cosas antes de aceptar el resultado: si el texto cambió, cuántas inferencias volvieron vacías y si el optimizador registró errores en CloudWatch.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;p&gt;¿Ya mediste cuántas llamadas al mes hacen tus prompts de producción? ¿Tu volumen está en la escala donde esta cuenta sí importa? Si alguien está viendo ahorros reales con el shortening, me interesa mucho saber con qué volumen — los comentarios están abiertos.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/10/bedrock-prompt-optimization-shortening/&quot; target=&quot;_blank&quot;&gt;Anuncio: Advanced Prompt Optimization now supports prompt shortening (20 de octubre de 2026)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-shorten.html&quot; target=&quot;_blank&quot;&gt;Shorten prompts&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-how.html&quot; target=&quot;_blank&quot;&gt;How Advanced Prompt Optimization works&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-input.html&quot; target=&quot;_blank&quot;&gt;Prepare your input dataset&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-evaluation.html&quot; target=&quot;_blank&quot;&gt;Define evaluation methods (incluye el contrato del Lambda evaluador)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-selective.html&quot; target=&quot;_blank&quot;&gt;Selective optimization: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;advpo:optimize&amp;gt;&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;advpo:exclude&amp;gt;&lt;/code&gt;&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-jobs.html&quot; target=&quot;_blank&quot;&gt;Create and manage optimization jobs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-results.html&quot; target=&quot;_blank&quot;&gt;View and interpret results&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-prereqs.html&quot; target=&quot;_blank&quot;&gt;Prerequisites (permisos y Forward Access Session)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/advanced-prompt-optimization-quotas.html&quot; target=&quot;_blank&quot;&gt;Quotas&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/APIReference/API_CreateAdvancedPromptOptimizationJob.html&quot; target=&quot;_blank&quot;&gt;API Reference: CreateAdvancedPromptOptimizationJob&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/bedrock/pricing/&quot; target=&quot;_blank&quot;&gt;Amazon Bedrock pricing (fórmula del Advanced Prompt Optimizer)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://github.com/aws-samples/amazon-bedrock-samples/tree/main/advanced-prompt-optimization&quot; target=&quot;_blank&quot;&gt;Sample oficial: aws-samples/amazon-bedrock-samples, advanced-prompt-optimization&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Mon, 26 Oct 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/bedrock-prompt-shortening.html</link>
                <guid isPermaLink="true">https://gerardo.dev/bedrock-prompt-shortening.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>Prompt Optimization</category>
                
                <category>Claude</category>
                
                <category>Nova</category>
                
                <category>GenAI</category>
                
                <category>LLM</category>
                
                
            </item>
        
            <item>
                <title>Temporal Policies en AgentCore: 98 despliegues denegados y un 409 que nunca llegó</title>
                <description>&lt;p&gt;Le pedí a un agente Strands algo razonable: «ejecuta las pruebas y despliega». Emitió &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; en el mismo turno, y el Gateway rechazó el despliegue. Repetí la tarea en diez sesiones y obtuve diez rechazos.&lt;/p&gt;

&lt;p&gt;La política que lo bloqueó decía exactamente eso: «permite &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; solo si hubo un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; completado en los últimos cinco minutos». Cuando el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; llegó al Gateway, las pruebas todavía estaban corriendo. La política hizo su trabajo; el que no esperó fue el agente.&lt;/p&gt;

&lt;p&gt;Las Temporal Policies de &lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;AgentCore Policy&lt;/a&gt; permiten escribir reglas que dependen de lo que el agente hizo antes en la sesión y que se aplican en el Gateway, fuera del código del agente. La documentación cubre bien el caso feliz: secuencias obligatorias, límites por sesión, ventanas de tiempo. Lo que no cubre es qué pasa cuando el agente paraleliza, cuando una solicitud se deniega o cuando despliegas una política nueva con conversaciones vivas. Para averiguarlo armé un Gateway con herramientas simuladas, escribí las hipótesis antes de ejecutar nada y lancé 5,294 llamadas contra él.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;&lt;strong&gt;📌 TL;DR — Lo que encontré&lt;/strong&gt;&lt;/p&gt;

  &lt;ul&gt;
    &lt;li&gt;Con llamadas en paralelo, el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; dependiente se denegó &lt;strong&gt;98 de 100&lt;/strong&gt; veces. En secuencia, &lt;strong&gt;0 de 600&lt;/strong&gt;, incluso sin retardo agregado. Un agente Strands paralelizó en las 10 sesiones.&lt;/li&gt;
    &lt;li&gt;Las solicitudes &lt;strong&gt;denegadas&lt;/strong&gt; también consumen el presupuesto de un límite basado en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::request&lt;/code&gt;: 40 de 40 pruebas.&lt;/li&gt;
    &lt;li&gt;Una sesión obsoleta llega como &lt;strong&gt;HTTP 200 con código JSON-RPC &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32005&lt;/code&gt;&lt;/strong&gt;, no como el 409 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ConflictException&lt;/code&gt; que menciona la documentación.&lt;/li&gt;
    &lt;li&gt;Solo los cambios en políticas &lt;strong&gt;temporales&lt;/strong&gt; invalidan sesiones vivas. Las políticas Cedar sin estado y el cambio de modo del Gateway no las tocan.&lt;/li&gt;
    &lt;li&gt;La validación por defecto rechaza el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; simple que pide la documentación, y también un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt; creado antes que su &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt;.&lt;/li&gt;
    &lt;li&gt;Evaluar la parte temporal cuesta &lt;strong&gt;entre 20 y 27 ms&lt;/strong&gt; con hasta ~1,000 llamadas de historial.&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

&lt;p&gt;Si no leíste el artículo de AgentCore Policy, ahí explico el modelo default-deny y Cedar. Aquí asumo que ya lo conoces.&lt;/p&gt;

&lt;h2 id=&quot;qué-son-las-temporal-policies&quot;&gt;Qué Son las Temporal Policies&lt;/h2&gt;

&lt;p&gt;Una política Cedar normal no tiene estado: decide mirando solo la solicitud actual. Una Temporal Policy le agrega memoria de la sesión. Se escribe en Dogwood, un lenguaje de políticas de código abierto compatible con Cedar (todo Cedar válido es Dogwood válido), y sus condiciones van en un bloque &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;when temporal { ... }&lt;/code&gt; con operadores como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly within&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;since within&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sum&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Para que esto funcione hacen falta dos piezas. La primera es la &lt;strong&gt;sesión de política&lt;/strong&gt;: el identificador lo generas tú y lo envías en el header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;x-amzn-bedrock-agentcore-policy-session-id&lt;/code&gt; desde la primera solicitud. El Gateway no lo genera; lo asocia a la identidad autenticada del llamador y lo expira después de 24 horas sin actividad. La segunda es el &lt;strong&gt;evento&lt;/strong&gt;. Cada acción produce hasta tres tipos —&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;request&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt; (solo si la herramienta terminó con éxito) y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;error&lt;/code&gt;— y los predicados temporales buscan eventos de esos tipos dentro de una ventana de tiempo.&lt;/p&gt;

&lt;p&gt;Esta es la política de secuencia que usé:&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;permit (
    principal,
    action == AgentCore::Action::&quot;ToolsTarget___deploy&quot;,
    resource == AgentCore::Gateway::&quot;&amp;lt;ARN-DEL-GATEWAY&amp;gt;&quot;
)
when temporal {
    formerly within 5m AgentCore::Action::&quot;ToolsTarget___run_tests&quot;::response{
        eventResource: resource
    }
};
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; se permite si en los últimos cinco minutos hubo una respuesta de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt;. Para que esa respuesta quede en el historial, la documentación pide además un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; sin condiciones para &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt;, porque una acción solo se registra como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt; si alguna política la permitió. Ese &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; simple reaparece en el Hallazgo 4.&lt;/p&gt;

&lt;p&gt;Las cuotas documentadas son 20 políticas temporales por engine, 3 operadores por política y una ventana máxima de 24 horas.&lt;/p&gt;

&lt;h2 id=&quot;cómo-lo-medí&quot;&gt;Cómo Lo Medí&lt;/h2&gt;

&lt;p&gt;El montaje fue deliberadamente simple. Una Lambda simulada con cinco herramientas (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;read_secret&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;send_webhook&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rollback&lt;/code&gt;), con datos falsos y sin salida a red. Un Gateway con autenticación &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AWS_IAM&lt;/code&gt; en us-east-1. Y un harness en Python que firma con SigV4 y escribe cada llamada en un JSONL inmutable con timestamp, request ID, decisión, latencia y la respuesta completa. Todas las tablas de este artículo salen de esos archivos por script, ninguna está hecha a mano. Para la prueba con agente usé Strands y Claude Sonnet con el perfil de inferencia &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us.&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;Un detalle para leer los datos: el Gateway devuelve las denegaciones como HTTP 200 con un error JSON-RPC &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32002&lt;/code&gt;, no como un 4xx. La decisión hay que leerla en el cuerpo de la respuesta, no en el código HTTP.&lt;/p&gt;

&lt;p&gt;El método es el mismo del &lt;a href=&quot;/agentcore-optimization-loop.html&quot; target=&quot;_blank&quot;&gt;A/B test del Optimization Loop&lt;/a&gt;: antes de ejecutar escribí cada hipótesis con el criterio que la refutaría, y registré cada cambio de diseño posterior (terminaron siendo diez). Los scripts, las políticas y el harness están en &lt;a href=&quot;https://github.com/codecr/agentcore-temporal-policies&quot; target=&quot;_blank&quot;&gt;github.com/codecr/agentcore-temporal-policies&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;El piloto con N=5 me corrigió una suposición antes de gastar en serio. Yo había definido «retardo cero» como «el cliente envía la solicitud dependiente apenas recibe la respuesta». Al medirlo, ese cero era en realidad un hueco de unos 15 ms entre una cosa y la otra, así que agregué una condición en paralelo a la prueba de secuencia y lo anoté como la primera desviación.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #1&lt;/strong&gt;: Corre un piloto con N=5 por condición antes de escalar cualquier medición contra un servicio. El mío costó menos de un centavo y me mostró que mi «retardo cero» no era cero. Con N=100 desde el inicio habría gastado el tiempo midiendo otra cosa.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-1-si-tu-agente-paraleliza-pierde-el-despliegue&quot;&gt;Hallazgo 1: Si Tu Agente Paraleliza, Pierde el Despliegue&lt;/h2&gt;

&lt;p&gt;Esta es la pregunta que dio origen al artículo. Mi hipótesis era que el evento &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt; de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; tardaría en quedar disponible, de modo que un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; enviado justo después de recibir la respuesta se denegaría en algunas sesiones. El criterio para refutarla era cero denegaciones con retardo 0 en 100 sesiones.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Condición&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Sesiones&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; denegado&lt;/th&gt;
      &lt;th&gt;Tasa (IC 95% Wilson)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Secuencial, retardo 0 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;100&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;0&lt;/td&gt;
      &lt;td&gt;0.0% [0.0, 3.7]%&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Secuencial, 50 / 100 / 250 / 500 / 1000 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;100 por celda&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;0&lt;/td&gt;
      &lt;td&gt;0.0% [0.0, 3.7]% por celda&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Paralelo (dos hilos a la vez)&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;100&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;98&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;98.0% [93.0, 99.4]%&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Agente Strands, prompt «paralelo»&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;5&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;5&lt;/td&gt;
      &lt;td&gt;N=5, sin intervalo útil&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Agente Strands, prompt «neutro»&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;5&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;5&lt;/td&gt;
      &lt;td&gt;N=5, sin intervalo útil&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;La hipótesis queda refutada. Con un hueco mediano de unos 15 ms entre la respuesta de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; y el envío de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt;, no hubo una sola denegación en 600 sesiones secuenciales: el evento ya está disponible cuando la respuesta llega al cliente.&lt;/p&gt;

&lt;p&gt;El problema aparece cuando las dos solicitudes salen a la vez. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; se evalúa casi de inmediato, mientras &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; tarda unos 770 ms en responder (mediana medida), así que el Gateway ve un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; sin pruebas completadas y lo deniega. Es el comportamiento correcto de la política. AWS ya &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-temporal.html&quot; target=&quot;_blank&quot;&gt;recomienda&lt;/a&gt; enviar la solicitud dependiente después de recibir la respuesta previa (sección &lt;em&gt;Sequencing actions that depend on a prior response&lt;/em&gt;), y su blog sobre Dogwood menciona que los agentes hacen llamadas en paralelo. Lo que agrega este experimento es la magnitud: 98 de 100.&lt;/p&gt;

&lt;p&gt;Los dos &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; que sí pasaron en la condición paralela (repeticiones 14 y 92) tuvieron latencias de 1,045 y 1,152 ms, contra una mediana de 764 ms, lo que es compatible con que su evaluación ocurriera más tarde de lo normal.&lt;/p&gt;

&lt;p&gt;Con un agente de por medio, la pregunta cambia: ¿el modelo espera la respuesta o paraleliza? Le di a un agente Strands la tarea «ejecuta las pruebas y despliega» con dos variantes de prompt, una que pedía paralelismo y otra neutra, en 5 sesiones cada una. En las 10 sesiones emitió &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; en el mismo turno, incluida la variante neutra, y el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; fue denegado en las 10. Ninguna sesión reintentó el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt;: cada una cerró con dos llamadas al Gateway y dos ciclos de modelo, así que el agente recibió el rechazo y terminó sin volver a intentarlo.&lt;/p&gt;

&lt;p&gt;Un detalle más para quien tenga que depurar esto: cuando &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; se llamó sin ningún &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; previo, el mensaje fue &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Tool Execution Denied: Tool call not allowed due to policy enforcement [No policy applies to the request (denied by default).]&lt;/code&gt;. El mensaje no distingue «todavía no» de «nunca».&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #2&lt;/strong&gt;: Si dos acciones de tu agente dependen una de la otra, no dejes que el modelo decida el orden. Serializa en el cliente o en el framework, o diseña una sola herramienta que haga ambas cosas por dentro. La segunda opción te cuesta visibilidad, porque la política ya no ve el paso intermedio; la primera te cuesta latencia. Elige sabiendo cuál de las dos pagas.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-2-las-denegaciones-también-gastan-tu-límite&quot;&gt;Hallazgo 2: Las Denegaciones También Gastan Tu Límite&lt;/h2&gt;

&lt;p&gt;Aquí mi hipótesis también estaba equivocada, y esta vez en una dirección que la documentación no anticipa.&lt;/p&gt;

&lt;p&gt;La &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-temporal-authoring.html&quot; target=&quot;_blank&quot;&gt;documentación del esquema de eventos&lt;/a&gt; dice que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;request&lt;/code&gt; se registra «for each authorized request» y que lo denegado produce un evento &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;error&lt;/code&gt;. Con esa lectura, una ráfaga de solicitudes denegadas no debería afectar un límite que cuenta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::request&lt;/code&gt;. Para comprobarlo combiné dos políticas. La primera es un límite por sesión que bloquea &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;send_webhook&lt;/code&gt; cuando hay más de cinco eventos &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::request&lt;/code&gt; en diez minutos (el conteo incluye la solicitud actual):&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;forbid (
    principal,
    action == AgentCore::Action::&quot;ToolsTarget___send_webhook&quot;,
    resource == AgentCore::Gateway::&quot;&amp;lt;ARN-DEL-GATEWAY&amp;gt;&quot;
)
when temporal {
    exists (n: Long).
        (count for (t: Timepoint).
            where (formerly within 10m (AgentCore::Action::&quot;ToolsTarget___send_webhook&quot;::request{ eventResource: resource } &amp;amp;&amp;amp; tp(t)))) == n
        &amp;amp;&amp;amp; n &amp;gt; 5
};
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;La segunda es una regla Cedar sin estado que deniega cualquier &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;send_webhook&lt;/code&gt; dirigido a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://blocked.invalid/hook&lt;/code&gt;. En cada sesión nueva envié K llamadas a esa URL, todas denegadas, y después hasta 8 llamadas permitidas, anotando en cuál de ellas aparecía el primer bloqueo por límite. Veinte pruebas por cada valor de K, en orden aleatorio.&lt;/p&gt;

&lt;p&gt;Si las denegadas no cuentan, el límite salta siempre en la sexta llamada permitida. Si cuentan, salta en la 6−K.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;K (denegadas previas)&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Pruebas&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Primer bloqueo por límite, entre las permitidas&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Si NO cuentan&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Si SÍ cuentan&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;0&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;20&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;6&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;6&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;6&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;3&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;20&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;3&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;6&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;3&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;10&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;20&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;1&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;6&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;1&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Las 40 pruebas con K mayor que cero siguieron el patrón 6−K sin excepción. Los mensajes de denegación lo confirman por otro camino: de las 260 llamadas denegadas por la regla de URL, 160 nombran solo esa política y 100 nombran &lt;strong&gt;las dos&lt;/strong&gt;. Esas 100 son las denegadas número 6 a 10 de cada prueba con K=10 (cinco por prueba, veinte pruebas). Mientras una regla rechazaba las solicitudes, el límite las iba contando. Eso sí, no parsees esa lista de políticas determinantes: en los mensajes que nombran las dos, el orden salió 55 veces de una forma y 45 de la otra.&lt;/p&gt;

&lt;p&gt;La causa no está documentada, así que esto es interpretación mía. La guía de Dogwood describe &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;request&lt;/code&gt; como el único tipo de evento «de decisión»: ingerirlo es lo que dispara la autorización, mientras que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;error&lt;/code&gt; son solo historial. Eso es consistente con que el evento quede registrado antes de conocer el veredicto, pero la guía no lo dice de forma explícita.&lt;/p&gt;

&lt;p&gt;El alcance es acotado: solo probé denegaciones de una regla Cedar sin estado, no la denegación por defecto cuando ninguna política aplica. La consecuencia práctica es incómoda. Con sesiones amplias por usuario, que la documentación lista como estrategia válida, un agente atascado reintentando contra una regla que lo rechaza podría agotar su propio límite y quedar bloqueado hasta que pase la ventana.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #3&lt;/strong&gt;: Si tu límite cuenta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::request&lt;/code&gt;, cada intento denegado cuenta. Según la documentación, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt; solo se registra cuando la acción termina con éxito, así que contar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::response&lt;/code&gt; debería contar solo lo que de verdad se ejecutó. No probé ese cambio, pero es lo primero que probaría.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-3-la-sesión-obsoleta-no-llega-como-409&quot;&gt;Hallazgo 3: La Sesión Obsoleta No Llega Como 409&lt;/h2&gt;

&lt;p&gt;Según la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-temporal.html&quot; target=&quot;_blank&quot;&gt;documentación&lt;/a&gt; (sección &lt;em&gt;Session invalidation&lt;/em&gt;), agregar o actualizar una política temporal invalida las sesiones activas del engine, y la siguiente solicitud que reutilice una sesión invalidada falla con HTTP 409 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ConflictException&lt;/code&gt;. Para recuperarte, abres una sesión nueva. Probé cada disparador con tres sesiones vivas: esperé a que la política estuviera ACTIVE, agregué 10 segundos y llamé dos veces con cada sesión.&lt;/p&gt;

&lt;p&gt;Por la ruta MCP del Gateway (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tools/call&lt;/code&gt;) nunca recibí un 409. Las 42 observaciones (21 sesiones invalidadas, dos llamadas cada una) devolvieron lo mismo: HTTP 200 con este cuerpo JSON-RPC.&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;code&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;-32005&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;message&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Tool Execution Denied: Policy session is stale. Policies were updated after the session started. Start a new session and retry.&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Disparador&lt;/th&gt;
      &lt;th&gt;¿Invalida sesiones vivas?&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Crear política temporal&lt;/td&gt;
      &lt;td&gt;Sí (3 de 3, en dos corridas)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Actualizar política temporal&lt;/td&gt;
      &lt;td&gt;Sí (3 de 3)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Borrar política temporal&lt;/td&gt;
      &lt;td&gt;Sí (3 de 3, en dos corridas)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update-policy&lt;/code&gt; sin cambio real (la política ya estaba ACTIVE)&lt;/td&gt;
      &lt;td&gt;Sí (3 de 3, en dos corridas)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Crear o borrar una política Cedar sin estado&lt;/td&gt;
      &lt;td&gt;No (0 de 3)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Gateway de ENFORCE a LOG_ONLY, y de vuelta&lt;/td&gt;
      &lt;td&gt;No (0 de 3)&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;De la tabla salen varios comportamientos que la documentación no menciona. Solo invalidan las sesiones los cambios en políticas &lt;strong&gt;temporales&lt;/strong&gt;; una política Cedar sin estado o un cambio de modo del Gateway no las afectan, aunque el blog de lanzamiento de AWS habla de cualquier cambio en las políticas del engine. Borrar una política temporal también invalida, aunque la documentación solo menciona agregar o actualizar. Una sesión obsoleta no se recupera sola: las 21 sesiones invalidadas siguieron obsoletas en la segunda llamada, mientras que una sesión nueva funcionó en las 7 de 7 pruebas donde el disparador sí invalidó. Y un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update-policy&lt;/code&gt; sin cambio efectivo también invalida.&lt;/p&gt;

&lt;p&gt;Ese último caso lo encontré por accidente. El disparador que había diseñado como «de LOG_ONLY a ACTIVE» terminó siendo un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update-policy&lt;/code&gt; sobre una política que ya estaba ACTIVE, porque el paso anterior falló (lo cuento en los gotchas operativos).&lt;/p&gt;

&lt;p&gt;De la documentación se deduce una consecuencia de diseño: una sesión nueva empieza con el historial vacío, así que desplegar una política temporal también &lt;strong&gt;reinicia&lt;/strong&gt; los contadores de límite y las precondiciones de secuencia de todas las conversaciones vivas.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #4&lt;/strong&gt;: Trata el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32005&lt;/code&gt; como una señal de control del flujo y no como un error para el usuario. Tu cliente debería capturarlo, abrir una sesión nueva y volver a establecer las precondiciones (por ejemplo, correr las pruebas otra vez). Si no lo manejas, cada reintento con el mismo ID va a fallar: en mis pruebas, ninguna sesión obsoleta se recuperó sola.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;La detección tiene que mirar el cuerpo, porque el código HTTP es 200 tanto en la denegación (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32002&lt;/code&gt;) como en la sesión obsoleta (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32005&lt;/code&gt;). Este es el criterio que usó mi harness para clasificar las respuestas, con el caso de la sesión obsoleta agregado:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;DENEGADO&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32002&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;SESION_OBSOLETA&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32005&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;clasificar&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cuerpo&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;cuerpo&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;isinstance&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cuerpo&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;isinstance&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;code&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SESION_OBSOLETA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;STALE&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# sesión nueva, rehacer precondiciones, reintentar una vez
&lt;/span&gt;        &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;code&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DENEGADO&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;DENY&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;OTRO&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;TOOL_ERROR&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;cuerpo&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}).&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;isError&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;ALLOW&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;La recuperación del comentario (sesión nueva, rehacer las precondiciones y un solo reintento) no forma parte del experimento: es lo que haría, no algo que medí.&lt;/p&gt;

&lt;h2 id=&quot;hallazgo-4-la-validación-estricta-contra-el-patrón-documentado&quot;&gt;Hallazgo 4: La Validación Estricta Contra el Patrón Documentado&lt;/h2&gt;

&lt;p&gt;Estos dos gotchas me costaron una tarde, y ambos vienen de la validación por defecto de las políticas (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FAIL_ON_ANY_FINDINGS&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; simple que pide la documentación falla.&lt;/strong&gt; Para que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; quede registrada como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt;, necesitas un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; sin condiciones para esa acción. Con la validación por defecto, la política pasa a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CREATE_FAILED&lt;/code&gt; con dos motivos, uno por cada tipo de principal:&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Overly Permissive: Policy Engine will allow every request for the specified principal (AgentCore::IamEntity), action (ToolsTarget___run_tests) and resource (arn:aws:bedrock-agentcore:us-east-1:&amp;lt;CUENTA&amp;gt;:gateway/&amp;lt;GATEWAY&amp;gt;) combination if the policy is added or updated
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El segundo motivo es idéntico, pero con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgentCore::OAuthUser&lt;/code&gt;, aunque mi Gateway usa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AWS_IAM&lt;/code&gt;. Lo resolví con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--validation-mode IGNORE_ALL_FINDINGS&lt;/code&gt; solo para los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; simples, y mantuve la validación estricta en las políticas temporales.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt; creado antes que su &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; también falla.&lt;/strong&gt; El límite de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt; que usé para medir latencia (con un umbral inalcanzable) falló dos veces con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Overly Restrictive: Policy Engine will deny every request for the specified principal ...&lt;/code&gt;, primero con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n &amp;gt; 100000&lt;/code&gt; y después con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;n &amp;gt; 5000&lt;/code&gt;. Pasó al tercer intento cambiando una sola cosa: creé primero el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; de la acción y después el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt;. Lo vi en un único caso (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt; sobre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;read_secret&lt;/code&gt;), así que no lo generalizo.&lt;/p&gt;

&lt;p&gt;Esto deja un problema operativo. El orden fail-closed, con el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt; primero para que nunca exista una ventana sin límite, es incompatible con la validación estricta. Si aplicas el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; y después el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt;, durante un instante la acción queda permitida sin su límite. En mi caso lo evité creando todo en un entorno sin tráfico. En producción vas a necesitar otra estrategia; una opción es crear las políticas en un engine nuevo antes de asociarlo al Gateway.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #5&lt;/strong&gt;: Si automatizas la creación de políticas en un pipeline, prueba el orden de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt; con la validación estricta &lt;strong&gt;antes&lt;/strong&gt; de depender de él. Y deja escrito en tu runbook en qué orden vas a crearlas y qué ventana de exposición estás aceptando.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;hallazgo-5-la-evaluación-temporal-cuesta-unos-20-ms&quot;&gt;Hallazgo 5: La Evaluación Temporal Cuesta Unos 20 ms&lt;/h2&gt;

&lt;p&gt;La hipótesis era que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sum&lt;/code&gt; se volverían más lentos con un historial grande, mientras que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt; se mantendría casi plano. Medí la latencia de evaluación temporal con el atributo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws.agentcore.policy.temporal.latency_ms&lt;/code&gt; de los spans de Transaction Search, en una sola sesión por operador con 1,000 llamadas consecutivas.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Operador&lt;/th&gt;
      &lt;th&gt;Historial previo&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;P50&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;P99&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~10 llamadas&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;21 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;26 ms&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~100&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;21 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;24 ms&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~1,000&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;24 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;27 ms&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~10&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;21 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;39 ms&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~100&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;20 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;25 ms&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~1,000&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;20 ms&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;24 ms&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Con el criterio que fijé antes de medir (refutada si la diferencia de P99 entre 10 y 1,000 llamadas es menor al 10%), la hipótesis queda refutada para &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt;: la diferencia es de 3.8%. Las medianas por decil muestran algo más fino. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;count&lt;/code&gt; sube de 20 a 24 ms a lo largo de las 1,000 llamadas, unos 0.29 ms por cada 100, mientras que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt; se queda en 21 ms en los diez deciles. Hay crecimiento, pero es tan pequeño que no representa un problema operativo. El piso de unos 20 ms existe incluso con el historial casi vacío, y frente a los ~800 ms de la llamada completa (que incluye el Gateway y mi Lambda simulada) representa alrededor del 3%.&lt;/p&gt;

&lt;p&gt;Hay que leer esta tabla con cuidado. Son 20 muestras por ventana, así que el P99 es prácticamente el máximo. La ventana de ~10 llamadas siempre corresponde a las primeras 20 de la corrida, de modo que el tamaño del historial y el calentamiento están mezclados; los 39 ms de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt; probablemente vienen de ahí. Además conté llamadas y no eventos: cada llamada deja al menos un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;request&lt;/code&gt; y un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;response&lt;/code&gt;, así que el historial real es mayor que el nominal. Una llamada de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;formerly&lt;/code&gt; agotó el tiempo de espera (la n=640).&lt;/p&gt;

&lt;h2 id=&quot;el-id-de-sesión-lo-debe-elegir-tu-backend&quot;&gt;El ID de Sesión Lo Debe Elegir Tu Backend&lt;/h2&gt;

&lt;p&gt;La documentación ya cubre este punto; aquí solo lo cuantifico. Un límite por sesión no sirve contra quien elige su propio session ID. Con 20 pruebas por condición: con el ID fijo, el bloqueo llegó en la llamada 6 en 20 de 20; rotando el ID en cada llamada, &lt;strong&gt;0 de 20&lt;/strong&gt; pruebas se bloquearon; y con el ID derivado en un backend mediante un HMAC del usuario, otra vez 20 de 20, con aislamiento correcto entre usuarios en 20 de 20.&lt;/p&gt;

&lt;p&gt;La documentación también advierte que usar un ID nuevo en cada solicitud desactiva en la práctica las políticas temporales.&lt;/p&gt;

&lt;p&gt;La derivación que usé es una línea de HMAC con una clave que solo conoce el backend:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;hashlib&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;hmac&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;secrets&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;class&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;BackendSesion&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;__init__&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_clave&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;secrets&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;token_bytes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;32&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# en producción, desde Secrets Manager
&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;session_id_para&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;usuario&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;hmac&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;new&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_clave&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;usuario&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;encode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;utf-8&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;hashlib&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;sha256&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;hexdigest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El resultado son 64 caracteres hexadecimales, dentro del formato que acepta el header (1 a 128 caracteres &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[A-Za-z0-9-]&lt;/code&gt;). En el experimento derivé el ID solo del usuario, lo que da una sesión amplia por usuario. Si quieres sesiones por conversación, agrega el ID de la conversación al mensaje del HMAC.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔧 &lt;strong&gt;ProTip #6&lt;/strong&gt;: Genera el session ID en tu backend a partir del usuario y la conversación (un HMAC alcanza), nunca en el agente. Un límite por sesión que el agente puede reiniciar con un UUID nuevo no protege nada.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;gotchas-operativos&quot;&gt;Gotchas Operativos&lt;/h2&gt;

&lt;p&gt;Estos no son propios de las Temporal Policies, pero te los vas a encontrar si repites el experimento.&lt;/p&gt;

&lt;p&gt;Para medir latencia necesitas Transaction Search, y el destino de segmentos de X-Ray pasa por un estado &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PENDING&lt;/code&gt;. Mientras tanto, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateDelivery&lt;/code&gt; falla con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-Ray Delivery Destination is supported with CloudWatch Logs as a Trace Segment Destination&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UpdateTraceSegmentDestination&lt;/code&gt; con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Updates are not allowed while the current status is PENDING&lt;/code&gt;. Espera a que llegue a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ACTIVE&lt;/code&gt;. Cada span de política trae un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws.request.id&lt;/code&gt; igual al &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;x-amzn-RequestId&lt;/code&gt; de la respuesta, y con eso puedes unir spans y llamadas.&lt;/p&gt;

&lt;p&gt;Pasar una política temporal de ACTIVE a LOG_ONLY falló con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UPDATE_FAILED&lt;/code&gt; en las dos corridas. En la segunda, el motivo fue &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Policy references an action that does not exist on the target gateway. Verify the target and tool names, then try again.&lt;/code&gt; La acción sí existe en el Gateway.&lt;/p&gt;

&lt;p&gt;El llamador firma con SigV4 usando el servicio &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore&lt;/code&gt;, un detalle que la documentación de autenticación de entrada no menciona.&lt;/p&gt;

&lt;h2 id=&quot;qué-garantiza-una-temporal-policy-y-qué-no&quot;&gt;Qué Garantiza una Temporal Policy y Qué No&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Lo que observé que garantiza&lt;/th&gt;
      &lt;th&gt;Lo que no te garantiza&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Deniega &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; si no hubo un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run_tests&lt;/code&gt; completado&lt;/td&gt;
      &lt;td&gt;Que tu agente espere: paralelizó en las 10 sesiones y el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;deploy&lt;/code&gt; fue denegado en las 10&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Bloquea la llamada 6 de un límite por sesión (20 de 20)&lt;/td&gt;
      &lt;td&gt;Un límite si el agente elige su ID (0 de 20 bloqueos con ID rotado)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Cuenta las solicitudes denegadas en un límite &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::request&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Que cuente solo lo ejecutado, salvo que cuentes &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::response&lt;/code&gt; (no probado)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Invalida sesiones vivas al cambiar políticas temporales&lt;/td&gt;
      &lt;td&gt;Un 409 (llega un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32005&lt;/code&gt;), ni que la sesión nueva conserve el historial&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Evalúa en 20 a 27 ms con historial de hasta ~1,000 llamadas&lt;/td&gt;
      &lt;td&gt;Que esas cifras apliquen a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sum&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;since&lt;/code&gt;, otro modelo, otra región u otra hora del día&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;límites-del-experimento&quot;&gt;Límites del Experimento&lt;/h2&gt;

&lt;p&gt;La prueba con agente usó una sola tarea explícita, un solo modelo y 5 sesiones por variante. Todo corrió en un solo día (entre las 10:54 y las 17:50, hora de Costa Rica), en una región, una cuenta, un Gateway y con una Lambda simulada, y las 20 muestras por ventana de la prueba de latencia son pocas.&lt;/p&gt;

&lt;p&gt;Esto es lo que quedó sin probar:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;Cómo reacciona un agente Strands con reintentos por defecto ante un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32005&lt;/code&gt;, y si el reinicio de contadores que se deduce de la documentación se ve igual con un agente real.&lt;/li&gt;
  &lt;li&gt;Contar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::response&lt;/code&gt; en lugar de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;::request&lt;/code&gt;, y la denegación por defecto cuando ninguna política aplica.&lt;/li&gt;
  &lt;li&gt;Si el 409 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ConflictException&lt;/code&gt; existe en otra capa, como el plano de control.&lt;/li&gt;
  &lt;li&gt;El paso de LOG_ONLY a ENFORCE a nivel de política. No encontré la causa del &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UPDATE_FAILED&lt;/code&gt;; crear la política directamente en LOG_ONLY queda pendiente.&lt;/li&gt;
  &lt;li&gt;Una estrategia para crear &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;permit&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;forbid&lt;/code&gt; en producción sin ventana de exposición.&lt;/li&gt;
  &lt;li&gt;Los operadores &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sum&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;since&lt;/code&gt;, y la autenticación &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM_JWT&lt;/code&gt;.&lt;/li&gt;
  &lt;li&gt;Qué pasa cuando el agente corre en AgentCore Runtime y envía su propio header de sesión: si prevalece el session ID que viaja en el token de identidad (WAT) o el del agente. La documentación no lo dice y no llegué a probarlo.&lt;/li&gt;
  &lt;li&gt;Un Gateway sin autenticación, donde según la documentación todos los llamadores con el mismo ID comparten el historial.&lt;/li&gt;
  &lt;li&gt;Un backend desplegado para el session ID. El mío fue un módulo local y todos los usuarios simulados compartían la misma identidad IAM, así que evalué la lógica de derivación, no un servicio.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Esos son los huecos que más me gustaría cerrar.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;El experimento se resume en tres decisiones de diseño. Serializa en el cliente las acciones que dependen unas de otras, porque tu agente puede paralelizar sin que se lo pidas: el mío lo hizo en las 10 sesiones. Genera el session ID en tu backend, porque un límite que el agente puede reiniciar no limita nada. Y maneja el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;-32005&lt;/code&gt;, porque cada vez que despliegues una política temporal vas a invalidar conversaciones vivas, y la sesión nueva arranca sin el historial que tenía la anterior.&lt;/p&gt;

&lt;p&gt;El servicio se comportó casi siempre como describe la documentación. La sorpresa más grande fue el agente, que no se comportó como yo suponía. Las demás estuvieron en los bordes: qué cuenta como evento, qué código llega cuando una sesión queda obsoleta, en qué orden acepta la validación tus políticas. Esos bordes son los que conviene probar antes de producción.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚀 &lt;strong&gt;ProTip Final&lt;/strong&gt;: Antes de confiar en una política temporal para proteger algo importante, mídela con tu propio agente, tu propio modelo y tu propia estrategia de sesiones. En mi experimento, la sorpresa más grande vino del agente, no de la política.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Si vienes del &lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;artículo de AgentCore Policy&lt;/a&gt;, las Temporal Policies son la pieza que le faltaba: Cedar decide sobre una solicitud; Dogwood, sobre la historia de la sesión. Y si te interesa el método, el &lt;a href=&quot;/agentcore-optimization-loop.html&quot; target=&quot;_blank&quot;&gt;A/B test del Optimization Loop&lt;/a&gt; lo aplica con un resultado negativo incluido.&lt;/p&gt;

&lt;hr /&gt;

&lt;p&gt;¿Ya estás usando Temporal Policies, o sigues controlando secuencias y límites dentro del código del agente? ¿Cómo estás generando el session ID? Si replicaste alguna de estas pruebas o mediste lo que yo dejé fuera, me interesa mucho comparar — los comentarios están abiertos.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-temporal.html&quot; target=&quot;_blank&quot;&gt;Temporal policies, AgentCore Developer Guide&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-session-based-temporal.html&quot; target=&quot;_blank&quot;&gt;Policy sessions and identity propagation&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-temporal-authoring.html&quot; target=&quot;_blank&quot;&gt;Authoring temporal policies&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-policy-metrics.html&quot; target=&quot;_blank&quot;&gt;Policy in AgentCore observability data&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-test-a-policy.html&quot; target=&quot;_blank&quot;&gt;Probar una política (modos LOG_ONLY y ENFORCE)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://dogwood-policy.github.io/dogwood/guide/03-event-schema.html&quot; target=&quot;_blank&quot;&gt;Dogwood: guía del esquema de eventos&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://dogwood-policy.github.io/dogwood/guide/04-temporal-expressions.html&quot; target=&quot;_blank&quot;&gt;Dogwood: expresiones temporales&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/opensource/introducing-dogwood-runtime-verification-for-ai-agents/&quot; target=&quot;_blank&quot;&gt;Introducing Dogwood: runtime verification for AI agents (AWS Open Source Blog)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/securing-ai-agents-with-temporal-policies-in-amazon-bedrock-agentcore/&quot; target=&quot;_blank&quot;&gt;Securing AI agents with temporal policies in Amazon Bedrock AgentCore (AWS ML Blog)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Mon, 12 Oct 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/agentcore-temporal-policies.html</link>
                <guid isPermaLink="true">https://gerardo.dev/agentcore-temporal-policies.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>AgentCore</category>
                
                <category>Gateway</category>
                
                <category>Policy</category>
                
                <category>Dogwood</category>
                
                <category>Security</category>
                
                <category>GenAI</category>
                
                
            </item>
        
            <item>
                <title>Le Quité el Volante a mi RAG: Managed KB vs. Chunking Manual</title>
                <description>&lt;p&gt;En abril publiqué un benchmark comparando 5 estrategias de chunking en Amazon Bedrock Knowledge Bases. La conclusión práctica fue simple: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt; con S3 Vectors como backend, y listo, a menos que tus datos justifiquen algo más complejo.&lt;/p&gt;

&lt;p&gt;Tres meses después, AWS le quitó la pregunta al problema. Amazon Bedrock Managed Knowledge Base no te pide elegir estrategia de chunking. Smart Parsing decide el parsing por tipo de documento, AWS administra el vector store, y si tus preguntas son complejas, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; planifica una estrategia de retrieval en vez de hacer una sola búsqueda por similitud.&lt;/p&gt;

&lt;p&gt;Suena a que la discusión de abril quedó obsoleta. Así que hice la pregunta que me pareció honesta: &lt;strong&gt;¿cuánto cuesta en calidad que te quiten el volante, y bajo qué condiciones se recupera esa pérdida?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;No tenía una tesis antes de correr esto. La tengo ahora, y no es la que esperaba.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;Spoiler&lt;/strong&gt;: El retrieval gestionado simple prácticamente empata con mi configuración manual de abril. Lo que no funcionó es el planner agéntico —la pieza que justifica el “agentic” del nombre— con el modelo que AWS te da por defecto: &lt;strong&gt;no descompuso una sola consulta en 80 preguntas evaluadas&lt;/strong&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;En este artículo va la metodología completa: cinco configuraciones de retrieval sobre el mismo corpus, dos sets de preguntas —las 25 de un salto de abril sin tocar, y 15 nuevas multi-hop redactadas contra el texto real de los documentos—, tres planners distintos, y los 6 gotchas de infraestructura que hubo que resolver antes de poder medir nada. Porque el hallazgo del planner tiene una vuelta: depende enteramente de qué modelo planifica, y eso no lo supe hasta que dejé de usar el que viene por defecto.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;&lt;strong&gt;📌 TL;DR — Datos clave antes de seguir leyendo&lt;/strong&gt;&lt;/p&gt;

  &lt;ul&gt;
    &lt;li&gt;&lt;strong&gt;Managed KB con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; simple&lt;/strong&gt; ≈ mi configuración manual de abril en Correctness (0.88 vs 0.84, diferencia dentro de lo esperable).&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Smart Parsing ingesta sin fallar&lt;/strong&gt; los dos PDF que en abril reventaron &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; — y lo hace más rápido que mi pipeline manual (183s vs 407s). Incluso ingesta y recupera correctamente un PDF sin capa de texto extraíble.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; con el planner por defecto (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;) nunca generó una sola sub-query&lt;/strong&gt; en 80/80 preguntas evaluadas, incluidas las que un retrieval simple demostrablemente no podía resolver.&lt;/li&gt;
    &lt;li&gt;En preguntas multi-hop, eso hizo que el retriever “agéntico” quedara &lt;strong&gt;por debajo&lt;/strong&gt; del retrieval simple (0.50 vs 0.567 de Correctness).&lt;/li&gt;
    &lt;li&gt;Con planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; pequeño (Claude Haiku 4.5), sí aparece descomposición real — pero en preguntas que ya no la necesitaban, no en las 5 que sí.&lt;/li&gt;
    &lt;li&gt;Con planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; &lt;strong&gt;grande&lt;/strong&gt; (Claude Sonnet 4.6, el mismo modelo que mi generador), la Correctness en multi-hop saltó de 0.50 a &lt;strong&gt;1.00&lt;/strong&gt;, sostenido en dos corridas independientes — pero el planner y el generador comparten modelo en esa prueba, y lo digo explícito como salvedad, no como letra chica.&lt;/li&gt;
    &lt;li&gt;El corpus &lt;strong&gt;no es byte-idéntico&lt;/strong&gt; al de abril: mi bucket original fue destruido y tuve que re-descargar los documentos. Lo digo explícito, no lo escondo.&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;por-qué-me-importa-esto&quot;&gt;Por Qué Me Importa Esto&lt;/h2&gt;

&lt;p&gt;No es una curiosidad académica. Si estás evaluando si migrar un RAG de producción hacia Managed Knowledge Base, la pregunta real no es “¿es mejor?” — es “¿qué pierdo al dejar de controlar el chunking, y qué gano si dejo que el servicio también decida cuándo y cómo buscar más de una vez?”&lt;/p&gt;

&lt;p&gt;Esa segunda parte es la que casi nadie mide. AWS presenta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; con números de un benchmark académico (MuSiQue) que muestran mejoras de hasta +37 puntos de recall en preguntas de 4 saltos. Son números reales, publicados en su &lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/agentic-retrieval-for-amazon-bedrock-managed-knowledge-base/&quot; target=&quot;_blank&quot;&gt;blog oficial sobre agentic retrieval&lt;/a&gt;, y los desgloso más abajo. Pero un benchmark académico no te dice qué pasa cuando el planner que obtienes &lt;strong&gt;por defecto&lt;/strong&gt;, sin tocar ningún parámetro, se enfrenta a tu propio corpus.&lt;/p&gt;

&lt;p&gt;Eso es lo que corrí.&lt;/p&gt;

&lt;h2 id=&quot;el-diseño-cinco-configuraciones-dos-sets-de-preguntas&quot;&gt;El Diseño: Cinco Configuraciones, Dos Sets de Preguntas&lt;/h2&gt;

&lt;p&gt;Mantuve el generador (Claude Sonnet 4.6) y el juez (Nova Pro, cross-family) constantes en cuatro de las cinco configuraciones —la única excepción es D, donde genera el propio servicio— para aislar la capa de retrieval como única variable:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Config&lt;/th&gt;
      &lt;th&gt;Retrieval&lt;/th&gt;
      &lt;th&gt;Generación&lt;/th&gt;
      &lt;th&gt;Pregunta que responde&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;A&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;S3 Vectors + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt; (abril)&lt;/td&gt;
      &lt;td&gt;Sonnet 4.6&lt;/td&gt;
      &lt;td&gt;Línea base&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;B&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Managed KB, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Sonnet 4.6&lt;/td&gt;
      &lt;td&gt;¿Perdí calidad al entregar el volante?&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;C&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Managed KB, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;generateResponse=False&lt;/code&gt;, planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;)&lt;/td&gt;
      &lt;td&gt;Sonnet 4.6&lt;/td&gt;
      &lt;td&gt;¿Sirve el planner por defecto?&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;D&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Managed KB, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;generateResponse=True&lt;/code&gt;, planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;)&lt;/td&gt;
      &lt;td&gt;El propio servicio&lt;/td&gt;
      &lt;td&gt;¿Y si dejo que AWS también genere?&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;E&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Managed KB, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;generateResponse=False&lt;/code&gt;, planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; = Sonnet 4.6)&lt;/td&gt;
      &lt;td&gt;Sonnet 4.6&lt;/td&gt;
      &lt;td&gt;¿Ayuda un planner &lt;em&gt;grande&lt;/em&gt;, no solo distinto del gestionado?&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Las primeras cuatro corrieron juntas. La E la agregué un día después, como respuesta directa a lo que encontré con C — la cuento en detalle más abajo, en su propia sección, para no mezclar una corrida exploratoria con el diseño pre-registrado original.&lt;/p&gt;

&lt;p&gt;Y dos sets de preguntas sobre el mismo corpus de 3 documentos técnicos (el Well-Architected Framework, el developer guide de AgentCore, y un blog post de RAG evaluation):&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Set 1-hop&lt;/strong&gt;: las 25 preguntas originales de abril, de un solo salto. Sin tocar, por comparabilidad.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Set multi-hop&lt;/strong&gt;: 15 preguntas nuevas, multi-hop y comparativas, redactadas contra el texto real de los documentos, no contra resúmenes.&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #1&lt;/strong&gt;: Si vas a comparar un retriever “agéntico” contra uno simple, necesitas dos sets de preguntas, no uno. AWS mismo reporta que su ganancia en preguntas de un solo salto es menor a 5 puntos de recall. Correr solo preguntas de un salto contra un retriever que planifica es medir algo que se sabe de antemano que no va a mostrar diferencia — no es un benchmark, es una confirmación.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Un control de imparcialidad que me costó tiempo pero era innegociable: &lt;strong&gt;volví a correr la configuración A completa&lt;/strong&gt;, no reutilicé los scores publicados en abril. Aquellos salieron del path nativo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieveAndGenerate&lt;/code&gt;; B, C y D solo se pueden evaluar por el path &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-evaluation-create-randg.html&quot; target=&quot;_blank&quot;&gt;&lt;em&gt;bring your own inference responses&lt;/em&gt;&lt;/a&gt; (BYOI). Comparar scores producidos por dos mecanismos de evaluación distintos habría sido exactamente el tipo de trampa metodológica que le critico a otros benchmarks.&lt;/p&gt;

&lt;h2 id=&quot;primer-gotcha-antes-de-escribir-una-línea-de-código-de-retrieval&quot;&gt;Primer Gotcha, Antes de Escribir una Línea de Código de Retrieval&lt;/h2&gt;

&lt;p&gt;Mi plan original era reutilizar la Knowledge Base de abril tal cual. No pude.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La KB de abril y su bucket de corpus ya no existían.&lt;/strong&gt; No fue un descuido — los había destruido intencionalmente tras publicar el artículo, como hago con casi toda mi infraestructura de benchmark. Verificado contra la cuenta real antes de asumir nada: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;list-knowledge-bases&lt;/code&gt; devolvió cero resultados en cinco regiones, el bucket de S3 Vectors no tenía buckets, y el bucket del corpus daba &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NoSuchBucket&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Tuve que recrear solo el módulo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt; del repo de abril (Titan v2, 1024 dimensiones, 512 tokens de chunk, 20% de overlap) — sin los otros 4 módulos de chunking, que no hacían falta para este benchmark.&lt;/p&gt;

&lt;p&gt;Y aquí viene la parte incómoda que sí hay que decir: &lt;strong&gt;el corpus no pudo ser byte-idéntico al de abril&lt;/strong&gt;. La carpeta de datos estaba en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.gitignore&lt;/code&gt; del repo original — nunca versioné el contenido real, así que no había hash ni manifest contra qué comparar. Verificado por HTTP HEAD:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Documento&lt;/th&gt;
      &lt;th&gt;Abril (según README)&lt;/th&gt;
      &lt;th&gt;Hoy&lt;/th&gt;
      &lt;th&gt;Conclusión&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-dg.pdf&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~17 MB&lt;/td&gt;
      &lt;td&gt;30,420,374 bytes&lt;/td&gt;
      &lt;td&gt;Casi el doble. Confirmado NO idéntico.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;wellarchitected-framework.pdf&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;~14 MB&lt;/td&gt;
      &lt;td&gt;14,189,927 bytes&lt;/td&gt;
      &lt;td&gt;Tamaño similar, pero sin hash no puedo afirmar identidad exacta.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;blog-rag-evaluation.html&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;Modificado el 18 de agosto&lt;/td&gt;
      &lt;td&gt;Tocado después de abril.&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;El AgentCore developer guide prácticamente duplicó su tamaño en cuatro meses, lo cual tiene sentido — es el servicio que más ha evolucionado en ese periodo. Reporto esto como limitación explícita del re-run. No lo escondo, no lo minimizo, y tampoco creo que invalide la comparación: los documentos siguen siendo la misma &lt;em&gt;clase&lt;/em&gt; de contenido (documentación técnica AWS densa), que es lo que el benchmark de abril necesitaba para ser representativo.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #2&lt;/strong&gt;: Si vas a publicar un benchmark que planeas revisitar meses después, versiona el corpus con un hash público (aunque no subas los archivos completos). Yo no lo hice en abril y me costó poder afirmar “byte-idéntico” con evidencia, no solo con intención.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;segundo-bloque-de-gotchas-crear-y-consultar-una-managed-kb-no-es-como-crear-una-normal&quot;&gt;Segundo Bloque de Gotchas: Crear y Consultar una Managed KB No Es Como Crear una Normal&lt;/h2&gt;

&lt;p&gt;Seis problemas de infraestructura reales, ninguno documentado junto en ningún lugar que haya encontrado.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; sobre una Managed KB rechaza &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;vectorSearchConfiguration&lt;/code&gt;.&lt;/strong&gt; Mi código de abril usaba ese parámetro sin problema contra la KB de S3 Vectors. Contra la Managed KB, el servicio respondió:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: Incompatible configuration: vectorSearchConfiguration
is not supported for managed knowledge bases. Use managedSearchConfiguration
instead.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Mismo shape interno, distinta clave contenedora. Config A usa una, config B necesita la otra.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;2. Crear el data source S3 con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;type=S3&lt;/code&gt; falla en una Managed KB.&lt;/strong&gt; El error:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: Unsupported data source type for MANAGED knowledge
base type.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;La forma correcta —que solo encontré contra un ejemplo real de AWS, no contra la documentación de referencia del shape— es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;type=MANAGED_KNOWLEDGE_BASE_CONNECTOR&lt;/code&gt;, con la configuración del conector anidada un nivel más adentro de lo intuitivo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;3. La creación es asíncrona de una forma que no esperaba.&lt;/strong&gt; Con Terraform, la config A acepta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateKnowledgeBase&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateDataSource&lt;/code&gt; en secuencia sin esperar. Contra una Managed KB, llamar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateDataSource&lt;/code&gt; mientras la KB sigue en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CREATING&lt;/code&gt; falla con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ConflictException&lt;/code&gt;. Hay que hacer polling hasta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AVAILABLE&lt;/code&gt; antes de seguir — típicamente 2-5 minutos.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;4. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ragSourceIdentifier&lt;/code&gt; en el eval job no es una etiqueta libre.&lt;/strong&gt; Intenté ponerle un nombre descriptivo (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;D-setA&quot;&lt;/code&gt;) y el servicio lo rechazó: tiene que coincidir &lt;strong&gt;exactamente&lt;/strong&gt; con el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;knowledgeBaseIdentifier&lt;/code&gt; que trae cada línea del dataset BYOI, o falla con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ValidationException&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;5. El esquema de salida del eval job es distinto al que está documentado para “automated MODEL evaluation”.&lt;/strong&gt; Ese esquema documentado usa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;automatedEvaluationResult.scores&lt;/code&gt; en la raíz. El real, confirmado contra un output crudo en S3, es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;conversationTurns[].results[]&lt;/code&gt;, con un JSONL único por job en una ruta que genera el servicio.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;6. El juez a veces no puede extraer un score.&lt;/strong&gt; Un ejemplo real, verificado contra el JSONL crudo: para la pregunta “Summarize the design principles of the Operational Excellence pillar” (config A, set 1-hop), Nova Pro respondió en lenguaje natural con una explicación perfectamente coherente, pero &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.Faithfulness&lt;/code&gt; quedó en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;result: null&lt;/code&gt; con el mensaje &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Unable to parse score from the LLM judge response&lt;/code&gt;. No es que el juez haya fallado en razonar — el servicio simplemente no pudo parsear un número de esa respuesta específica. Lo cuento y lo reporto en el conteo final, no lo promedio ocultándolo.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/01-judge-parse-error.png&quot; alt=&quot;Vista de conversación de ejemplo en la consola de Bedrock Evaluations mostrando la respuesta del juez y el error Unable to parse score from the LLM judge response&quot; /&gt;
&lt;em&gt;Figura 1: La respuesta del juez es coherente y lista los principios correctamente, pero el servicio no logró extraer un score numérico de ese texto. El error queda documentado en la propia consola.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Con eso resuelto, sí pude confirmar algo que rompió a mi favor: &lt;strong&gt;Smart Parsing ingesta sin quejarse&lt;/strong&gt; los dos PDF que en abril reventaron &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; (límite de 1 MB) y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; (límite de 50,000 caracteres). El job terminó en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;COMPLETE&lt;/code&gt;, 3 de 3 documentos indexados, 0 fallidos, en aproximadamente 183 segundos — más rápido que mi pipeline manual de FIXED_SIZE + S3 Vectors sobre el mismo corpus (~407 segundos).&lt;/p&gt;

&lt;p&gt;Fui un paso más allá para estresar Smart Parsing de verdad: generé un PDF sintético de 2 páginas &lt;strong&gt;sin ninguna capa de texto extraíble&lt;/strong&gt; —confirmé con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pypdf&lt;/code&gt; que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;extract_text()&lt;/code&gt; devuelve cadena vacía en ambas páginas, solo contenido rasterizado a imagen— y lo agregué al corpus. El ingestion job terminó igual en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;COMPLETE&lt;/code&gt;, sin fallos ni documentos saltados. Y no se quedó en “lo aceptó de nombre”: un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; directo con una query sobre el contenido de ese PDF devolvió el texto correcto como primer resultado, con score 0.981, apuntando exactamente al archivo. La &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html&quot; target=&quot;_blank&quot;&gt;documentación de Knowledge Bases&lt;/a&gt; sí lista los documentos escaneados entre los tipos que Smart Parsing selecciona automáticamente, pero no nombra el mecanismo: que corra OCR internamente lo infiero del resultado, no de una promesa explícita.&lt;/p&gt;

&lt;p&gt;Eso ya es un dato con peso: si tu corpus tiene archivos grandes o escaneados que rompen chunking manual, Managed KB te resuelve un problema real sin que tengas que pensarlo.&lt;/p&gt;

&lt;h2 id=&quot;los-resultados&quot;&gt;Los Resultados&lt;/h2&gt;

&lt;p&gt;Juez Nova Pro y BYOI en todas las configuraciones, con los mismos scripts para A, B, C y D. Una sola corrida por celda — no promediada sobre múltiples ejecuciones, así que tómalo como señal, no como certeza estadística.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/02-rag-evaluations-completadas.png&quot; alt=&quot;Lista de 8 RAG evaluation jobs completados en la consola de Amazon Bedrock, uno por cada combinación de configuración y set de preguntas&quot; /&gt;
&lt;em&gt;Figura 2: Las 8 combinaciones del diseño original (configuraciones A-D × 2 sets) terminaron &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Completed&lt;/code&gt; en la consola de RAG evaluations. Ninguna quedó a medias ni falló silenciosamente.&lt;/em&gt;&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Config&lt;/th&gt;
      &lt;th&gt;Set&lt;/th&gt;
      &lt;th&gt;Correctness&lt;/th&gt;
      &lt;th&gt;Completeness&lt;/th&gt;
      &lt;th&gt;Faithfulness&lt;/th&gt;
      &lt;th&gt;Helpfulness&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;A&lt;/td&gt;
      &lt;td&gt;un salto (n=25)&lt;/td&gt;
      &lt;td&gt;0.84&lt;/td&gt;
      &lt;td&gt;0.66&lt;/td&gt;
      &lt;td&gt;0.875&lt;/td&gt;
      &lt;td&gt;0.847&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;B&lt;/td&gt;
      &lt;td&gt;un salto (n=25)&lt;/td&gt;
      &lt;td&gt;0.88&lt;/td&gt;
      &lt;td&gt;0.68&lt;/td&gt;
      &lt;td&gt;0.95&lt;/td&gt;
      &lt;td&gt;0.880&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;C&lt;/td&gt;
      &lt;td&gt;un salto (n=25)&lt;/td&gt;
      &lt;td&gt;0.88&lt;/td&gt;
      &lt;td&gt;0.67&lt;/td&gt;
      &lt;td&gt;0.94&lt;/td&gt;
      &lt;td&gt;0.867&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;D&lt;/td&gt;
      &lt;td&gt;un salto (n=25)&lt;/td&gt;
      &lt;td&gt;0.94&lt;/td&gt;
      &lt;td&gt;0.92&lt;/td&gt;
      &lt;td&gt;0.86&lt;/td&gt;
      &lt;td&gt;0.940&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;A&lt;/td&gt;
      &lt;td&gt;multi-hop (n=15)&lt;/td&gt;
      &lt;td&gt;0.733&lt;/td&gt;
      &lt;td&gt;0.783&lt;/td&gt;
      &lt;td&gt;0.783&lt;/td&gt;
      &lt;td&gt;0.822&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;B&lt;/td&gt;
      &lt;td&gt;multi-hop (n=15)&lt;/td&gt;
      &lt;td&gt;0.567&lt;/td&gt;
      &lt;td&gt;0.517&lt;/td&gt;
      &lt;td&gt;0.60&lt;/td&gt;
      &lt;td&gt;0.778&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;C&lt;/td&gt;
      &lt;td&gt;multi-hop (n=15)&lt;/td&gt;
      &lt;td&gt;0.50&lt;/td&gt;
      &lt;td&gt;0.50&lt;/td&gt;
      &lt;td&gt;0.55&lt;/td&gt;
      &lt;td&gt;0.778&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;D&lt;/td&gt;
      &lt;td&gt;multi-hop (n=15)&lt;/td&gt;
      &lt;td&gt;0.70&lt;/td&gt;
      &lt;td&gt;0.70&lt;/td&gt;
      &lt;td&gt;0.55&lt;/td&gt;
      &lt;td&gt;0.878&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;E&lt;/td&gt;
      &lt;td&gt;un salto (n=25)&lt;/td&gt;
      &lt;td&gt;0.90&lt;/td&gt;
      &lt;td&gt;0.70&lt;/td&gt;
      &lt;td&gt;0.91&lt;/td&gt;
      &lt;td&gt;0.873&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;E&lt;/td&gt;
      &lt;td&gt;multi-hop (n=15)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;1.00&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;0.883&lt;/td&gt;
      &lt;td&gt;0.917&lt;/td&gt;
      &lt;td&gt;0.911&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;La fila E corrió un día después que A-D, como seguimiento directo al hallazgo del planner — el detalle completo, incluida la salvedad de que ahí el planner y el generador comparten modelo, está en su propia sección más abajo.&lt;/p&gt;

&lt;p&gt;Y el veredicto de las cinco hipótesis que pre-registré antes de correr nada:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;#&lt;/th&gt;
      &lt;th&gt;Hipótesis&lt;/th&gt;
      &lt;th&gt;Resultado&lt;/th&gt;
      &lt;th&gt;Veredicto&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;H1&lt;/td&gt;
      &lt;td&gt;B ≈ A en Correctness (un salto), ±0.05&lt;/td&gt;
      &lt;td&gt;0.88 − 0.84 = 0.04&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Consistente&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H2&lt;/td&gt;
      &lt;td&gt;C ≈ B en un salto (el planner no debería aportar)&lt;/td&gt;
      &lt;td&gt;Correctness idéntico: 0.88 = 0.88&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Consistente&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H3&lt;/td&gt;
      &lt;td&gt;C &amp;gt; B con margen amplio en multi-hop&lt;/td&gt;
      &lt;td&gt;0.50 &amp;lt; 0.567 — &lt;strong&gt;C queda por debajo de B&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Refutada&lt;/strong&gt; (con planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H4&lt;/td&gt;
      &lt;td&gt;Latencia de C ≥ 3× la de B&lt;/td&gt;
      &lt;td&gt;~2.7s vs ~0.6-0.9s en un salto; 3.07s vs 0.67s en multi-hop (4.6×)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Consistente&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;H5&lt;/td&gt;
      &lt;td&gt;D ≤ C en Faithfulness&lt;/td&gt;
      &lt;td&gt;0.86 ≤ 0.94 en un salto; empate 0.55 en multi-hop&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;Consistente&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/03-eval-b-vs-c-multihop.png&quot; alt=&quot;Comparación en la consola de Amazon Bedrock entre config B y config C sobre el set multi-hop: Correctness 0.57 vs 0.50, Completeness 0.52 vs 0.50, Faithfulness 0.60 vs 0.55, Helpfulness 0.78 vs 0.78&quot; /&gt;
&lt;em&gt;Figura 3: Vista de comparación nativa de RAG evaluations, config B (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; simple) contra config C (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt;) sobre el set multi-hop. El retriever “agéntico” pierde en 3 de 4 métricas y empata en la cuarta.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Cuatro de cinco hipótesis se sostuvieron. La que se cayó es la interesante, y no se cayó por poco.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Con una salvedad de alcance sobre H3.&lt;/strong&gt; Lo que esa hipótesis evalúa es el planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;, el default. Más adelante vas a ver que con un planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; grande el patrón que H3 predecía sí aparece — y eso no la rescata, porque quedó refutada tal como la escribí y para el planner que medía. Lo que sí deja es la pregunta que persigo en el resto del artículo: ¿lo que importa es el tamaño del planner, o el hecho de que ese planner grande acabe compartiendo modelo con el generador?&lt;/p&gt;

&lt;h2 id=&quot;el-hallazgo-principal-el-planner-nunca-planeó&quot;&gt;El Hallazgo Principal: El Planner Nunca Planeó&lt;/h2&gt;

&lt;p&gt;H3 no es un “no ayudó mucho”. Es una regresión medida: en el set de preguntas donde el retriever agéntico debería lucirse, terminó &lt;strong&gt;peor&lt;/strong&gt; que el retrieval simple de un solo paso.&lt;/p&gt;

&lt;p&gt;Y tiene una causa mecánica identificada, no es un misterio estadístico. Revisé el trace completo de las 80 preguntas agentic ejecutadas (configuraciones C y D, ambos sets completos). En el &lt;strong&gt;100% de los casos&lt;/strong&gt;, la estructura fue idéntica: un único step &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieval&lt;/code&gt; —la pasada especulativa con la query cruda— seguido de un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Planning&lt;/code&gt; que devolvió &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;actions&quot;: []&lt;/code&gt;. Nunca apareció un segundo step &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieval&lt;/code&gt;. Nunca apareció &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FullDocumentExpansion&lt;/code&gt;. El planner &lt;strong&gt;nunca generó una sola sub-query&lt;/strong&gt;, ni siquiera en las preguntas del set multi-hop donde ya sabía —por una verificación aparte que hice antes de correr el benchmark— que el retrieval de un solo paso no alcanzaba ambos documentos relevantes.&lt;/p&gt;

&lt;p&gt;Un ejemplo concreto. Para la pregunta &lt;em&gt;“¿qué componente de AgentCore aplica una lógica similar a ‘Keep people away from data’ de la Security pillar para ejecución de código?”&lt;/em&gt;, el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieval&lt;/code&gt; especulativo inicial trajo únicamente contenido del developer guide de AgentCore —Code Interpreter, aislamiento de sesiones, controles de seguridad— y nada del Well-Architected Framework. El paso de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Planning&lt;/code&gt; subsiguiente decidió que eso ya bastaba.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/04-trace-planning-vacio.png&quot; alt=&quot;Trace crudo de AgenticRetrieveStream mostrando un step Retrieval con status SUCCEEDED, seguido de dos eventos Planning donde el segundo devuelve actions: [] con status SUCCEEDED&quot; /&gt;
&lt;em&gt;Figura 4: Trace crudo de esta misma pregunta. Tras el único step &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieval&lt;/code&gt;, el evento &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Planning&lt;/code&gt; con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;message&quot;: &quot;Agent planning completed&quot;&lt;/code&gt; devuelve &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;actions&quot;: []&lt;/code&gt; — el planner consideró el trabajo terminado sin generar una sola sub-query.&lt;/em&gt;&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #3&lt;/strong&gt;: Si vas a medir “iteraciones” de un retriever agéntico, no cuentes steps del trace — cuenta sub-queries reales. Un step &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Planning&lt;/code&gt; que devuelve &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;actions: []&lt;/code&gt; sigue contando como una iteración en el campo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;iterations&lt;/code&gt; que expone el SDK, pero no representa ningún trabajo de descomposición. Es la diferencia entre “el planner corrió” y “el planner planificó”.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;es-esto-un-bug-fui-a-verificarlo-contra-la-fuente&quot;&gt;¿Es Esto un Bug? Fui a Verificarlo Contra la Fuente&lt;/h3&gt;

&lt;p&gt;Antes de publicar esto como hallazgo, lo contrasté contra el post oficial de AWS dedicado enteramente a esta capacidad, &lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/agentic-retrieval-for-amazon-bedrock-managed-knowledge-base/&quot; target=&quot;_blank&quot;&gt;Agentic retrieval for Amazon Bedrock Managed Knowledge Base&lt;/a&gt; — el mismo que es fuente de los números de MuSiQue que cito arriba. Tres cosas se confirman, una se matiza.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Confirma que no es un problema de mi captura de datos.&lt;/strong&gt; La documentación describe el step &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieval&lt;/code&gt;/&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FullDocumentExpansion&lt;/code&gt; como “un evento por cada sub-query ejecutada”. Mi código loggea cualquier step que llegue en el stream, sin filtrar por nombre. Si el planner hubiera descompuesto aunque fuera una sola vez en 80 preguntas, habría aparecido en el trace. Nunca apareció.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Confirma que salir temprano es comportamiento documentado, no un error.&lt;/strong&gt; La doc dice explícitamente que el planner “puede salir temprano después de que su paso de evaluación determine que la evidencia es suficiente”. El 100% de mis casos son justamente eso — un estado normal del servicio, no una falla.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Confirma los números de MuSiQue que ya cité&lt;/strong&gt;, con sus valores exactos: +22.8, +31.9 y +37.3 puntos de recall en preguntas de 2, 3 y 4 saltos, con ganancias por debajo de 5 puntos en preguntas de un solo salto.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Y matiza algo importante&lt;/strong&gt;: los dos ejemplos de código oficiales del post —single-KB y multi-KB— usan &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;foundationModelType: &quot;CUSTOM&quot;&lt;/code&gt; con un modelo explícito. &lt;strong&gt;Ninguno usa el valor por defecto (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;)&lt;/strong&gt;. El mismo post recomienda como best practice “empezar con un planner pequeño y rápido”, lo cual implica elegir un modelo a propósito, no confiar en el default.&lt;/p&gt;

&lt;p&gt;Eso me lleva a la conclusión más honesta que puedo dar: no puedo afirmar “&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; no descompone” en general. Solo puedo afirmar, con evidencia de 80 de 80 preguntas, que &lt;strong&gt;el planner gestionado por defecto —el que obtiene cualquiera que no haya leído este blog post de AWS— nunca ejerció su capacidad de descomposición en mi corpus&lt;/strong&gt;, ni siquiera cuando la evidencia recuperada era insuficiente. Que toda la documentación de referencia oficial use &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; es, en sí mismo, un dato: sugiere que AWS tampoco espera que el modelo gestionado descomponga de forma confiable sin que el usuario elija su propio planner.&lt;/p&gt;

&lt;h2 id=&quot;probé-la-salida-obvia-un-planner-propio&quot;&gt;Probé la Salida Obvia: Un Planner Propio&lt;/h2&gt;

&lt;p&gt;Configuré &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;foundationModelType=CUSTOM&lt;/code&gt; con Claude Haiku 4.5 como planner —un modelo “pequeño y rápido”, justo lo que recomienda AWS, y distinto tanto del generador (Sonnet 4.6) como del juez (Nova Pro), para no contaminar ninguno de los dos roles.&lt;/p&gt;

&lt;p&gt;Guardé esta corrida por separado; no reemplaza los resultados oficiales de la configuración C, que siguen siendo con el planner gestionado, porque es lo que el diseño del benchmark mide a propósito.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sí cambió algo.&lt;/strong&gt; Con Haiku 4.5 como planner, 3 de las 15 preguntas del set multi-hop mostraron &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;planning_actions &amp;gt; 0&lt;/code&gt; — el planner generó sub-queries reales, algo que nunca pasó ni una sola vez en las 80 preguntas con el planner gestionado. En el set de un salto, 0 de 25 descompusieron, lo cual es coherente: ahí no hace falta.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Pero no cambió lo que de verdad importaba.&lt;/strong&gt; Las 5 preguntas cross-document donde el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; simple demostrablemente fallaba en traer evidencia de ambos documentos —confirmé por separado que el contenido faltante sí estaba bien indexado, no era un problema de ingesta— &lt;strong&gt;siguieron trayendo un solo documento, exactamente igual que con el planner gestionado&lt;/strong&gt;. El planner CUSTOM descompuso preguntas que ya tenían evidencia suficiente en una sola pasada, y no tocó las que genuinamente necesitaban las dos fuentes.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #4&lt;/strong&gt;: Cambiar de planner gestionado a uno propio no es un botón mágico que arregla el multi-hop cross-document, al menos con un modelo “pequeño y rápido” como recomienda AWS. El resultado publicable, con lo que tengo hasta aquí, es: &lt;strong&gt;cambiar el planner ayuda a que el planner trabaje, no garantiza que trabaje en las preguntas correctas.&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Quedaba una pregunta obvia sin responder: ¿y si el planner no es solo distinto, sino &lt;em&gt;grande&lt;/em&gt;? La probé, y el resultado me obligó a reescribir esta sección dos veces.&lt;/p&gt;

&lt;h2 id=&quot;subí-de-categoría-un-planner-grande-y-una-colisión-de-roles-que-hay-que-nombrar&quot;&gt;Subí de Categoría: Un Planner Grande (Y una Colisión de Roles que Hay que Nombrar)&lt;/h2&gt;

&lt;p&gt;El blog oficial de AWS menciona dos candidatos como planner “grande”: Claude Sonnet 4.6 y Amazon Nova Premier. Antes de correr nada, verifiqué cuál seguía siendo viable contra la cuenta real, no contra la doc — y encontré un problema.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/05-nova-premier-legacy-eol.png&quot; alt=&quot;Tarjeta de Nova Premier en el catálogo de modelos de Amazon Bedrock mostrando la etiqueta Legacy&quot; /&gt;
&lt;em&gt;Figura 5: Nova Premier aparece marcado &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Legacy&lt;/code&gt; en el catálogo de modelos. Verificado con más detalle: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;startOfLifeTime=2025-04-30&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;legacyTime=2026-03-13&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;endOfLifeTime=2026-09-14&lt;/code&gt; — doce días después de esta sesión.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Nova Premier queda descartado no por preferencia de diseño, sino porque cualquiera que intente reproducir este benchmark después del 14 de septiembre no podría usarlo aunque quisiera. Eso me dejó una sola alternativa “grande” citada por AWS: &lt;strong&gt;Sonnet 4.6, el mismo modelo que ya uso como generador constante en A, B, C y D&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Aquí hay que ser explícito sobre lo que esto rompe: mi propia regla de diseño para la corrida con Haiku fue mantener el planner aislado del generador y del juez, precisamente para no contaminar ningún rol. Config E rompe esa regla a propósito, documentada como desviación, no como descuido. El resultado que sigue no se puede leer como “planner grande puro” — hay que leerlo como “planner grande que además es el mismo modelo que genera la respuesta después”.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Con esa salvedad ya puesta sobre la mesa, los números:&lt;/strong&gt;&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt; &lt;/th&gt;
      &lt;th&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt; (C)&lt;/th&gt;
      &lt;th&gt;Haiku 4.5 (CUSTOM, exploratorio)&lt;/th&gt;
      &lt;th&gt;Sonnet 4.6 (E)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Set un salto, preguntas con sub-queries reales&lt;/td&gt;
      &lt;td&gt;0/25&lt;/td&gt;
      &lt;td&gt;0/25&lt;/td&gt;
      &lt;td&gt;4/25&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Set multi-hop, preguntas con sub-queries reales&lt;/td&gt;
      &lt;td&gt;0/15&lt;/td&gt;
      &lt;td&gt;3/15&lt;/td&gt;
      &lt;td&gt;8/15&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Sonnet 4.6 descompuso casi el triple de veces que Haiku. De las 5 preguntas cross-document que ni &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt; ni Haiku resolvían (b04, b08, b09, b11, b14), verificado buscando vocabulario específico del Well-Architected Framework en los chunks recuperados:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;b04 y b14 se corrigen&lt;/strong&gt; — ahora sí traen contenido del WAF.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;b08 mejora parcialmente&lt;/strong&gt; — algo de WAF, no tanto como las anteriores.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;b09 y b11 siguen sin el lado que faltaba&lt;/strong&gt; — b09 incluso generó una sub-query, pero no hacia el documento correcto; b11 ni siquiera descompuso.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/06-eval-e-example-b14-correctness.png&quot; alt=&quot;Vista de la conversación 14 del eval job de config E en la consola de Bedrock: la pregunta cruza el principio Maximize utilization del Well-Architected Framework con el modo Instances de AgentCore Runtime, la respuesta cita los pasajes 11 y 13, y la columna de Correctness marca 1&quot; /&gt;
&lt;em&gt;Figura 6: b14 resuelta con el planner Sonnet 4.6. La pregunta cruza el principio de sostenibilidad &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Maximize utilization&lt;/code&gt; del Well-Architected Framework con el modo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Instances&lt;/code&gt; de AgentCore Runtime — dos documentos distintos. La respuesta cita los pasajes recuperados 11 y 13, coincide con el ground truth, y el juez le da Correctness 1.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Es decir: un planner más grande descompone más, pero no garantiza que descomponga &lt;em&gt;bien&lt;/em&gt;. Dos de cinco preguntas problemáticas siguen rotas incluso con el modelo más capaz que pude probar.&lt;/p&gt;

&lt;p&gt;Y el eval job con Nova Pro, mismas 4 métricas:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/managed-kb-vs-chunking/07-eval-c-setb-vs-e-setb-metrics.png&quot; alt=&quot;Gráfico de radar de la consola de Bedrock comparando el eval job de config C contra el de config E sobre el set multi-hop, con el polígono de E extendiéndose más allá del de C en Correctness, Completeness, Helpfulness y Faithfulness&quot; /&gt;
&lt;em&gt;Figura 7: Comparación nativa de los dos eval jobs sobre el set multi-hop. El área de E domina a C en las cuatro métricas medidas, con la brecha más ancha en Correctness. Los demás ejes del radar quedan en 0 porque esos evaluadores no formaban parte del job.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;En el set de un salto la diferencia es pequeña (0.90 vs 0.88 de Correctness), consistente con H2: un planner, del tamaño que sea, no debería aportar mucho cuando un solo paso ya alcanza. En el set multi-hop el salto es grande: Correctness pasa de 0.50 (C) a &lt;strong&gt;1.00&lt;/strong&gt; (E) — por encima incluso de B (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; simple, 0.567) y de D (planner &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt; + generación del servicio, 0.70).&lt;/p&gt;

&lt;h3 id=&quot;es-real-o-suerte-de-una-sola-tirada&quot;&gt;¿Es Real, o Suerte de una Sola Tirada?&lt;/h3&gt;

&lt;p&gt;Antes de publicar un salto de esa magnitud, repetí la corrida completa de C y E sobre el set multi-hop al día siguiente — mismas 15 preguntas, mismo corpus, mismos modelos, pipeline de retrieval, generación y evaluación corrido de cero, con su propio job de evaluación independiente.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt; &lt;/th&gt;
      &lt;th&gt;Correctness&lt;/th&gt;
      &lt;th&gt;Completeness&lt;/th&gt;
      &lt;th&gt;Faithfulness&lt;/th&gt;
      &lt;th&gt;Helpfulness&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;C, corrida 1&lt;/td&gt;
      &lt;td&gt;0.500&lt;/td&gt;
      &lt;td&gt;0.500&lt;/td&gt;
      &lt;td&gt;0.550&lt;/td&gt;
      &lt;td&gt;0.778&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;C, corrida 2&lt;/td&gt;
      &lt;td&gt;0.467&lt;/td&gt;
      &lt;td&gt;0.500&lt;/td&gt;
      &lt;td&gt;0.583&lt;/td&gt;
      &lt;td&gt;0.767&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;E, corrida 1&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;1.000&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;0.883&lt;/td&gt;
      &lt;td&gt;0.917&lt;/td&gt;
      &lt;td&gt;0.911&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;E, corrida 2&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;1.000&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;0.867&lt;/td&gt;
      &lt;td&gt;0.867&lt;/td&gt;
      &lt;td&gt;0.922&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;El resultado sostiene. Correctness de E salió exactamente 1.00 en las dos corridas independientes — no es un artefacto de una tirada con suerte. C se mantiene bajo en ambas, con una diferencia de 0.033 entre corridas que es ruido normal de juez, no una tendencia. La brecha entre C y E en Correctness es estable; las otras tres métricas varían un poco más entre corridas (hasta 0.05) pero sin cruzar nunca la brecha entre configuraciones.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #5&lt;/strong&gt;: Un salto de 0.50 a 1.00 en una sola corrida de 15 preguntas es exactamente el tipo de número que invita a sospechar de un artefacto — un promedio inflado por registros descartados, un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;null_result&lt;/code&gt; mal contado. Antes de publicar cualquier salto así de grande, repite la corrida completa de cero. Si no sostiene, era ruido. Si sostiene, como en este caso, tienes evidencia real de que vale la pena reportar con confianza.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;La lectura honesta, con todas sus salvedades:&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;N=15 sigue siendo un set chico.&lt;/strong&gt; El patrón se repite en 2 corridas, pero eso no reemplaza un N mayor. La dirección del efecto está bien sostenida; los valores exactos de Completeness, Faithfulness y Helpfulness tienen más ruido de corrida en corrida que Correctness.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;El planner y el generador comparten modelo&lt;/strong&gt;, la desviación ya declarada arriba. No puedo descartar que parte de la ganancia venga de que Sonnet 4.6, como planner, “sepa mejor qué se le va a preguntar a sí mismo después” — un efecto de auto-consistencia, no necesariamente de mejor razonamiento de descomposición en abstracto.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;No cierra el problema por completo.&lt;/strong&gt; b09 y b11 siguen sin resolverse incluso con el planner más capaz que pude probar — la ganancia es real, pero parcial: 2 de 5 preguntas arregladas, 1 parcial, 2 sin cambio.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;La comparación limpia (Nova Premier) no está disponible&lt;/strong&gt; por la fecha de EOL. Esta corrida no puede aislar “planner más grande” de “planner que además es el generador” — esa separación hubiera requerido un tercer modelo grande sin ese conflicto de rol.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;&lt;strong&gt;La conclusión que sí sostiene la evidencia:&lt;/strong&gt; un planner CUSTOM más grande que Haiku descompone más veces (8/15 contra 3/15 en el set multi-hop) y, cuando descompone hacia el lado correcto, mueve las métricas de forma sustancial — algo que Haiku nunca llegó a demostrar. Lo que no puedo separar limpiamente, con este diseño, es cuánto de esa ganancia es “modelo más capaz” y cuánto es “mismo modelo que ya genera la respuesta final”.&lt;/p&gt;

&lt;h2 id=&quot;lo-que-cambió-desde-abril-y-lo-que-no&quot;&gt;Lo Que Cambió Desde Abril (Y Lo Que No)&lt;/h2&gt;

&lt;p&gt;Una afirmación de abril quedó desactualizada, y dos supuestos con los que arranqué este benchmark resultaron equivocados. Los tres se corrigen acá.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude Sonnet 4.6 ya está en la allowlist de jueces&lt;/strong&gt; para evaluación RAG/KB específicamente. En abril tuve que usar Nova Pro por esa restricción, así que dejé la nota de actualización correspondiente en el &lt;a href=&quot;/chunking-benchmark.html&quot; target=&quot;_blank&quot;&gt;artículo original&lt;/a&gt; en vez de dejar el dato colgado allá. Aun así, mantuve Nova Pro como juez en este benchmark: el diseño pide un juez cross-family como control de imparcialidad independiente, para evitar el sesgo de auto-preferencia conocido en LLM-as-judge cuando el juez comparte familia con el generador (que sigue siendo Sonnet 4.6 en A, B y C). La disponibilidad nueva no cambia esa lógica de diseño.&lt;/p&gt;

&lt;p&gt;Los otros dos son correcciones a mi propio research previo, no a lo publicado en abril.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;foundationModelType&lt;/code&gt; acepta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt;&lt;/strong&gt;, con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MANAGED&lt;/code&gt; como default. Esto no estaba claro en la primera revisión de la documentación pública que hice antes de ejecutar — solo se documentaban ejemplos con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt;. Confirmado tanto contra la referencia de API actualizada como contra el shape real de botocore en la cuenta.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La primera versión de boto3/botocore que soporta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; es la 1.43.32&lt;/strong&gt; — esa release lanzó la operación y “Managed Knowledge Bases” juntos, en el mismo commit de API. El Python global de mi máquina traía una versión anterior; tuve que aislar el proyecto en un virtualenv propio.&lt;/p&gt;

&lt;h2 id=&quot;tabla-de-decisión&quot;&gt;Tabla de Decisión&lt;/h2&gt;

&lt;p&gt;Con los datos en la mano, esto es lo que le diría hoy a alguien evaluando esta migración:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Tu situación&lt;/th&gt;
      &lt;th&gt;Recomendación&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;RAG de producción con preguntas mayormente de un solo salto&lt;/td&gt;
      &lt;td&gt;Migra a Managed KB con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; simple. La calidad empata con una configuración manual bien afinada, y te ahorras la operación del vector store.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Tu corpus tiene archivos grandes que rompen chunking manual (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt;)&lt;/td&gt;
      &lt;td&gt;Managed KB resuelve esto de forma directa vía Smart Parsing. Es la ganancia más clara y menos discutible de este benchmark.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Preguntas multi-hop o comparativas frecuentes&lt;/td&gt;
      &lt;td&gt;No actives &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; con el planner por defecto sin probarlo primero contra tu propio corpus. En mi caso fue peor que no usarlo.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Vas a usar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; de todas formas&lt;/td&gt;
      &lt;td&gt;Configura &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;foundationModelType=CUSTOM&lt;/code&gt; con un modelo explícito desde el día uno — nunca dejes el default en producción sin haberlo validado.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Vas a elegir un planner CUSTOM&lt;/td&gt;
      &lt;td&gt;Prueba con un modelo grande antes de conformarte con uno pequeño. En mi benchmark, Haiku 4.5 descompuso poco y mal; Sonnet 4.6 descompuso casi el triple y arregló 2 de 5 preguntas problemáticas, con 1 más parcialmente. La latencia y el costo adicional de un planner más grande pueden justificarse si tu caso de uso tiene preguntas genuinamente multi-hop.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Vas a usar el mismo modelo como planner y como generador&lt;/td&gt;
      &lt;td&gt;Es válido, y en mi benchmark funcionó bien — pero no asumas que el resultado aísla “planner grande” de “planner que sabe qué se va a preguntar a sí mismo”. Si tienes forma de probar un modelo grande &lt;em&gt;distinto&lt;/em&gt; de tu generador, hazlo antes de generalizar la recomendación a tu arquitectura.&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;lo-que-queda-pendiente&quot;&gt;Lo Que Queda Pendiente&lt;/h2&gt;

&lt;p&gt;Este benchmark, como el de abril, tiene scope acotado a propósito:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Aislar tamaño de planner de colisión de rol.&lt;/strong&gt; Config E usa Sonnet 4.6 como planner y como generador a la vez. La separación limpia hubiera sido un modelo grande &lt;em&gt;distinto&lt;/em&gt; de ambos — Nova Premier era la única opción citada por AWS, y quedó fuera de alcance por su fecha de fin de vida (14 de septiembre de 2026).&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;N mayor en el set multi-hop.&lt;/strong&gt; 15 preguntas, aunque replicadas en dos corridas, siguen siendo pocas para intervalos de confianza serios.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Multi-KB routing&lt;/strong&gt;, la otra capacidad central de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; que no toqué aquí — este benchmark usó una sola Managed KB en todas las configuraciones.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Costo por consulta comparado entre planners.&lt;/strong&gt; Este benchmark mide calidad y latencia, no costo. Y la pregunta que queda abierta es bastante concreta: si un planner grande descompone casi el triple de veces, ¿cuánto sube la factura por consulta contra la ganancia en Correctness? Eso se responde midiendo tokens de planning por query, no mirando el gasto agregado de la cuenta.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Corpus en español&lt;/strong&gt;, fuera de scope igual que en abril.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Resolver b09 y b11&lt;/strong&gt;, las dos preguntas cross-document que ni el planner gestionado ni ningún planner CUSTOM que probé lograron resolver del todo.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Si replicas esto en tu cuenta y el planner gestionado sí descompone en tu corpus, quiero saberlo — sería evidencia de que el comportamiento depende más del tipo de contenido de lo que mis datos sugieren.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;Managed Knowledge Base no es una regresión de calidad. En retrieval simple, hace lo mismo que mi configuración manual de abril, y resuelve sin esfuerzo el problema de ingesta que en abril tumbó dos de las cinco estrategias de chunking. Si tu única pregunta es “¿pierdo calidad al dejar de administrar el chunking?”, la respuesta con estos datos es no.&lt;/p&gt;

&lt;p&gt;Pero el nombre “agentic” en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; promete algo que el planner por defecto no entrega, y que un planner mal elegido tampoco garantiza. No es marketing engañoso —AWS documenta el comportamiento de salida temprana como normal, y sus propios ejemplos de código nunca usan el default— pero sí es una trampa fácil de caer si activas la funcionalidad esperando que “sea más inteligente” sin elegir explícitamente quién hace el razonamiento. Con el planner gestionado, fue una regresión medida. Con un planner pequeño, fue descomposición real pero mal dirigida. Con un planner grande —aunque compartiera modelo con mi generador, una limpieza que no pude aislar del todo por la salida de Nova Premier— la Correctness en preguntas multi-hop se duplicó, sostenida en dos corridas independientes.&lt;/p&gt;

&lt;p&gt;La consultoría real, si trabajas con esto en producción, no es “activa el retriever agéntico”. Es “activa el retriever agéntico, elige tu propio planner —y probablemente uno más grande de lo que te da pereza probar primero—, y &lt;strong&gt;mide&lt;/strong&gt; en tu propio corpus si descompone las preguntas que de verdad lo necesitan”. Porque el rango que encontré en un mismo corpus, con la misma pregunta multi-hop, fue de “peor que no usarlo” a “el doble de bueno que usarlo sin pensar”, según quién planificara.&lt;/p&gt;

&lt;p&gt;El código completo del benchmark —Terraform, scripts numerados, las 15 preguntas multi-hop con su verificación cruzada, y los datasets BYOI— está en &lt;a href=&quot;https://github.com/codecr/mkb-vs-chunking&quot; target=&quot;_blank&quot;&gt;github.com/codecr/mkb-vs-chunking&lt;/a&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚀 &lt;strong&gt;Pro Tip Final&lt;/strong&gt;: Antes de activar cualquier feature “agéntico” en producción, pregúntate qué modelo está tomando las decisiones de planning y si ese modelo es el que tú elegiste o el que el servicio eligió por ti. Y si eliges tú, no te conformes con el primer modelo “pequeño y rápido” que sugiera la documentación — en mi benchmark, la diferencia entre un planner pequeño y uno grande fue más grande que la diferencia entre tener planner y no tenerlo.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Si te interesa el contexto completo, el &lt;a href=&quot;/chunking-benchmark.html&quot; target=&quot;_blank&quot;&gt;benchmark original de chunking&lt;/a&gt; sigue siendo la referencia para configuraciones manuales. Y si lo que quieres es exponer una Managed KB como herramienta MCP para tus agentes, ese camino pasa por &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-gateway-target.html&quot; target=&quot;_blank&quot;&gt;AgentCore Gateway como target de Knowledge Base&lt;/a&gt; —el conector expone &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgenticRetrieveStream&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Retrieve&lt;/code&gt; como tools MCP— y mi artículo sobre &lt;a href=&quot;/bedrock-mcp.html&quot; target=&quot;_blank&quot;&gt;Amazon Bedrock + MCP&lt;/a&gt; da el contexto del protocolo.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! Si replicaste esto o probaste un planner distinto, cuéntamelo en los comentarios — con este hallazgo en particular, entre más ojos lo verifiquen, mejor. 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/agentic-retrieval-for-amazon-bedrock-managed-knowledge-base/&quot; target=&quot;_blank&quot;&gt;Blog: Agentic retrieval for Amazon Bedrock Managed Knowledge Base&lt;/a&gt; — fuente de los números de MuSiQue y de los ejemplos con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;foundationModelType=CUSTOM&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/build-enterprise-search-for-agents-with-amazon-bedrock-managed-knowledge-base/&quot; target=&quot;_blank&quot;&gt;Blog: Build enterprise search for agents with Amazon Bedrock Managed Knowledge Base&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html&quot; target=&quot;_blank&quot;&gt;API Reference: AgenticRetrieveStream&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-test-agentic-retrieve.html&quot; target=&quot;_blank&quot;&gt;Use agentic retrieval to query a knowledge base&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-build-managed.html&quot; target=&quot;_blank&quot;&gt;Build a managed knowledge base&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-create.html&quot; target=&quot;_blank&quot;&gt;Create a managed knowledge base&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-managed-customize-ingestion.html&quot; target=&quot;_blank&quot;&gt;Customize ingestion for a data source (Smart Parsing por defecto)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html&quot; target=&quot;_blank&quot;&gt;Retrieve data and generate AI responses with Amazon Bedrock Knowledge Bases&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-gateway-target.html&quot; target=&quot;_blank&quot;&gt;Connect to your knowledge base through AgentCore Gateway (KB como tool MCP)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-managed-kb.html&quot; target=&quot;_blank&quot;&gt;Amazon Bedrock Managed Knowledge Bases as Connector Target&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/evaluation-kb.html&quot; target=&quot;_blank&quot;&gt;Evaluate the performance of RAG sources using Amazon Bedrock Evaluations&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-evaluation-create-randg.html&quot; target=&quot;_blank&quot;&gt;Creating a retrieve-and-generate RAG evaluation job (path BYOI)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2025/03/amazon-bedrock-rag-evaluation-generally-available/&quot; target=&quot;_blank&quot;&gt;Anuncio: Amazon Bedrock RAG Evaluation generally available (marzo 2025)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/evaluate-models-or-rag-systems-using-amazon-bedrock-evaluations-now-generally-available/&quot; target=&quot;_blank&quot;&gt;Blog: Evaluate models or RAG systems using Amazon Bedrock Evaluations — now GA&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Wed, 02 Sep 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/managed-kb-vs-chunking.html</link>
                <guid isPermaLink="true">https://gerardo.dev/managed-kb-vs-chunking.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>AgentCore</category>
                
                <category>KnowledgeBases</category>
                
                <category>RAG</category>
                
                <category>Chunking</category>
                
                <category>Evaluations</category>
                
                <category>GenAI</category>
                
                
            </item>
        
            <item>
                <title>Dejé que AWS reescribiera el prompt de mi agente DevOps: 142 sesiones, +6.2% y un p-value de 0.38</title>
                <description>&lt;h1 id=&quot;dejé-que-aws-reescribiera-el-prompt-de-mi-agente-devops-142-sesiones-62-y-un-p-value-de-038&quot;&gt;Dejé que AWS reescribiera el prompt de mi agente DevOps: 142 sesiones, +6.2% y un p-value de 0.38&lt;/h1&gt;

&lt;p&gt;Cerré el artículo de &lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;Memoria Episódica&lt;/a&gt; con una frase que me quedó dando vueltas por meses: &lt;em&gt;“hay un momento en el desarrollo de un agente en el que ya no puedes seguir mejorándolo solo con prompts”&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;En ese momento propuse una respuesta: que el agente aprenda de su propia experiencia. Pero había otra respuesta que dejé pendiente, y es bastante más incómoda: &lt;strong&gt;¿y si el problema no es que el prompt no alcance, sino que yo no soy la persona indicada para seguir escribiéndolo?&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Piénsalo un segundo. Cuando ajustas el system prompt de un agente en producción, ¿en qué te basas? En los tres o cuatro casos que recuerdas que salieron mal. En la intuición de que “esta instrucción debería ayudar”. En un puñado de pruebas manuales que hiciste después del cambio. Nunca en los 200 traces reales que están sentados en CloudWatch esperando que alguien los lea.&lt;/p&gt;

&lt;p&gt;Amazon Bedrock AgentCore Optimization propone exactamente eso: que un modelo lea los traces por ti, encuentre el patrón de fallo, y te devuelva un prompt mejorado. Y después —esta es la parte que me interesó de verdad— que valides ese cambio con un A/B test sobre tráfico real, con significancia estadística, antes de comprometerlo.&lt;/p&gt;

&lt;p&gt;Lo corrí completo sobre el mismo agente DevOps de la serie. Esto es lo que pasó: la recomendación fue sorprendentemente buena, el A/B test me dijo que &lt;strong&gt;no había evidencia suficiente para declararla ganadora&lt;/strong&gt;, y en el camino fui anotando cada trampa que la documentación no menciona — están repartidas como ProTips a lo largo del artículo. Todo el código está en &lt;a href=&quot;https://github.com/codecr/agentcore-optimization-loop&quot; target=&quot;_blank&quot;&gt;github.com/codecr/agentcore-optimization-loop&lt;/a&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #1&lt;/strong&gt;: Ojo con el estado de madurez, porque cambió hace poco y buena parte de lo que vas a encontrar escrito está desactualizado. Según las &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/release-notes.html&quot; target=&quot;_blank&quot;&gt;release notes&lt;/a&gt;, el Agent Optimization Loop entró en public preview en &lt;strong&gt;abril de 2026&lt;/strong&gt;, pero &lt;strong&gt;Recommendations, A/B Testing y Batch Evaluations llegaron a GA en junio de 2026&lt;/strong&gt;. Lo único que sigue en preview es &lt;strong&gt;Failure Insights&lt;/strong&gt;, y AgentCore Evaluations —la base sobre la que todo esto se apoya— es GA desde &lt;strong&gt;marzo de 2026&lt;/strong&gt;. Esto ya no es un juguete de preview: es superficie de producción. Dicho eso, GA no significa completo. En mi cuenta las llamadas a estas APIs &lt;strong&gt;no aparecieron en el event history de CloudTrail&lt;/strong&gt;, y aunque la documentación tiene páginas dedicadas de CloudTrail para Gateway, Runtime y Harness, no encontré la equivalente para optimization. No afirmo que el soporte no exista; afirmo que no lo vi. Si tu proceso exige &lt;em&gt;audit trail&lt;/em&gt; de quién cambió la configuración del agente, compruébalo en tu cuenta antes de asumirlo, porque ese es justamente uno de los argumentos de venta de los configuration bundles.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: Verificado a inicios de septiembre — &lt;strong&gt;Failure Insights sigue en public preview&lt;/strong&gt;, sin cambio de estado desde que escribí esto. Lo que sí cambió es el nombre y el alcance: la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/insights.html&quot; target=&quot;_blank&quot;&gt;documentación actual&lt;/a&gt; lo presenta como &lt;strong&gt;“AgentCore insights”&lt;/strong&gt;, con tres tipos de análisis en vez de uno — failure analysis (lo que este artículo describe como Failure Insights), user intent analysis, y execution/trajectory summary. Los tres siguen en public preview y se configuran desde la misma sección de Optimizations en la consola. Nada de lo que digo sobre Failure Insights más abajo cambió de comportamiento, solo el nombre bajo el que AWS lo agrupa.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;el-desafío-el-ciclo-que-nadie-cierra&quot;&gt;El Desafío: El Ciclo que Nadie Cierra&lt;/h2&gt;

&lt;p&gt;La mayoría de los equipos que conozco tienen las dos primeras piezas del ciclo y les falta la tercera.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Observan&lt;/strong&gt;: tienen observabilidad, traces en CloudWatch, dashboards. &lt;strong&gt;Evalúan&lt;/strong&gt;: si ya leyeron el artículo de &lt;a href=&quot;/bedrock-evaluations.html&quot; target=&quot;_blank&quot;&gt;AgentCore Evaluations&lt;/a&gt;, tienen scores de calidad corriendo sobre tráfico real. Pero cuando llega el momento de &lt;strong&gt;mejorar&lt;/strong&gt;, el ciclo se rompe y vuelve a ser artesanal: alguien abre el archivo del prompt, escribe unas líneas nuevas basado en su lectura personal de los datos, y despliega esperando lo mejor.&lt;/p&gt;

&lt;p&gt;AgentCore Optimization ataca ese último tramo con tres capacidades que trabajan juntas:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Recommendations&lt;/strong&gt; — Le apuntas a los traces de tu agente en CloudWatch Logs y le dices cuál evaluador quieres optimizar. El servicio analiza los patrones de fallo y te devuelve un system prompt optimizado (o descripciones de tools más precisas), con una explicación de qué cambió y por qué.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Configuration bundles&lt;/strong&gt; — Snapshots inmutables y versionados de la configuración de tu agente: system prompts, model IDs, descripciones de tools. La analogía con git no es mía ni es aproximada: es literalmente el modelo de datos. Cada versión lleva &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;commitMessage&lt;/code&gt;, y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;parentVersionIds&lt;/code&gt; está documentado como &lt;em&gt;“los commits regulares tienen un solo padre; los merge commits tienen dos: el padre de la rama destino y el de la rama origen”&lt;/em&gt;. Hay &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;branchName&lt;/code&gt;, que si lo omites hereda la rama del padre o cae en una por defecto llamada &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mainline&lt;/code&gt;&lt;/strong&gt;. Y el CLI expone &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore cb versions&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore cb diff --from &amp;lt;v1&amp;gt; --to &amp;lt;v2&amp;gt;&lt;/code&gt;. Todo eso está en la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/configuration-bundles-update.html&quot; target=&quot;_blank&quot;&gt;referencia de UpdateConfigurationBundle&lt;/a&gt; y en el tipo &lt;a href=&quot;https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrockagentcore-configurationbundle-versionlineagemetadata.html&quot; target=&quot;_blank&quot;&gt;VersionLineageMetadata de CloudFormation&lt;/a&gt;. Desacoplan el comportamiento del agente del código, así que puedes cambiar cómo responde sin redesplegar. Son opcionales: también puedes validar desplegando a un runtime endpoint separado.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A/B testing&lt;/strong&gt; — Divide el tráfico en vivo entre dos variantes a través del AgentCore Gateway. La asignación es &lt;em&gt;sticky&lt;/em&gt; por session ID, el online evaluation puntúa cada sesión, y el servicio calcula media, cambio porcentual, p-value, intervalo de confianza y una bandera de significancia.&lt;/p&gt;

&lt;p&gt;La promesa junta es un loop que se retroalimenta: los traces de la variante ganadora se vuelven la nueva línea base para la siguiente recomendación.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #2&lt;/strong&gt;: El evaluador que elijas &lt;strong&gt;es&lt;/strong&gt; la función objetivo de la optimización. El optimizador empuja el prompt hacia lo que ese evaluador puntúa alto, con todo lo bueno y lo malo que eso implica. Si tu agente tiene una tarea clara que completar, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.GoalSuccessRate&lt;/code&gt; es la señal correcta. Si es más abierto y te importa la calidad de la interacción, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.Helpfulness&lt;/code&gt; encaja mejor. Elegir mal aquí no te da un mal prompt: te da un prompt excelente para la métrica equivocada.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;el-punto-de-partida-portar-el-agente-y-por-qué-no-había-alternativa&quot;&gt;El Punto de Partida: Portar el Agente (y Por Qué No Había Alternativa)&lt;/h2&gt;

&lt;p&gt;Aquí viene la primera lección dura del ejercicio, y llegó antes de escribir una sola línea de código nuevo.&lt;/p&gt;

&lt;p&gt;El agente DevOps de la serie de Memory era una aplicación Flask local que llamaba a Bedrock Converse directo. Funcionaba perfecto para lo que necesitaba ese artículo. Pero &lt;strong&gt;no puede entrar al loop de optimización&lt;/strong&gt;, y por dos razones que no se negocian:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Recommendations y online evaluation leen traces desde CloudWatch bajo la convención de service name &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{RuntimeName}.DEFAULT&lt;/code&gt;. Eso implica un agente desplegado en &lt;strong&gt;AgentCore Runtime con observabilidad&lt;/strong&gt;, o un framework soportado (Strands Agents, o LangGraph con instrumentación de OpenTelemetry/OpenInference).&lt;/li&gt;
  &lt;li&gt;Para que el A/B test pueda intercambiar el system prompt entre variantes, el agente tiene que &lt;strong&gt;leer su prompt desde el configuration bundle en runtime&lt;/strong&gt;, no tenerlo hardcodeado.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Así que “reusar mi agente” en realidad significó portarlo a Strands sobre AgentCore Runtime. No fue un retoque: fue un port.&lt;/p&gt;

&lt;h3 id=&quot;las-tools-con-el-decorador-de-strands&quot;&gt;Las Tools con el Decorador de Strands&lt;/h3&gt;

&lt;p&gt;Al portar a Strands, las tools se cablean con el decorador &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@tool&lt;/code&gt; y el framework se encarga del resto:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nd&quot;&gt;@tool&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;describe_rds_metrics&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instance_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;period_minutes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;30&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Obtiene métricas de CloudWatch de una instancia RDS: conexiones, CPU,
    memoria libre y latencias de lectura/escritura. Úsala cuando el incidente
    involucre timeouts, saturación o lentitud de base de datos.

    Args:
        instance_id: Identificador de la instancia RDS (ej. prod-db-1).
        period_minutes: Ventana de tiempo hacia atrás en minutos.
    &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;end_time&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;datetime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;now&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;timezone&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;utc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;start_time&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;end_time&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;timedelta&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;minutes&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;period_minutes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;metrics&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;DatabaseConnections&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;CPUUtilization&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;FreeableMemory&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
               &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;ReadLatency&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;WriteLatency&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;metrics&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;try&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_cloudwatch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get_metric_statistics&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;Namespace&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;AWS/RDS&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;MetricName&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;Dimensions&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;DBInstanceIdentifier&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Value&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;instance_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}],&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;StartTime&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;start_time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;EndTime&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;end_time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;Period&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;300&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;Statistics&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Average&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Maximum&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Datapoints&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;latest&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;sorted&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Datapoints&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;lambda&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;x&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;x&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Timestamp&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;])[&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;FreeableMemory&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                    &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;_GB&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;round&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;latest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Average&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1024&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;**&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;elif&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Latency&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                    &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;_ms&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;round&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;latest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Average&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1000&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                    &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;round&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;latest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Average&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;except&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;Exception&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# Si el rol del runtime no tiene permisos, esto aflora como dato, no como caída
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Error: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Ese detalle del docstring no es cosmético: en Strands, la descripción de la tool &lt;strong&gt;es&lt;/strong&gt; lo que ve el modelo para decidir si la usa. Es literalmente el artefacto que optimiza la recomendación de tool descriptions.&lt;/p&gt;

&lt;h3 id=&quot;el-hook-que-lee-el-bundle&quot;&gt;El Hook que Lee el Bundle&lt;/h3&gt;

&lt;p&gt;La pieza clave del port es el hook &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BeforeModelCallEvent&lt;/code&gt;. Se dispara antes de cada llamada al modelo y aplica el system prompt del bundle activo:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;_resolve_system_prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Lee el system prompt base del config bundle; si no hay, usa el DEFAULT.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;try&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;config&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BedrockAgentCoreContext&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get_config_bundle&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;system_prompt&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DEFAULT_SYSTEM_PROMPT&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;config&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DEFAULT_SYSTEM_PROMPT&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;except&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;Exception&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;# Fallback defensivo: nunca dejamos al agente sin prompt
&lt;/span&gt;        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;DEFAULT_SYSTEM_PROMPT&lt;/span&gt;


&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;dynamic_config_hook&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BeforeModelCallEvent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Antes de cada llamada al modelo, aplica el prompt del bundle activo.
    Durante un A/B test, el Gateway propaga por baggage qué versión de bundle
    corresponde a esta sesión (control o treatment), y aquí se materializa.
    &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;system_prompt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;_resolve_system_prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;


&lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;Agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nc&quot;&gt;BedrockModel&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DEFAULT_MODEL_ID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;TOOLS&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;system_prompt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;DEFAULT_SYSTEM_PROMPT&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;hooks&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;add_callback&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;BeforeModelCallEvent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dynamic_config_hook&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Lo elegante del diseño: &lt;strong&gt;el código del agente nunca sabe en qué variante está&lt;/strong&gt;. El Gateway asigna la sesión, inyecta la referencia del bundle vía headers de &lt;a href=&quot;https://www.w3.org/TR/baggage/&quot; target=&quot;_blank&quot;&gt;W3C Baggage&lt;/a&gt; con dos claves —&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws.agentcore.configbundle_arn&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws.agentcore.configbundle_version&lt;/code&gt;—, el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BedrockAgentCoreApp&lt;/code&gt; las parsea, resuelve la versión contra el control plane, &lt;strong&gt;cachea el resultado&lt;/strong&gt;, y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_config_bundle()&lt;/code&gt; devuelve la configuración del componente que corresponde a tu runtime ARN. Si no hay referencia de bundle en el request, devuelve un diccionario vacío y cae al default.&lt;/p&gt;

&lt;p&gt;Vale aclarar que este patrón no lo inventé: el hook &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BeforeModelCallEvent&lt;/code&gt; es exactamente &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/configuration-bundles-runtime.html&quot; target=&quot;_blank&quot;&gt;el patrón recomendado en la documentación&lt;/a&gt; para agentes Strands, y ahí están también las variantes para LangGraph, Google ADK y el SDK de OpenAI. Si necesitas aplicar más campos que el prompt —model ID, temperature, tools— la doc sugiere construir el agente por request en lugar de usar el hook. Un extra útil que descubrí leyéndola: existe &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_config_bundle_ref()&lt;/code&gt; para inspeccionar la referencia cruda (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bundle_id&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bundle_arn&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bundle_version&lt;/code&gt;), que es la forma limpia de loggear en qué variante corrió una sesión sin que el agente cambie su comportamiento por saberlo. Y para probar en local puedes pasar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;baggage=&lt;/code&gt; a mano en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;invoke_agent_runtime&lt;/code&gt;, sin montar un A/B test.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #3&lt;/strong&gt;: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_config_bundle()&lt;/code&gt; existe a partir de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore &amp;gt;= 1.8.0&lt;/code&gt;. Este piso sí está documentado: los &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/ab-testing-prereqs.html&quot; target=&quot;_blank&quot;&gt;prerrequisitos de A/B testing&lt;/a&gt; exigen “AgentCore SDK (version 1.8+)” porque el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BaggageSpanProcessor&lt;/code&gt; del SDK es el que adjunta el ARN del experimento y el nombre de la variante a los spans de OpenTelemetry. Los otros dos pisos los deduje a golpes y no fallan de forma obvia si te quedas corto: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;strands-agents[otel] &amp;gt;= 1.13.0&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;botocore[crt] &amp;gt;= 1.35.0&lt;/code&gt;. Y siempre envuelve la lectura en un try/except con defaults — si la llamada al control plane falla, la excepción se propaga y te tumba la invocación completa.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;la-decisión-de-apagar-la-memoria&quot;&gt;La Decisión de Apagar la Memoria&lt;/h3&gt;

&lt;p&gt;Tomé una decisión que vale la pena explicar porque va contra la intuición: &lt;strong&gt;durante el A/B test dejé la memoria episódica apagada&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;El motivo es puramente experimental. La inyección dinámica de episodios y reflections cambia el contexto de cada sesión según lo que la búsqueda semántica recupere en ese momento. Eso mete varianza que no tiene nada que ver con el cambio que estoy midiendo. Si control y treatment difieren en el prompt base &lt;em&gt;y además&lt;/em&gt; en qué experiencias recuperaron, ya no puedo atribuir la diferencia al prompt.&lt;/p&gt;

&lt;p&gt;Con memoria apagada, lo único que difiere entre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;C&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;T1&lt;/code&gt; es el system prompt. A/B limpio. En operación normal se enciende con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ENABLE_MEMORY=true&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🧪 &lt;strong&gt;ProTip #4&lt;/strong&gt;: Todo componente que agregue varianza por sesión —memoria episódica, RAG con recuperación dinámica, contexto de usuario— &lt;strong&gt;encarece tu A/B test en muestras&lt;/strong&gt;. No es que esté mal tenerlo encendido; es que necesitas más sesiones para separar la señal del ruido. Si tu experimento es sobre el prompt, aísla el prompt.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;implementación-paso-a-paso&quot;&gt;Implementación Paso a Paso&lt;/h2&gt;

&lt;p&gt;Todo el camino va por el AgentCore CLI, que por debajo administra un stack de CDK. Esta fue mi primera decisión de arquitectura del ejercicio y la cambié a mitad de camino: mi convención es Terraform, pero el soporte de provider para las capacidades nuevas de AgentCore va por detrás, y el CLI ya tiene comandos de primera clase para bundles, online eval y A/B tests. Peleé menos y llegué más lejos.&lt;/p&gt;

&lt;h3 id=&quot;paso-1-aprovisionar-runtime-online-eval-y-gateway&quot;&gt;Paso 1: Aprovisionar Runtime, Online Eval y Gateway&lt;/h3&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# Proyecto y runtime del agente&lt;/span&gt;
agentcore create &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; DevOpsOptimizationLoop &lt;span class=&quot;nt&quot;&gt;--no-agent&lt;/span&gt;
&lt;span class=&quot;nb&quot;&gt;cd &lt;/span&gt;DevOpsOptimizationLoop

agentcore add agent &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; devopsAgent &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--language&lt;/span&gt; Python &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--framework&lt;/span&gt; Strands &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--model-provider&lt;/span&gt; Bedrock &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--memory&lt;/span&gt; none &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--build&lt;/span&gt; CodeZip

agentcore deploy

&lt;span class=&quot;c&quot;&gt;# Online evaluation: puntúa cada sesión en vivo&lt;/span&gt;
agentcore add online-eval &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; devopsEval &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--runtime&lt;/span&gt; devopsAgent &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--evaluator&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;Builtin.GoalSuccessRate&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--sampling-rate&lt;/span&gt; 100.0 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--enable-on-create&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# Gateway y target: el A/B por config bundle rutea por aquí&lt;/span&gt;
agentcore add gateway &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; devopsGateway

agentcore add gateway-target &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; devops-diag &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--gateway&lt;/span&gt; devopsGateway &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--type&lt;/span&gt; http-runtime &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--runtime&lt;/span&gt; devopsAgent

agentcore deploy
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--sampling-rate 100.0&lt;/code&gt; es deliberado. En producción normal usarías 10% o menos por costo, pero durante un A/B test quieres que &lt;strong&gt;cada&lt;/strong&gt; sesión se evalúe: entre más muestras puntuadas, antes llegas a significancia. Lo bajas cuando termina el experimento.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/01-runtime-observability.png&quot; alt=&quot;Runtime desplegado con observabilidad: 31 sesiones y 31 invocaciones&quot; /&gt;
&lt;em&gt;Figura 1: El runtime durante la fase de línea base — 31 sesiones y 31 invocaciones. Nótese que ya hay dos versiones del runtime: cada &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore deploy&lt;/code&gt; genera un snapshot versionado, y el endpoint DEFAULT apunta a la Version 2.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Ese consumo de 0.074 vCPU-hrs y 3.4 GB-hrs para 31 invocaciones da una idea del costo de compute del runtime, que es independiente del costo de inferencia. La consola advierte que los datos de consumo pueden retrasarse hasta 60 minutos.&lt;/p&gt;

&lt;p&gt;Un detalle de bookkeeping para que los números del artículo cuadren: el contador sube a lo largo del ejercicio. El seed son 30 invocaciones, esta captura muestra 31, y el desglose de costo del final cierra en 32 porque incluye las verificaciones que hice después de tomar la pantalla.&lt;/p&gt;

&lt;h3 id=&quot;paso-2-generar-la-línea-base&quot;&gt;Paso 2: Generar la Línea Base&lt;/h3&gt;

&lt;p&gt;La recomendación necesita traces que analizar, así que hay que hacer trabajar al agente primero. Mi script recorre diez incidentes DevOps reales en varias rondas:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# 3 rondas × 10 incidentes = 30 invocaciones directas al runtime&lt;/span&gt;
./seed_traffic.sh ../../incidents.txt 3
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Los incidentes son del dominio real, no “hola mundo”: &lt;em&gt;“Estamos viendo timeouts intermitentes en checkout-api contra la instancia RDS prod-db-1”&lt;/em&gt;, &lt;em&gt;“payment-service tiene errores de conexión desde hace 10 minutos”&lt;/em&gt;, &lt;em&gt;“Aurora prod-db-1 muestra 95% de utilización de conexiones, ¿escalo o hay otra causa?”&lt;/em&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔧 &lt;strong&gt;ProTip #5&lt;/strong&gt;: Después de invocar, &lt;strong&gt;espera de 2 a 5 minutos&lt;/strong&gt; antes de lanzar la recomendación. CloudWatch necesita ingerir la telemetría, y si disparas antes el servicio simplemente no encuentra traces suficientes. También necesitas &lt;strong&gt;Transaction Search habilitado&lt;/strong&gt; en CloudWatch — y ahí hay una trampa que me costó tiempo, ver el ProTip #10.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Con el tráfico corriendo, el dashboard de online evaluation empezó a mostrar la línea base:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/02-goal-success-baseline.png&quot; alt=&quot;Widget de Builtin.GoalSuccessRate mostrando 0.826 de score promedio&quot; /&gt;
&lt;em&gt;Figura 2: Línea base del evaluador &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.GoalSuccessRate&lt;/code&gt; — score promedio de 0.826 en esa ventana, con la distribución Yes/No que caracteriza a este evaluador binario a nivel de sesión.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Un score de 0.826 no es malo. Y aquí está la trampa conceptual del ejercicio completo, así que la dejo dicha desde ya: &lt;strong&gt;entre más alto arranca tu agente, más difícil es demostrar estadísticamente que lo mejoraste&lt;/strong&gt;. Volveré sobre esto.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;📊 &lt;strong&gt;ProTip #6&lt;/strong&gt;: No mezcles el score del widget de online evaluation con los números del A/B test. Son ventanas de tiempo, muestras y contextos distintos. En mi corrida, el widget marcó 0.826 sobre la ventana de línea base, la recomendación reportó 16 éxitos de 20 traces analizados (0.80), y el A/B test midió 0.94 para el control sobre 103 sesiones. Los tres números son correctos y ninguno es el otro. Cada vez que cites uno, cita también de qué pantalla salió y sobre cuántas sesiones — sin eso, cualquiera de los tres puede pasar por “el score del agente”.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;paso-3-pedir-la-recomendación&quot;&gt;Paso 3: Pedir la Recomendación&lt;/h3&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;agentcore run recommendation &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--type&lt;/span&gt; system-prompt &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--run&lt;/span&gt; devops-prompt-rec &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--runtime&lt;/span&gt; devopsAgent &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--evaluator&lt;/span&gt; Builtin.GoalSuccessRate &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--prompt-file&lt;/span&gt; ../../bundles/control_prompt.txt &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--lookback&lt;/span&gt; 7
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Por debajo, el CLI resuelve los ARNs de log group y los service names desde la configuración del runtime, y arma una llamada equivalente a esta:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;start_recommendation&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;devops-prompt-rec&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;nb&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;SYSTEM_PROMPT_RECOMMENDATION&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;recommendationConfig&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;systemPromptRecommendationConfig&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;systemPrompt&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt_actual&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;agentTraces&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;cloudwatchLogs&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;logGroupArns&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&amp;lt;log-group-arn&amp;gt;&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;# ARNs, no nombres
&lt;/span&gt;                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;serviceNames&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;devopsAgent.DEFAULT&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# verifica el valor real
&lt;/span&gt;                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;startTime&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;now&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;timedelta&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;days&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;7&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;endTime&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;now&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;evaluationConfig&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;evaluators&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;evaluatorArn&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;clientToken&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;uuid&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;uuid4&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()),&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;No copies ese &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;serviceNames&lt;/code&gt; a ciegas. El CLI lo resuelve por ti, pero si armas la llamada a mano tienes que usar el nombre literal con el que el runtime emite telemetría, y ese nombre carga los prefijos y sufijos que el proyecto le agrega — en mi cuenta la consola muestra el runtime como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DevOpsOptimizationLoop_dev&lt;/code&gt;, no como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;devopsAgent&lt;/code&gt;. Si te equivocas aquí no obtienes un error: obtienes cero traces y una recomendación que nunca arranca, que es el peor modo de falla posible para depurar.&lt;/p&gt;

&lt;p&gt;Y aquí llegó la sorpresa agradable del ejercicio.&lt;/p&gt;

&lt;h2 id=&quot;resultados-qué-encontró-el-optimizador&quot;&gt;Resultados: Qué Encontró el Optimizador&lt;/h2&gt;

&lt;p&gt;El servicio analizó &lt;strong&gt;veinte trayectorias: dieciséis éxitos y cuatro fallos&lt;/strong&gt;. Veinte no es el número de traces que sembré, es el máximo que el servicio muestrea por recomendación — volveré sobre eso. Y en esos cuatro fallos encontró un patrón que yo no había visto, a pesar de que los datos llevaban ahí toda la tarde.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/03-recommendation-explanation.png&quot; alt=&quot;Explicación del optimizador sobre el patrón de fallo detectado&quot; /&gt;
&lt;em&gt;Figura 3: La pestaña Explanation del resultado — el optimizador identifica un único patrón dominante de fallo, cita los cuatro traces específicos, y explica en qué se diferenciaban las trayectorias exitosas que enfrentaron el mismo error de herramienta.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;El razonamiento, resumido: los cuatro traces fallidos compartían la misma estructura. El agente llamaba a las herramientas contra &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prod-db-1&lt;/code&gt;, recibía un error &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DBInstanceNotFound&lt;/code&gt; o métricas nulas en todos los campos de CloudWatch, y entonces respondía &lt;strong&gt;pidiendo el identificador correcto de la instancia sin entregar ningún contenido diagnóstico&lt;/strong&gt; sobre los síntomas que el usuario ya había descrito.&lt;/p&gt;

&lt;p&gt;(Un paréntesis honesto: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;prod-db-1&lt;/code&gt; e &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;i-0abc123def456&lt;/code&gt; son identificadores ficticios de mi laboratorio. Esos errores de herramienta son &lt;em&gt;esperados&lt;/em&gt;. Lo interesante no es que fallaran, sino qué hizo el agente cuando fallaron.)&lt;/p&gt;

&lt;p&gt;Porque el optimizador también miró los traces &lt;strong&gt;exitosos que enfrentaron exactamente el mismo fallo&lt;/strong&gt; —el mismo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DBInstanceNotFound&lt;/code&gt;, los mismos campos nulos— y se comportaron distinto de forma consistente: reconocían brevemente la falla de la herramienta y luego entregaban un diagnóstico diferencial completo basado en los síntomas descritos, con queries SQL concretas, comandos bash de verificación y pasos de remediación específicos.&lt;/p&gt;

&lt;p&gt;La conclusión del optimizador me pareció una lección de diseño de agentes en sí misma: los agentes exitosos &lt;strong&gt;trataban los síntomas reportados como suficientes por sí solos&lt;/strong&gt; para generar guía accionable, sin importar si las llamadas a herramientas devolvieron datos usables. El agente fallido se detenía a pedir más datos; el exitoso trataba el error de la herramienta como un dato más.&lt;/p&gt;

&lt;p&gt;Y no se quedó en RDS. El optimizador reporta explícitamente que el mismo patrón aparecía &lt;strong&gt;también en los escenarios de EC2&lt;/strong&gt;: cuando la tool devolvía todos los campos en null, las trayectorias exitosas igual entregaban un marco diagnóstico completo cubriendo estado del agente de CloudWatch, huecos de permisos IAM, estado de la instancia y retraso de métricas. Eso es lo que le da peso al hallazgo: no detectó una anécdota de una tool, detectó un comportamiento del agente que se repite cruzando dos familias de servicio.&lt;/p&gt;

&lt;p&gt;El prompt resultante refleja eso quirúrgicamente:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/04-recommendation-diff.png&quot; alt=&quot;Diff entre el prompt original y el recomendado&quot; /&gt;
&lt;em&gt;Figura 4: Vista lado a lado del prompt original contra el recomendado. El optimizador conservó verbatim la estructura, la lista de especialidades y la metodología de cuatro pasos, y agregó dos bloques nuevos.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Lo que agregó, integrado dentro de la sección de metodología en lugar de anexado al final:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;strong&gt;REGLA CRÍTICA&lt;/strong&gt;: Cuando las herramientas fallen (errores, null, NotFound, AccessDenied), SIEMPRE entrega un diagnóstico diferencial completo basado en los síntomas del usuario. Incluye queries SQL, comandos y remediación concreta. Nunca te limites solo a pedir más datos sin ofrecer valor diagnóstico.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Y una política de confirmación que el prompt original no tenía: antes de ejecutar acciones con consecuencias reales —escalar instancias, terminar conexiones, modificar parámetros— indicar el plan y esperar confirmación explícita del usuario. Un guiño interesante a lo que cubrimos con &lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;AgentCore Policy&lt;/a&gt;, solo que aquí es una convención de prompt, no un control determinístico. No confundas una con la otra: un prompt sugiere, Cedar bloquea.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #7&lt;/strong&gt;: Las veinte trayectorias no son casualidad, son un techo. Los &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/bedrock-agentcore-limits.html&quot; target=&quot;_blank&quot;&gt;service quotas de AgentCore&lt;/a&gt; fijan &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Sessions per recommendation&lt;/code&gt; en &lt;strong&gt;20&lt;/strong&gt;, y no es ajustable. Da igual que siembres 30 traces o 3,000: cada recomendación muestrea veinte sesiones y de ahí sale todo el diagnóstico. Eso cambia cómo construyes la línea base — necesitas tráfico &lt;strong&gt;representativo&lt;/strong&gt; antes que abundante, porque el muestreo va a dejar fuera casi todo lo demás. En la misma tabla: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Prompt size&lt;/code&gt; tope de 20,000 caracteres, 5 recomendaciones activas por cuenta y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StartRecommendation&lt;/code&gt; a 3 TPS.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Dos cosas que me parecen destacables de este resultado. La primera: &lt;strong&gt;conservó mi prompt original&lt;/strong&gt;. No lo reescribió con su propio estilo ni tradujo nada al inglés; respetó el español, la estructura y el tono, y agregó lo mínimo necesario. La segunda: el diagnóstico causal está bien hecho. Contrastar traces fallidos contra traces exitosos &lt;em&gt;que enfrentaron la misma condición&lt;/em&gt; es exactamente el análisis que haría un buen ingeniero, y es exactamente el que uno nunca tiene tiempo de hacer a mano sobre veinte trayectorias.&lt;/p&gt;

&lt;h2 id=&quot;validación-bundles-ab-y-el-veredicto-incómodo&quot;&gt;Validación: Bundles, A/B y el Veredicto Incómodo&lt;/h2&gt;

&lt;p&gt;Con el prompt recomendado en mano, el siguiente paso es no creerle. Para eso está el A/B test.&lt;/p&gt;

&lt;p&gt;Creé los dos bundles —control con el prompt actual, treatment con el recomendado— y lancé el experimento con un split 80/20:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;agentcore run ab-test &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--mode&lt;/span&gt; config-bundle &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; devopsPromptTest &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--gateway&lt;/span&gt; devopsGateway &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--runtime&lt;/span&gt; devopsAgent &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--control-bundle&lt;/span&gt; devopsControl &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--control-version&lt;/span&gt; &amp;lt;version-id-control&amp;gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--treatment-bundle&lt;/span&gt; devopsTreatment &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--treatment-version&lt;/span&gt; &amp;lt;version-id-treatment&amp;gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--online-eval&lt;/span&gt; devopsEval &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--control-weight&lt;/span&gt; 80 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--treatment-weight&lt;/span&gt; 20
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Después, tráfico real contra el endpoint HTTP del gateway, firmado con SigV4 y con un session ID nuevo por request para que el reparto de variantes funcione. Dejé acumular sesiones y consulté resultados.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/05-ab-test-results.png&quot; alt=&quot;Resultados del A/B test: control 0.94, variante 1.00, no significativo p=0.38&quot; /&gt;
&lt;em&gt;Figura 5: Resultados con 142 sesiones acumuladas — 103 ruteadas a control y 39 a la variante. Goal Success Rate: 0.94 contra 1.00. Variant improvement: &lt;strong&gt;Not significant: +6.2% (p=0.38)&lt;/strong&gt;. Recommended winner: ninguno.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Ahí está el veredicto, y no es el que uno quiere para un artículo:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Métrica&lt;/th&gt;
      &lt;th&gt;Control (C)&lt;/th&gt;
      &lt;th&gt;Treatment (T1)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Goal Success Rate (media)&lt;/td&gt;
      &lt;td&gt;0.94&lt;/td&gt;
      &lt;td&gt;1.00&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Sesiones&lt;/td&gt;
      &lt;td&gt;103&lt;/td&gt;
      &lt;td&gt;39&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Cambio porcentual&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;+6.2%&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;p-value&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;0.38&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;¿Significativo?&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;No&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Un apunte de precisión, porque de aquí en adelante voy a hacer aritmética con estos números: la consola reporta &lt;strong&gt;dos decimales&lt;/strong&gt;, 0.94 y 1.00. Eso es suficiente para reconstruir los conteos sin ambigüedad. Con 103 sesiones, un promedio que redondea a 0.94 solo admite un entero de éxitos: 97 (96/103 redondea a 0.93, 98/103 a 0.95). Así que el control fue &lt;strong&gt;97/103 = 0.9417&lt;/strong&gt; y la variante &lt;strong&gt;39/39&lt;/strong&gt;, y el cambio porcentual &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(1 − 0.9417) / 0.9417 × 100 = 6.19%&lt;/code&gt; cuadra con el +6.2% de la consola.&lt;/p&gt;

&lt;p&gt;La variante &lt;strong&gt;no falló ni una sola sesión de 39&lt;/strong&gt;. Y aun así, el servicio se niega a declararla ganadora: con p=0.38, la probabilidad de ver esta diferencia por puro azar es demasiado alta. El umbral que aplica la consola para marcar significancia es p &amp;lt; 0.05.&lt;/p&gt;

&lt;h3 id=&quot;por-qué-el-resultado-malo-es-el-hallazgo-bueno&quot;&gt;Por Qué el Resultado “Malo” es el Hallazgo Bueno&lt;/h3&gt;

&lt;p&gt;Es tentador leer esto como un fracaso del experimento. Yo lo leo al revés: &lt;strong&gt;el servicio hizo exactamente su trabajo, y su trabajo es protegerte de ti mismo&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Piensa en lo que habría pasado sin A/B test. Cambio el prompt, corro diez pruebas manuales, todas pasan, escribo en el changelog “mejora del 6% en tasa de éxito” y sigo con mi vida. Ese número habría sido una ficción con apariencia de dato. El A/B test es el que te dice, con matemática, que 39 sesiones perfectas no alcanzan para distinguir una mejora real de una racha de suerte.&lt;/p&gt;

&lt;p&gt;Antes de seguir, una honestidad que conviene decir yo mismo en lugar de dejar que alguien la encuentre cruzando las figuras: el control del A/B corre &lt;strong&gt;el mismo prompt&lt;/strong&gt; que produjo la línea base de 0.826, y sin embargo puntúa 0.9417. Son 0.116 puntos de diferencia con el prompt sin tocar, el doble del efecto que estoy tratando de medir. Entre ambas mediciones cambió el entorno: la memoria episódica quedó apagada para el A/B, y según el orden en que resolví los permisos IAM del rol de ejecución es posible que parte del tráfico de línea base corriera con herramientas devolviendo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDenied&lt;/code&gt;. La conclusión práctica es que &lt;strong&gt;la línea base no es estrictamente comparable con el control&lt;/strong&gt;: el 0.826 sirve como punto de partida narrativo, no como término de comparación. La única comparación limpia del ejercicio es control contra treatment dentro del mismo A/B test, y es la que sostiene el resto de la sección.&lt;/p&gt;

&lt;p&gt;Hay una razón de fondo que conviene entender: &lt;strong&gt;el techo&lt;/strong&gt;. Mi control ya venía en 0.9417. El espacio de mejora que queda es de 0.058 puntos. Detectar un efecto tan pequeño requiere muchísimas más muestras que detectar uno grande. Si tu agente estuviera en 0.60, la misma cantidad de tráfico probablemente habría bastado.&lt;/p&gt;

&lt;p&gt;Quise poner número a ese “muchísimas más”, y el ejercicio terminó siendo más instructivo por cómo falló que por su resultado. Corrí las pruebas clásicas sobre los conteos reconstruidos (97/103 contra 39/39) y &lt;strong&gt;ninguna coincide con lo que reporta AWS&lt;/strong&gt;: Fisher exacto bilateral da p=0.19, chi-cuadrado con corrección de Yates da p=0.28, y un t-test de Welch sobre los scores binarios da p=0.014. AWS reporta 0.38, más conservador que todas.&lt;/p&gt;

&lt;p&gt;Después intenté el paso siguiente —calcular cuántas sesiones harían falta para 80% de potencia— y ahí me quedé sin piso. Con effect size de arcoseno salen unas 105 sesiones totales al reparto 80/20; con la aproximación normal de varianza pooled salen más de 400. Un factor de cuatro entre dos métodos igual de estándar, sobre los mismos datos. La razón es que con una variante clavada en 1.00 la varianza es cero y las fórmulas de libro de texto se degradan justo donde más las necesitas. Así que el número honesto no es un número: es que &lt;strong&gt;este cálculo no se puede hacer por fuera con confianza&lt;/strong&gt;, y ese es el hallazgo.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #8&lt;/strong&gt;: No intentes reproducir ni el p-value ni el análisis de potencia de AgentCore por fuera. La documentación no especifica qué prueba usa el motor, y con una variante en 1.00 (varianza cero) las pruebas clásicas divergen entre sí por factores de cuatro. Lo práctico: el motor es &lt;strong&gt;más conservador&lt;/strong&gt; que cualquier cálculo ingenuo, así que si te dice que no hay evidencia, dale más tráfico en lugar de discutirle con una hoja de cálculo. Y dimensiona por el lado pesimista: si tu línea base ya está sobre 0.9, presupuesta cientos de sesiones por variante, no decenas.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Un detalle más que anoté: configuré el split en 80/20, pero el reparto observado fue 103/39, o sea 72.5%/27.5%. Con 142 sesiones, un 20% esperado da 28.4 sesiones con desviación estándar de 4.77; observar 39 son 2.2 sigmas (binomial exacto bilateral ≈ 0.035). Es una desviación mayor a la que esperaría del puro azar, aunque con este volumen tampoco es concluyente. Mi mejor hipótesis es la asignación &lt;em&gt;sticky&lt;/em&gt; por session ID. Descarté la explicación fácil —que los conteos fueran sesiones evaluadas y no ruteadas— porque la consola es literal al respecto: los rótulos dicen “Sessions routed to control” y “Sessions routed to variant”. No tengo evidencia para cerrarlo, así que lo dejo como observación abierta: &lt;strong&gt;si tus pesos importan de verdad, verifica el reparto real en lugar de asumirlo&lt;/strong&gt;.&lt;/p&gt;

&lt;h2 id=&quot;promoción-donde-el-cli-se-quedó-corto&quot;&gt;Promoción: Donde el CLI se Quedó Corto&lt;/h2&gt;

&lt;p&gt;Con el resultado en la mano tomé una decisión de equipo: promover el treatment de todas formas. El prompt recomendado es mejor por razones cualitativas —la regla de entregar diagnóstico ante fallos de herramienta es objetivamente correcta para el dominio— y no hay evidencia de que perjudique. Pero eso queda documentado como &lt;strong&gt;decisión, no como victoria estadística&lt;/strong&gt;. La diferencia importa.&lt;/p&gt;

&lt;p&gt;Y ahí me estrellé con el gotcha más caro del ejercicio:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Cannot promote: control and treatment reference different config bundles.
A config-bundle A/B test can only promote between two versions of the SAME bundle.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore promote ab-test&lt;/code&gt; &lt;strong&gt;solo promueve entre versiones del mismo bundle&lt;/strong&gt;. Mi test comparaba &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;devopsControl&lt;/code&gt; contra &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;devopsTreatment&lt;/code&gt;, dos bundles distintos — que es exactamente como quedan si sigues el camino natural de crear un bundle por variante. El comando falla y, peor, &lt;strong&gt;el test se queda RUNNING&lt;/strong&gt;: no lo detiene.&lt;/p&gt;

&lt;p&gt;Lo que convierte esto de descuido mío en un hueco real es que la documentación &lt;strong&gt;avala explícitamente&lt;/strong&gt; el camino que después bloquea la promoción. Los &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/ab-testing-prereqs.html&quot; target=&quot;_blank&quot;&gt;prerrequisitos de A/B testing&lt;/a&gt; listan como requisito “dos versiones de bundle &lt;strong&gt;o dos bundles separados&lt;/strong&gt;: uno para control y uno para treatment”. Las dos opciones son válidas para &lt;em&gt;correr&lt;/em&gt; el test; solo una de las dos te deja &lt;em&gt;promoverlo&lt;/em&gt;. Y el prerrequisito no lo advierte.&lt;/p&gt;

&lt;p&gt;La salida está en la consola. En la vista del A/B test hay un botón &lt;strong&gt;Deploy configuration bundle as rule&lt;/strong&gt;:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/06-deploy-bundle-as-rule.png&quot; alt=&quot;Diálogo de la consola para desplegar un bundle como regla del gateway&quot; /&gt;
&lt;em&gt;Figura 6: El diálogo pide elegir cuál bundle desplegar como regla en el gateway, y exige escribir “confirm” como consentimiento explícito. Nótese que los nombres de bundle aparecen prefijados con el nombre del proyecto: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DevOpsOptimizationLoopdevopsControl-...&lt;/code&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Esto crea una regla estática en el gateway apuntando al bundle ganador:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/optimization-loop/07-gateway-rule.png&quot; alt=&quot;Regla estática creada en el gateway con prioridad 900000&quot; /&gt;
&lt;em&gt;Figura 7: El gateway con su target &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;devops-diag&lt;/code&gt; y la nueva regla de configuration bundle en modo Static, con prioridad asignada 900000 — que según el propio diálogo se puede sobrescribir.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;No es lo mismo que un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;promote&lt;/code&gt;: no actualiza el bundle de control ni detiene el experimento. Pero logra el efecto práctico —todo el tráfico que pase por ese gateway usa el prompt ganador— y luego detienes el test aparte con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore stop ab-test -i &amp;lt;id&amp;gt;&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #9&lt;/strong&gt;: Si piensas usar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore promote ab-test&lt;/code&gt;, &lt;strong&gt;modela tus variantes como dos versiones del mismo bundle desde el inicio&lt;/strong&gt;, no como dos bundles distintos. Es una decisión de diseño que tomas en el minuto cinco del proyecto y que te cobra en el minuto quinientos. Bonus de nomenclatura: los nombres de bundle no admiten guiones (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[a-zA-Z][a-zA-Z0-9_]{0,99}&lt;/code&gt;) mientras que los de recomendación y A/B test sí; el CLI les antepone el nombre del proyecto &lt;strong&gt;sin separador&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DevOpsOptimizationLoopdevopsControl-...&lt;/code&gt;), y a los gateways además los pasa a minúsculas (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;devopsoptimizationloop-devopsgateway-...&lt;/code&gt;). Si construyes ARNs o scripts asumiendo el nombre que escribiste, no vas a encontrar nada. Y ojo con dos cupos que muerden al diseñar: &lt;strong&gt;un A/B test por gateway&lt;/strong&gt; y &lt;strong&gt;dos variantes por test&lt;/strong&gt; (control más un treatment), ambos no ajustables.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Intenté después gestionar las gateway rules por API para limpiar, y me topé con algo que no supe explicar: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ListGatewayRules&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DeleteGatewayRule&lt;/code&gt; devuelven &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDeniedException&lt;/code&gt; &lt;strong&gt;incluso con un rol de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AdministratorAccess&lt;/code&gt;&lt;/strong&gt;. Parece un guardrail de cuenta sobre APIs en preview más que un problema de política IAM. No bloquea el cleanup —la regla se elimina en cascada al destruir el gateway— pero sí impide gestión granular.&lt;/p&gt;

&lt;h2 id=&quot;lecciones-aprendidas&quot;&gt;Lecciones Aprendidas&lt;/h2&gt;

&lt;p&gt;Más allá de los ProTips repartidos por el artículo, esto es lo que me llevo del ejercicio completo.&lt;/p&gt;

&lt;h3 id=&quot;el-cli-tiene-un-homónimo-deprecado-que-te-arruina-la-tarde&quot;&gt;El CLI Tiene un Homónimo Deprecado que te Arruina la Tarde&lt;/h3&gt;

&lt;p&gt;Existen dos binarios llamados &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore&lt;/code&gt;: el &lt;strong&gt;AgentCore CLI de Node&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;npm install -g @aws/agentcore&lt;/code&gt;) y el viejo Starter Toolkit de Python (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pip install agentcore&lt;/code&gt;), que está deprecado. Si tienes ambos instalados, el de Python puede resolver primero en el PATH y &lt;strong&gt;ninguno&lt;/strong&gt; de los comandos de este artículo existe. El propio binario avisa que las capacidades nuevas solo están en el CLI nuevo, pero el mensaje es fácil de pasar por alto cuando estás depurando otra cosa. Verifica con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore --version&lt;/code&gt;: el de Node imprime algo como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.25.0&lt;/code&gt;, el de Python no soporta el flag.&lt;/p&gt;

&lt;h3 id=&quot;los-prerrequisitos-fallan-en-el-orden-equivocado&quot;&gt;Los Prerrequisitos Fallan en el Orden Equivocado&lt;/h3&gt;

&lt;p&gt;Todo el loop depende de Transaction Search habilitado en CloudWatch, y habilitarlo tiene su propia trampa de orden de operaciones.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⏱️ &lt;strong&gt;ProTip #10&lt;/strong&gt;: Habilitar Transaction Search tiene un orden obligatorio que no es obvio. Si corres &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;xray update-trace-segment-destination --destination CloudWatchLogs&lt;/code&gt; directo, falla con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDeniedException&lt;/code&gt; aunque tengas permisos de sobra. Primero necesitas un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;logs put-resource-policy&lt;/code&gt; que autorice a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;xray.amazonaws.com&lt;/code&gt; a hacer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;logs:PutLogEvents&lt;/code&gt; sobre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws/spans&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/aws/application-signals/data&lt;/code&gt;; después el update de X-Ray. El error no te dice nada de eso.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;En la misma familia de fallos por permisos: el rol de ejecución que genera el CDK &lt;strong&gt;no trae&lt;/strong&gt; los permisos que necesitan tus tools. Si no adjuntas una policy con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cloudwatch:GetMetricStatistics&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rds:Describe*&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ec2:Describe*&lt;/code&gt; al rol &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AgentCore-&amp;lt;Proyecto&amp;gt;-ApplicationAgent&amp;lt;Agente&amp;gt;...&lt;/code&gt;, tus herramientas devuelven &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDenied&lt;/code&gt; y el agente sigue respondiendo como si nada — otro fallo silencioso que solo ves si lees los traces.&lt;/p&gt;

&lt;p&gt;Y una advertencia con fecha de vencimiento, porque cambió dos semanas antes de que yo corriera esto. Las release notes de julio de 2026 introdujeron el &lt;strong&gt;destino unificado de spans&lt;/strong&gt;: en lugar del log group compartido &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws/spans&lt;/code&gt;, los agentes pueden entregar sus spans al log group propio, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/aws/bedrock-agentcore/runtimes/&amp;lt;agent_id&amp;gt;-&amp;lt;endpoint_name&amp;gt;&lt;/code&gt;, en el log stream &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;spans&lt;/code&gt;. Se controla con la variable &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UNIFIED_TRACES_DESTINATION_ENABLED&lt;/code&gt;, y el detalle que importa es este: &lt;strong&gt;desde el 20 de julio de 2026, los agentes nuevos usan su propio log group por defecto&lt;/strong&gt;, mientras los creados antes se quedan en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws/spans&lt;/code&gt; salvo que los migres. Si estás armando a mano los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;logGroupArns&lt;/code&gt; de una recomendación —o copiando un tutorial escrito antes de julio— vas a apuntar al log group equivocado y obtener cero traces. Verifica a dónde están cayendo tus spans antes de asumir la ruta.&lt;/p&gt;

&lt;h3 id=&quot;el-motor-de-análisis-corre-en-su-propio-ciclo&quot;&gt;El Motor de Análisis Corre en su Propio Ciclo&lt;/h3&gt;

&lt;p&gt;Después de generar tráfico nuevo, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentcore view ab-test --json&lt;/code&gt; me devolvía el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;analysisTimestamp&lt;/code&gt; y los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sampleSize&lt;/code&gt; de la última corrida del motor, no del momento de la consulta. A veces acompañado de un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;403 token expired&lt;/code&gt; en el campo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;results.error&lt;/code&gt; que &lt;strong&gt;no tenía relación con mis credenciales&lt;/strong&gt; —persistía con una sesión SSO recién renovada—. La consola sí reflejaba el conteo real.&lt;/p&gt;

&lt;p&gt;La lección práctica: los resultados tardan. Dependen del session timeout de tu online eval —una sesión se considera completa cuando no llegan requests nuevos dentro de la ventana— y después de que cierra, los scores aparecen típicamente en unos 15 minutos. Si sospechas un resultado stale, contrasta contra la consola o consulta directo con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws bedrock-agentcore get-ab-test --ab-test-id &amp;lt;id&amp;gt;&lt;/code&gt; (nótese: plano de datos, y el comando es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get-ab-test&lt;/code&gt;, no &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get-a-b-test&lt;/code&gt;).&lt;/p&gt;

&lt;h3 id=&quot;los-dos-planos-otra-vez&quot;&gt;Los Dos Planos, Otra Vez&lt;/h3&gt;

&lt;p&gt;Como en el artículo de Memory, la distinción entre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore&lt;/code&gt; (plano de datos: recommendations, A/B tests, invoke, leer bundle) y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-control&lt;/code&gt; (plano de control: crear bundles, online eval) es real y tiene consecuencias. Confundirlos te da un método inexistente, no un error de permisos. Y en la misma línea de detalles que muerden: la API de recommendations usa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;logGroupArns&lt;/code&gt; (ARNs completos) mientras que las batch evaluations usan &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;logGroupNames&lt;/code&gt; (nombres). La documentación lo marca explícitamente, lo cual ya dice algo.&lt;/p&gt;

&lt;h3 id=&quot;el-costo-es-sorprendentemente-bajo&quot;&gt;El Costo es Sorprendentemente Bajo&lt;/h3&gt;

&lt;p&gt;La &lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/pricing/&quot; target=&quot;_blank&quot;&gt;página oficial de pricing de AgentCore&lt;/a&gt; es explícita: la generación de recommendations &lt;strong&gt;no tiene cargo&lt;/strong&gt; —pagas solo las Evaluations que consuma el flujo— y los A/B tests se cobran por Gateway, Runtime y Evaluations consumidos. En números reales de mi cuenta, 32 invocaciones consumieron 50,020 tokens de input y 17,663 de output. Con el pricing de Claude Sonnet 4.6 ($3 por millón de input, $15 por millón de output):&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;input:  50,020 tokens ÷ 1M × $3  = $0.1501
output: 17,663 tokens ÷ 1M × $15 = $0.2649
                                   -------
total (32 invocaciones)            $0.4150   →  ~$0.013 por invocación
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Extrapolando a las ~172 invocaciones del loop completo, la inferencia del agente ronda los &lt;strong&gt;$2.23&lt;/strong&gt;. Hay que sumar el modelo juez del online evaluation y el compute del runtime, así que el ejercicio completo queda en el orden de unos pocos dólares. Para el tipo de decisión que respalda —cambiar el comportamiento de un agente en producción con evidencia en lugar de intuición— es barato.&lt;/p&gt;

&lt;p&gt;Pero ojo con la trampa: si tu línea base ya está alta y necesitas cientos de sesiones por variante para alcanzar significancia, ese costo escala. A $0.013 por invocación, 1,000 sesiones son ~$13 de inferencia del agente. Sigue siendo barato; solo hay que presupuestarlo.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;Volvamos a la pregunta del inicio: ¿es AWS mejor que tú escribiendo el prompt de tu agente?&lt;/p&gt;

&lt;p&gt;En mi ejercicio, la respuesta honesta es &lt;strong&gt;parcialmente sí, y por una razón que no esperaba&lt;/strong&gt;. El optimizador no fue más creativo que yo ni escribió mejor prosa. Lo que hizo fue algo mucho más aburrido y mucho más valioso: &lt;strong&gt;leyó los veinte traces completos&lt;/strong&gt; y comparó sistemáticamente los fallos contra los éxitos que enfrentaron la misma condición. Es un trabajo que yo sé hacer perfectamente y que nunca hago, porque implica leer trayectorias completas una por una un martes por la tarde.&lt;/p&gt;

&lt;p&gt;Ese es el verdadero producto de Recommendations: no la inteligencia, sino la disciplina.&lt;/p&gt;

&lt;p&gt;Y el A/B test resultó ser la mitad más importante del loop, precisamente porque me dijo que no. Una mejora de 0.94 a 1.00 sin un solo fallo en 39 sesiones &lt;strong&gt;suena&lt;/strong&gt; a victoria, y en un blog post menos honesto habría titulado “+6.2% de mejora con AgentCore Optimization”. El servicio me recordó que ese número no significa lo que parece significar con ese tamaño de muestra. Prefiero mil veces esa fricción que un dashboard que me dé la razón.&lt;/p&gt;

&lt;p&gt;Si vas a llevar esto a producción, mi recomendación práctica: empieza el loop &lt;strong&gt;antes&lt;/strong&gt; de que tu agente esté bueno. Suena contraintuitivo, pero es donde más rinde. Con un agente en 0.60 de Goal Success Rate, unas decenas de sesiones te dan significancia y el ciclo itera rápido. Con un agente en 0.94, estás peleando contra el techo y necesitas volumen de producción real para mover la aguja con evidencia.&lt;/p&gt;

&lt;p&gt;Con este artículo, la serie ya cubre el ciclo completo de un agente en AgentCore: &lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;Policy&lt;/a&gt; para lo que el agente &lt;strong&gt;puede&lt;/strong&gt; hacer, &lt;a href=&quot;/bedrock-evaluations.html&quot; target=&quot;_blank&quot;&gt;Evaluations&lt;/a&gt; para medir qué tan bien lo hace, &lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;Memoria Episódica&lt;/a&gt; para que aprenda de lo que vivió, &lt;a href=&quot;/agentcore-session-storage.html&quot; target=&quot;_blank&quot;&gt;Session Storage&lt;/a&gt; para que no pierda lo que construyó, y ahora Optimization para cerrar el ciclo y &lt;strong&gt;mejorarlo con evidencia en lugar de intuición&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;El código completo del ejercicio —agente portado a Strands, scripts numerados del 00 al 07, y el runbook con los nueve gotchas documentados— está en &lt;a href=&quot;https://github.com/codecr/agentcore-optimization-loop&quot; target=&quot;_blank&quot;&gt;github.com/codecr/agentcore-optimization-loop&lt;/a&gt;. Se reproduce en tu cuenta por unos pocos dólares.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚀 &lt;strong&gt;ProTip Final&lt;/strong&gt;: Antes de correr tu primer loop de optimización, mide tu línea base y calcula si tu volumen de tráfico puede alcanzar significancia para el tamaño de mejora que esperas. Un A/B test que nunca llega a p &amp;lt; 0.05 no es un experimento fallido: es un experimento mal dimensionado. Y esa cuenta se hace antes, no después.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;hr /&gt;

&lt;p&gt;¿Ya tienes agentes en producción con suficiente tráfico para correr A/B tests con significancia real? ¿O estás en la etapa donde el volumen todavía no da y las decisiones siguen siendo cualitativas? Me interesa mucho conocer cómo están validando cambios de prompt en producción — los comentarios están abiertos.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization.html&quot; target=&quot;_blank&quot;&gt;AgentCore optimization: Improve agent quality loop with recommendations and A/B tests&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization-how-it-works.html&quot; target=&quot;_blank&quot;&gt;Optimization: How it works&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/ab-testing.html&quot; target=&quot;_blank&quot;&gt;A/B testing: patrones de variantes&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/ab-testing-prereqs.html&quot; target=&quot;_blank&quot;&gt;A/B testing prerequisites&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/ab-testing-config-bundle.html&quot; target=&quot;_blank&quot;&gt;Run an A/B test with configuration bundles&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/configuration-bundles-runtime.html&quot; target=&quot;_blank&quot;&gt;Use configuration bundles at runtime (baggage y patrones por framework)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/configuration-bundles-update.html&quot; target=&quot;_blank&quot;&gt;Update a configuration bundle (versiones, branches, parentVersionIds)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrockagentcore-configurationbundle-versionlineagemetadata.html&quot; target=&quot;_blank&quot;&gt;CloudFormation: ConfigurationBundle VersionLineageMetadata&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/bedrock-agentcore-limits.html&quot; target=&quot;_blank&quot;&gt;Quotas for Amazon Bedrock AgentCore&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/evaluations.html&quot; target=&quot;_blank&quot;&gt;Evaluate agent performance with AgentCore Evaluations&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/03/agentcore-evaluations-generally-available/&quot; target=&quot;_blank&quot;&gt;Anuncio: AgentCore Evaluations is now generally available (marzo 2026)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_SystemPromptRecommendationConfig.html&quot; target=&quot;_blank&quot;&gt;API Reference: SystemPromptRecommendationConfig&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/introducing-agent-quality-optimization-in-agentcore-now-in-preview/&quot; target=&quot;_blank&quot;&gt;Blog de lanzamiento: Introducing agent quality optimization in AgentCore&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/detecting-silent-agent-failures-with-amazon-bedrock-agentcore-optimization/&quot; target=&quot;_blank&quot;&gt;Blog: Detecting silent agent failures with AgentCore optimization&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/pricing/&quot; target=&quot;_blank&quot;&gt;Pricing: Amazon Bedrock AgentCore&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/faqs/&quot; target=&quot;_blank&quot;&gt;Amazon Bedrock AgentCore FAQs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/release-notes.html&quot; target=&quot;_blank&quot;&gt;Release notes de Amazon Bedrock AgentCore&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.w3.org/TR/baggage/&quot; target=&quot;_blank&quot;&gt;W3C Baggage specification&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Wed, 05 Aug 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/agentcore-optimization-loop.html</link>
                <guid isPermaLink="true">https://gerardo.dev/agentcore-optimization-loop.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>AgentCore</category>
                
                <category>Optimization</category>
                
                <category>Evaluations</category>
                
                <category>Runtime</category>
                
                <category>Gateway</category>
                
                <category>GenAI</category>
                
                <category>Agents</category>
                
                <category>Strands</category>
                
                <category>DevOps</category>
                
                
            </item>
        
            <item>
                <title>Lambda MicroVMs vs AgentCore Runtime: cuándo usar cada uno para agentes en producción</title>
                <description>&lt;h1 id=&quot;lambda-microvms-vs-agentcore-runtime-cuándo-usar-cada-uno-para-agentes-en-producción&quot;&gt;Lambda MicroVMs vs AgentCore Runtime: cuándo usar cada uno para agentes en producción&lt;/h1&gt;

&lt;p&gt;El 22 de junio de 2026, AWS lanzó algo que no es una feature ni una actualización: es un primitivo de cómputo nuevo. Lambda MicroVMs permite dar a cada usuario o sesión su propia VM Firecracker aislada, con estado que persiste hasta 8 horas, arranque desde snapshot en segundos, y sin infraestructura que gestionar.&lt;/p&gt;

&lt;p&gt;Si llevas meses trabajando con AgentCore Runtime como yo, la reacción instintiva al leer el anuncio es la misma que registró la prensa técnica: otro caso de uso obvio para agentes de IA, pero AWS ya ofrece AgentCore Runtime, que se parece bastante a MicroVMs.&lt;/p&gt;

&lt;p&gt;Y es correcto identificar el solapamiento. Pero es un error llevarlo hasta la conclusión de que son intercambiables.&lt;/p&gt;

&lt;p&gt;Pasé los últimos días revisando la documentación oficial, los hands-on notes de Aidan Steele (quien exploró el servicio el día de lanzamiento), y el análisis de Yan Cui, además de mapear todo contra lo que ya conozco de AgentCore Runtime de haberlo cubierto en profundidad en esta serie. Este artículo es el resultado de ese trabajo.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #1&lt;/strong&gt;: La pregunta correcta no es “¿Lambda MicroVMs o AgentCore Runtime?”. La pregunta correcta es “¿quién ejecuta el código — mi agente, o mis usuarios?” Esa distinción determina todo lo demás.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;lo-que-tienen-en-común-el-mismo-motor&quot;&gt;Lo que Tienen en Común: El Mismo Motor&lt;/h2&gt;

&lt;p&gt;Antes de hablar de diferencias, hay que entender por qué la confusión es razonable.&lt;/p&gt;

&lt;p&gt;Ambos servicios corren sobre &lt;strong&gt;Firecracker&lt;/strong&gt;, el VMM open-source que AWS desarrolló internamente y que ya potencia más de 15 billones (15 trillion) de invocaciones mensuales de Lambda Functions. Ambos dan aislamiento real a nivel de VM: sin kernel compartido, sin recursos compartidos entre sesiones. Ambos soportan &lt;strong&gt;hasta 8 horas de duración máxima&lt;/strong&gt;. Y ambos agregaron soporte de shell interactivo en junio de 2026: Lambda MicroVMs con la API &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateMicrovmShellAuthToken&lt;/code&gt;, y AgentCore Runtime con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvokeAgentRuntimeCommandShell&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Eso es suficiente similitud para que la confusión sea comprensible. Pero la analogía que mejor captura la diferencia la escribió Yan Cui:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;em&gt;“AgentCore Runtime es a Lambda MicroVMs lo que Fargate es a EC2.”&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Fargate corre tu contenedor en una microVM pero controla lo que puedes hacer dentro. EC2 te da la máquina completa. AgentCore te da hosting gestionado de contenedores en microVM. Lambda MicroVMs te da la VM en sí.&lt;/p&gt;

&lt;p&gt;La frontera de aislamiento es la misma — Firecracker. Lo que puedes hacer dentro no lo es.&lt;/p&gt;

&lt;h2 id=&quot;agentcore-runtime-la-plataforma-gestionada&quot;&gt;AgentCore Runtime: La Plataforma Gestionada&lt;/h2&gt;

&lt;p&gt;AgentCore Runtime es lo que AWS llama un “managed agent platform”. Despliegas tu código de agente — LangGraph, Strands, CrewAI, o el framework que uses — y AWS gestiona todo lo demás. Fleet management. Routing de sesiones a VMs. Scaling y teardown de sesiones idle. Auth inbound y outbound. Soporte nativo de protocolos MCP y A2A. Versionado. Endpoints.&lt;/p&gt;

&lt;p&gt;Cuando tu usuario habla con tu agente, no piensas en VMs. El runtime provisiona la microVM, enruta la sesión, y cuando la sesión termina destruye el entorno y limpia la memoria.&lt;/p&gt;

&lt;p&gt;Lo que corres dentro del contenedor de AgentCore Runtime es &lt;strong&gt;tu lógica de agente&lt;/strong&gt;: el loop de razonamiento, las tools, el estado conversacional. El modelo LLM vive en Bedrock, en el lado de Anthropic, o donde lo hayas configurado. AgentCore pone a tu agente en un entorno seguro, escalable, y con observabilidad built-in — CloudTrail para auditoría, CloudWatch para logs.&lt;/p&gt;

&lt;p&gt;Las restricciones son las de cualquier plataforma gestionada: corres dentro de un contenedor que AWS configura y opera, no tienes la VM completa a tu disposición. El entorno está deliberadamente más acotado que una VM con todas las capabilities del sistema operativo, porque ejecutar un agente no requiere ese nivel de control. AgentCore sí te da shell interactivo — pero a través de una API gestionada (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvokeAgentRuntimeCommandShell&lt;/code&gt;), no acceso crudo al device del pseudoterminal. Si tu caso necesita cosas como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/dev/ptmx&lt;/code&gt; directo, correr tu propio daemon de Docker, o manipular el stack de red a bajo nivel, ese no es el terreno de AgentCore Runtime — es exactamente lo que Lambda MicroVMs habilita, como veremos enseguida.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: Todo lo anterior describe el &lt;strong&gt;AgentCore Runtime serverless (microVM)&lt;/strong&gt; — el único tipo de cómputo que existía cuando escribí este artículo. En agosto de 2026 AWS agregó un segundo tipo de cómputo dentro del mismo AgentCore Runtime: &lt;strong&gt;&lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/08/aws-bedrock-agentcore-runtime-instances-generally-available/&quot; target=&quot;_blank&quot;&gt;Runtime Instances&lt;/a&gt;&lt;/strong&gt;, basado en instancias EC2 (familias GPU-accelerated, memory-optimized, compute-optimized) con sesiones de hasta &lt;strong&gt;14 días&lt;/strong&gt; en vez del techo de 8 horas. No cambia el argumento central de este artículo — sigue siendo “tu agente ejecuta código” vs. “tus usuarios ejecutan código” — pero sí introduce una tercera fila en la tabla de decisión: si tu bloqueante para usar AgentCore Runtime era la duración máxima de sesión, ya no necesitas salir del ecosistema AgentCore ni evaluar Lambda MicroVMs para resolverlo. Está disponible en 9 regiones (us-east-1, us-east-2, us-west-2, eu-central-1, eu-west-1, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1) y se cobra como costo EC2 + fee de gestión, no con el billing por-consumo-activo del runtime serverless. Ver la &lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/pricing/&quot; target=&quot;_blank&quot;&gt;página de pricing de AgentCore&lt;/a&gt; para el detalle.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #2&lt;/strong&gt;: AgentCore está disponible en &lt;strong&gt;15 regiones&lt;/strong&gt; según el FAQ oficial de AWS — incluyendo us-east-1, us-west-2, eu-central-1 (Frankfurt), ap-northeast-1 (Tokyo), Mumbai, Sydney, Singapur, y varias de Europa. Lambda MicroVMs al lanzamiento está solo en &lt;strong&gt;5 regiones&lt;/strong&gt;: us-east-1, us-east-2, us-west-2, eu-west-1 (Irlanda), y ap-northeast-1 (Tokyo). Ten en cuenta que ciertas features puntuales de AgentCore Runtime (shell interactivo, MCP stateful, AG-UI) llegan a un subconjunto de esas regiones, así que verifica la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html&quot; target=&quot;_blank&quot;&gt;lista oficial de regiones soportadas&lt;/a&gt; para tu feature específica. Si tu workload necesita una región fuera de las 5 de MicroVMs, AgentCore Runtime sigue siendo la única opción gestionada por ahora.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (agosto 2026)&lt;/strong&gt;: Ese “15 regiones” ya estaba corto cuando publiqué. La &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html&quot; target=&quot;_blank&quot;&gt;tabla oficial de regiones soportadas&lt;/a&gt; lista hoy &lt;strong&gt;veinte&lt;/strong&gt; regiones con AgentCore Runtime disponible: diecinueve comerciales más GovCloud US-West. La expansión fue rápida — São Paulo y Canadá Central en abril de 2026, GovCloud US-West en mayo, y Bangkok, Malasia, Milán y España en junio. El argumento del ProTip no cambia (la brecha de cobertura frente a MicroVMs se ensanchó, no se cerró), pero la cifra sí. Y aquí está la lección de fondo: &lt;strong&gt;cualquier conteo de regiones en un artículo técnico caduca en semanas&lt;/strong&gt;, así que trátalo como una foto fechada y ve siempre a la tabla oficial.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;lambda-microvms-el-primitivo-de-bajo-nivel&quot;&gt;Lambda MicroVMs: El Primitivo de Bajo Nivel&lt;/h2&gt;

&lt;p&gt;Lambda MicroVMs es un namespace de API completamente nuevo dentro de Lambda — &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws lambda-microvms&lt;/code&gt; — con su propia superficie de comandos. No es una opción de configuración de Lambda Functions. Es un recurso distinto.&lt;/p&gt;

&lt;p&gt;El flujo es diferente desde el principio. En lugar de un handler que responde a eventos, tú empaquetas tu aplicación (cualquier cosa que corra en Linux) y un Dockerfile en un zip, lo subes a S3, y llamas &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create-microvm-image&lt;/code&gt;. Lambda ejecuta el Dockerfile, inicializa la aplicación, y captura un &lt;strong&gt;snapshot Firecracker del estado en memoria y disco&lt;/strong&gt;. Eso es tu imagen.&lt;/p&gt;

&lt;p&gt;Cuando necesitas un entorno aislado — para un usuario, un job, una sesión de sandbox — llamas &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run-microvm&lt;/code&gt;. Lambda lanza la VM desde el snapshot con startup near-instant y te devuelve un &lt;strong&gt;endpoint HTTPS dedicado&lt;/strong&gt; con un ID único para esa VM. Los clientes se conectan sobre HTTP/2, gRPC, o WebSockets. Cada conexión requiere un bearer token que generas con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateMicrovmAuthToken&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Lo que puedes hacer dentro de ese entorno es completamente diferente a AgentCore Runtime:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# Dentro de una MicroVM tienes un Linux completo&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;# Docker dentro de la MicroVM: funciona&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;# /dev/ptmx para pseudoterminales: disponible&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;# iptables, eBPF, namespaces de red: disponibles&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;# Hasta 16 vCPUs y 32 GB de memoria&lt;/span&gt;
&lt;span class=&quot;c&quot;&gt;# 32 GB de disco&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El gotcha más importante que documentó Aidan Steele el día del lanzamiento: &lt;strong&gt;todo UDP outbound está bloqueado por defecto&lt;/strong&gt;. El resolver DNS por defecto es un stub local. Si corres contenedores Docker dentro de tu MicroVM, el DNS dentro de los contenedores intentará caer a 8.8.8.8 — que falla porque el UDP está bloqueado. La solución es forzar el DNS de Lambda: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker run --dns 169.254.169.253&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #3&lt;/strong&gt;: Las imágenes MicroVM se construyen exclusivamente desde un &lt;strong&gt;Dockerfile en un ZIP subido a S3&lt;/strong&gt; — no desde una imagen ECR directamente. La documentación oficial sugiere que ECR está soportado, pero Aidan Steele lo verificó el día del lanzamiento: no lo está. Tu Dockerfile puede hacer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FROM alguna-imagen-ecr&lt;/code&gt;, pero el proceso siempre parte de un Dockerfile en S3. Otro detalle: Lambda construye &lt;strong&gt;dos copias&lt;/strong&gt; de la imagen — una para Graviton 3 y otra para Graviton 4 — por eso piden el Dockerfile fuente en lugar de la imagen compilada.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Además, la &lt;strong&gt;escala horizontal es tuya&lt;/strong&gt;. Lambda MicroVMs hace escala vertical automática dentro de cada VM (hasta 4x el baseline configurado), pero si necesitas más entornos aislados, tu aplicación los crea, les hace tracking, enruta usuarios al entorno correcto, y los limpia. No hay fleet management automático. No hay routing built-in.&lt;/p&gt;

&lt;p&gt;Eso no es una limitación — es una decisión de diseño deliberada. Lambda MicroVMs es un primitivo. La plomería de fleet management es lo que tú construyes encima.&lt;/p&gt;

&lt;h2 id=&quot;el-modelo-mental-correcto&quot;&gt;El Modelo Mental Correcto&lt;/h2&gt;

&lt;p&gt;La manera más clara que encontré de pensar en esto:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AgentCore Runtime&lt;/strong&gt;: &lt;em&gt;“corre mi agente para que mis usuarios puedan hablar con él”.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Lambda MicroVMs&lt;/strong&gt;: &lt;em&gt;“dale a cada usuario su propia VM aislada para que corran código en ella”.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;En AgentCore Runtime, &lt;strong&gt;tu agente ejecuta código&lt;/strong&gt;. El código que ejecuta es el razonamiento del LLM, las tools que definiste, la lógica que programaste. Los usuarios interactúan con el agente — no ejecutan código arbitrario en el entorno.&lt;/p&gt;

&lt;p&gt;En Lambda MicroVMs, &lt;strong&gt;tus usuarios ejecutan código&lt;/strong&gt;. O más precisamente, el código que genera el agente — output de un LLM, scripts de un usuario, queries de análisis — se ejecuta en el entorno aislado. El agente es el origen del código, no el ejecutor.&lt;/p&gt;

&lt;p&gt;Esta distinción define los casos de uso de cada servicio.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #4&lt;/strong&gt;: Hay un caso de uso donde Lambda MicroVMs y AgentCore Runtime se complementan directamente: &lt;strong&gt;coding agents con sandboxes de ejecución&lt;/strong&gt;. AgentCore Runtime corre tu agente (el razonamiento). Cada vez que el agente genera código para ejecutar, lanza una Lambda MicroVM para ejecutarlo de forma aislada. El resultado vuelve al agente. Es la arquitectura que AWS documenta en la guía oficial para Claude Managed Agents con self-hosted sandboxes.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;cuándo-usar-agentcore-runtime&quot;&gt;Cuándo Usar AgentCore Runtime&lt;/h2&gt;

&lt;p&gt;AgentCore Runtime es el primitivo correcto cuando:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Construyes un agente que presta un servicio a usuarios.&lt;/strong&gt; Un asistente de soporte técnico. Un agente de análisis financiero. Un bot de coding que ayuda a debuggear código &lt;em&gt;del usuario&lt;/em&gt;, pero donde el agente tiene su propio estado, tools y razonamiento. El usuario habla con el agente, no ejecuta código en el entorno del agente.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Necesitas el ecosistema gestionado de AgentCore.&lt;/strong&gt; Si usas &lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;AgentCore Memory&lt;/a&gt; para persistencia episódica, &lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;AgentCore Policy&lt;/a&gt; para límites determinísticos, &lt;a href=&quot;/agentcore-payments.html&quot; target=&quot;_blank&quot;&gt;AgentCore Payments&lt;/a&gt; para micropagos, o el Agent Registry para governance — todo eso está construido sobre el Runtime y se integra sin código adicional.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Necesitas disponibilidad en más regiones.&lt;/strong&gt; Quince regiones incluyendo Mumbai, Sydney, Singapur, y varias de Europa que Lambda MicroVMs no cubre todavía.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La complejidad operacional de fleet management no es parte de tu producto.&lt;/strong&gt; No quieres escribir el código que decide cuántas VMs tener en pie, cuáles asignar a qué usuario, y cuándo limpiarlas. AgentCore lo hace por ti.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Tu agente pasa buena parte del tiempo esperando I/O.&lt;/strong&gt; AgentCore Runtime solo cobra CPU por consumo activo — si tu agente no consume CPU mientras espera la respuesta del LLM, una tool call, o una query a base de datos, ese tiempo no se factura (&lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/pricing/&quot; target=&quot;_blank&quot;&gt;pricing oficial de AgentCore Runtime&lt;/a&gt;). En workloads agénticos, que típicamente pasan entre 30% y 70% del tiempo en I/O wait, esto es una ventaja de costo real frente a un modelo que factura toda la duración de la sesión sin distinguir CPU activo de CPU idle.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #5&lt;/strong&gt;: Si ya tienes AgentCore Runtime en producción y tu agente &lt;em&gt;ejecuta código que los usuarios envían&lt;/em&gt;, ese es el único caso donde deberías plantearte migrar la ejecución de ese código a Lambda MicroVMs como sandbox. No migrar el agente — migrar la capa donde se ejecuta el código no confiable.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;cuándo-usar-lambda-microvms&quot;&gt;Cuándo Usar Lambda MicroVMs&lt;/h2&gt;

&lt;p&gt;Lambda MicroVMs es el primitivo correcto cuando:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Construyes una plataforma multi-tenant donde cada usuario necesita su propio entorno de ejecución.&lt;/strong&gt; Un notebook interactivo de análisis de datos. Un coding assistant que ejecuta el código que el LLM genera. Una plataforma de CI/CD que corre pipelines en aislamiento por tenant. Un escáner de vulnerabilidades que inspecciona paquetes. En todos estos casos, el producto &lt;em&gt;es&lt;/em&gt; el entorno de ejecución aislado — no el agente que razona.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Necesitas acceso completo al sistema operativo.&lt;/strong&gt; Correr Docker dentro de la VM. eBPF. Montar filesystems. Instalar paquetes a nivel de sistema operativo. Nada de esto es posible en AgentCore Runtime porque corre en un contenedor, no en una VM completa.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Construyes algo que no es un agente de IA.&lt;/strong&gt; Un servidor de juegos que ejecuta scripts de usuarios. Un entorno de CI con fuerte aislamiento por tenant. Una herramienta de research de seguridad. Lambda MicroVMs no está atado al ecosistema de agentes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Quieres control granular del lifecycle.&lt;/strong&gt; Lambda MicroVMs expone APIs directas para &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;suspend-microvm&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;resume-microvm&lt;/code&gt;, y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;terminate-microvm&lt;/code&gt;. Puedes construir exactamente la lógica de lifecycle que tu producto necesita.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #6&lt;/strong&gt;: El modelo de precios de Lambda MicroVMs es &lt;strong&gt;por segundo de instancia&lt;/strong&gt; — más cercano a Fargate que a Lambda Functions. Se cobra por vCPU-segundo + GB de memoria por segundo + snapshot reads/writes + data transfer. A diferencia de Lambda Functions (por milisegundo), Lambda MicroVMs factura por segundo. Mientras la VM está &lt;em&gt;suspended&lt;/em&gt;, los cargos de cómputo cesan — solo pagas el snapshot storage. El suspend/resume es la palanca principal para controlar costos en sesiones con períodos largos de inactividad. Verifica los precios actuales en la &lt;a href=&quot;https://aws.amazon.com/lambda/pricing/&quot;&gt;página oficial de pricing de AWS Lambda&lt;/a&gt; antes de presupuestar cualquier workload.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;la-tabla-de-decisión-honesta&quot;&gt;La Tabla de Decisión Honesta&lt;/h2&gt;

&lt;p&gt;Para bajar todo esto a algo accionable:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt; &lt;/th&gt;
      &lt;th&gt;&lt;strong&gt;AgentCore Runtime&lt;/strong&gt;&lt;/th&gt;
      &lt;th&gt;&lt;strong&gt;Lambda MicroVMs&lt;/strong&gt;&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Quién ejecuta código&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Tu agente (lógica tuya)&lt;/td&gt;
      &lt;td&gt;Tus usuarios o el código que genera el LLM&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Nivel de abstracción&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Plataforma gestionada&lt;/td&gt;
      &lt;td&gt;Primitivo de cómputo&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Fleet management&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;AWS lo gestiona&lt;/td&gt;
      &lt;td&gt;Tu aplicación lo gestiona&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Auth built-in&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Sí — inbound y outbound&lt;/td&gt;
      &lt;td&gt;Token bearer por VM, tuyo el routing&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Protocolos MCP/A2A&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Built-in&lt;/td&gt;
      &lt;td&gt;No existe, lo construyes&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;OS access dentro&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Contenedor (restringido)&lt;/td&gt;
      &lt;td&gt;VM completa (Docker, ptmx, eBPF)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Suspend/resume&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;No soportado&lt;/td&gt;
      &lt;td&gt;Sí — API explícita&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Regiones (jun 2026)&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;15 regiones (features puntuales en subconjunto)&lt;/td&gt;
      &lt;td&gt;5 regiones&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Arquitectura&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;ARM64&lt;/td&gt;
      &lt;td&gt;ARM64 únicamente&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Billing&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Por vCPU-second activo + memory-second (I/O wait no se cobra)&lt;/td&gt;
      &lt;td&gt;Por vCPU-second + memory-second&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Shell interactivo&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InvokeAgentRuntimeCommandShell&lt;/code&gt; (PTY sobre WebSocket, hasta 10 concurrentes)&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateMicrovmShellAuthToken&lt;/code&gt; (PTY directo)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Ecosistema AgentCore&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Memory, Policy, Payments, Registry&lt;/td&gt;
      &lt;td&gt;Sin integración directa&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Duración máxima&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;8 horas (microVM serverless) / 14 días (Runtime Instances, GA agosto 2026)&lt;/td&gt;
      &lt;td&gt;8 horas&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;el-caso-del-coding-agent-los-dos-juntos&quot;&gt;El Caso del Coding Agent: Los Dos Juntos&lt;/h2&gt;

&lt;p&gt;Hay un caso donde los dos servicios son la respuesta — no uno u otro. Es el que AWS formalizó con su guía oficial para Claude Managed Agents con sandboxes self-hosted.&lt;/p&gt;

&lt;p&gt;La arquitectura es:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;AgentCore Runtime&lt;/strong&gt; corre tu agente — el loop de razonamiento, el modelo, la gestión de sesión conversacional.&lt;/li&gt;
  &lt;li&gt;Cuando el agente genera código para ejecutar (bash, Python, Node.js), tu control plane lanza una &lt;strong&gt;Lambda MicroVM&lt;/strong&gt; por sesión.&lt;/li&gt;
  &lt;li&gt;El código del agente se ejecuta en ese sandbox aislado.&lt;/li&gt;
  &lt;li&gt;El resultado vuelve al agente como output de tool.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;El flujo concreto según la documentación oficial:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;1. Anthropic envía webhook session.status_run_started
2. Una Lambda Function verifica la firma y llama run-microvm
3. La MicroVM levanta, ejecuta tool calls en /workspace
4. Resultados vuelven a Anthropic
5. La MicroVM se suspende o termina al cerrar la sesión
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Tu API key de Anthropic nunca toca cómputo de AWS en este flujo. El launcher solo pasa una referencia a Secrets Manager — la MicroVM lee la clave en runtime con credenciales temporales via IMDSv2.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔧 &lt;strong&gt;ProTip #7&lt;/strong&gt;: Si implementas este patrón, configura la &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;idle-policy&lt;/code&gt; de tu MicroVM con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;suspendedDurationSeconds: 0&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;autoResumeEnabled: false&lt;/code&gt; para sesiones por usuario. Quieres que las MicroVMs terminen cuando la sesión cierra, no que se suspendan esperando tráfico que puede no volver. Usa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maximumDurationInSeconds&lt;/code&gt; como ceiling de seguridad para sesiones bloqueadas — el máximo es 28,800 segundos (8 horas).&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;lo-que-no-se-sabe-todavía&quot;&gt;Lo Que No Se Sabe Todavía&lt;/h2&gt;

&lt;p&gt;Sería deshonesto no incluir las limitaciones actuales que hay que monitorear:&lt;/p&gt;

&lt;p&gt;Lambda MicroVMs está disponible desde el 22 de junio. La curva de adopción es corta y hay detalles que todavía emergen:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El tamaño máximo de imagen no está documentado.&lt;/strong&gt; Aidan Steele verificó en el lanzamiento que la máquina que construye las imágenes tiene aproximadamente 7.2 GB de espacio libre en disco. Imágenes grandes pueden fallar en el build con un error críptico.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Las variables de entorno requieren rebuild de imagen.&lt;/strong&gt; En Lambda Functions, actualizar env vars es inmediato. En MicroVMs, los env vars van en la imagen — cambiarlos requiere &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create-microvm-image&lt;/code&gt; de nuevo. Diseña el acceso a configuración dinámica (Secrets Manager, SSM Parameter Store) como llamadas en runtime, no como env vars.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;ECR como source no está soportado a pesar de que los docs lo sugieren.&lt;/strong&gt; La fuente siempre es un Dockerfile en un ZIP en S3. Tu Dockerfile puede hacer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FROM&lt;/code&gt; a una imagen ECR, pero el proceso parte del Dockerfile.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Regiones limitadas al lanzamiento.&lt;/strong&gt; El equipo de Lambda tiene track record de expandir regiones rápidamente, pero si us-east-1, us-east-2, us-west-2, eu-west-1, o ap-northeast-1 no sirven para tu caso, aguarda a la expansión.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #8&lt;/strong&gt;: Antes de diseñar una arquitectura de producción sobre Lambda MicroVMs, ejecuta el tutorial oficial completo: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create-microvm-image&lt;/code&gt; + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run-microvm&lt;/code&gt; + auth token + request HTTP real. Según las mediciones de Aidan Steele el día del lanzamiento, el ciclo de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run-microvm&lt;/code&gt; a estado RUNNING tomó ~2 segundos, y la app sirviendo HTTP 200 OK ~2 segundos adicionales — pero él mismo advierte que tomes esos números con pinzas, porque estaba conectándose a us-east-1 desde el otro lado del mundo. El suspend y el resume rondaron 1 segundo cada uno en sus pruebas. Mídelo tú mismo desde tu región antes de comprometer cualquier número a tu diseño: si tu UX requiere sub-segundo en el arranque desde cero, ese delta importa.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;mi-evaluación&quot;&gt;Mi Evaluación&lt;/h2&gt;

&lt;p&gt;Si construyes &lt;strong&gt;agentes que sirven a usuarios&lt;/strong&gt;, AgentCore Runtime sigue siendo el punto de partida correcto. El ecosistema de &lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;Memory&lt;/a&gt;, &lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;Policy&lt;/a&gt;, &lt;a href=&quot;/agentcore-payments.html&quot; target=&quot;_blank&quot;&gt;Payments&lt;/a&gt;, y &lt;a href=&quot;/agentcore-session-storage.html&quot; target=&quot;_blank&quot;&gt;Session Storage&lt;/a&gt; existe para ese caso, y el fleet management gestionado elimina una clase entera de trabajo de plataforma. Y desde agosto de 2026, si tu agente necesita sesiones de larga duración (hasta 14 días) o cómputo GPU/memory-optimized, Runtime Instances cubre ese caso sin que tengas que salir del ecosistema AgentCore hacia Lambda MicroVMs.&lt;/p&gt;

&lt;p&gt;Si construyes &lt;strong&gt;plataformas donde los usuarios ejecutan código&lt;/strong&gt;, Lambda MicroVMs es la opción más limpia que AWS ha ofrecido hasta ahora. Era un problema que antes requería operar Firecracker directamente, o pagar a un vendor especializado, o hacer concesiones de aislamiento con contenedores. Ahora es un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;run-microvm&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Si construyes &lt;strong&gt;coding agents&lt;/strong&gt; — agentes que razonan sobre código y necesitan ejecutarlo de forma segura — la arquitectura correcta probablemente use los dos: AgentCore Runtime para el razonamiento, Lambda MicroVMs para el sandbox de ejecución.&lt;/p&gt;

&lt;p&gt;La pregunta que debes responder antes de elegir no es técnica. Es de diseño de producto: ¿en tu sistema, quién ejecuta el código que no escribiste tú?&lt;/p&gt;

&lt;p&gt;Si la respuesta es el agente — AgentCore Runtime.&lt;/p&gt;

&lt;p&gt;Si la respuesta son tus usuarios — Lambda MicroVMs.&lt;/p&gt;

&lt;p&gt;Si la respuesta son los dos — los dos.&lt;/p&gt;

&lt;hr /&gt;

&lt;p&gt;¿Estás evaluando Lambda MicroVMs para un caso de uso específico? ¿O ya tienes AgentCore Runtime en producción y te preguntas si migrarlo tiene sentido? Me interesa saber qué arquitectura están considerando — los comentarios están abiertos.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/06/aws-lambda-microvms/&quot; target=&quot;_blank&quot;&gt;Anuncio oficial: AWS Lambda MicroVMs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/aws/run-isolated-sandboxes-with-full-lifecycle-control-aws-lambda-introduces-microvms/&quot; target=&quot;_blank&quot;&gt;Blog de lanzamiento: Run isolated sandboxes with full lifecycle control&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html&quot; target=&quot;_blank&quot;&gt;Developer Guide: AWS Lambda MicroVMs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/lambda/latest/microvm-api/Welcome.html&quot; target=&quot;_blank&quot;&gt;API Reference: Lambda MicroVMs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/lambda/latest/dg/microvms-integrations-claude-managed-agents.html&quot; target=&quot;_blank&quot;&gt;Guía: Lambda MicroVMs como sandbox para Claude Managed Agents&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/lambda/pricing/&quot; target=&quot;_blank&quot;&gt;Pricing: AWS Lambda MicroVMs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/pricing/&quot; target=&quot;_blank&quot;&gt;Pricing: Amazon Bedrock AgentCore&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://awsteele.com/blog/2026/06/23/some-notes-on-lambda-microvms.html&quot; target=&quot;_blank&quot;&gt;Hands-on notes de Aidan Steele — día del lanzamiento&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://theburningmonk.com/2026/06/what-you-need-to-know-about-lambda-microvms/&quot; target=&quot;_blank&quot;&gt;Análisis de Yan Cui: What you need to know about Lambda MicroVMs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html&quot; target=&quot;_blank&quot;&gt;Documentación oficial: AgentCore Runtime&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-command-shell.html&quot; target=&quot;_blank&quot;&gt;API: InvokeAgentRuntimeCommandShell&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Fri, 03 Jul 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/lambda-microvms-vs-agentcore-runtime.html</link>
                <guid isPermaLink="true">https://gerardo.dev/lambda-microvms-vs-agentcore-runtime.html</guid>
                
                <category>AWS</category>
                
                <category>Lambda</category>
                
                <category>AgentCore</category>
                
                <category>Runtime</category>
                
                <category>Firecracker</category>
                
                <category>GenAI</category>
                
                <category>Agents</category>
                
                <category>Serverless</category>
                
                
            </item>
        
            <item>
                <title>AgentCore Payments: Cuando Tu Agente Tiene Su Propia Wallet</title>
                <description>&lt;h1 id=&quot;agentcore-payments-cuando-tu-agente-tiene-su-propia-wallet-&quot;&gt;AgentCore Payments: Cuando Tu Agente Tiene Su Propia Wallet 💸&lt;/h1&gt;

&lt;p&gt;Imagina esto. Construiste un agente de análisis crediticio para tu fintech. Funciona hermoso en demo: razona, llama herramientas, escribe un dictamen. Pero cuando lo llevas a producción te das cuenta del problema real — el agente necesita datos. Datos de un bureau regional que cobra USD $0.015 por consulta. Una API de mercados que cobra fracciones de centavo por tick. Un proveedor de noticias financieras que pone paywall por artículo.&lt;/p&gt;

&lt;p&gt;Y tu equipo termina haciendo lo que hacen todos los equipos: integrar billing manualmente con cada proveedor. Cuentas separadas, llaves rotadas a mano, presupuestos en hojas de cálculo, alertas que llegan tarde, un PR cada vez que aparece un proveedor nuevo. Meses de ingeniería que no agrega valor a tu producto — solo plomería.&lt;/p&gt;

&lt;p&gt;El 7 de mayo de 2026, AWS anunció en preview &lt;strong&gt;Amazon Bedrock AgentCore Payments&lt;/strong&gt;, construido en sociedad con Coinbase y Stripe. Y por primera vez tu agente puede tener algo que suena absurdo cuando lo dices en voz alta: &lt;strong&gt;su propia wallet&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Vamos a ver por qué esto no es una curiosidad cripto, sino un cambio arquitectónico real para cualquiera que esté construyendo agentes en producción.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: &lt;strong&gt;AgentCore Payments alcanzó disponibilidad general (GA) el 18 de agosto de 2026&lt;/strong&gt;, según el &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/08/bedrock-agentcore-payments-ga/&quot; target=&quot;_blank&quot;&gt;anuncio oficial&lt;/a&gt;. Todo lo que sigue en este artículo describe el comportamiento del servicio en preview (junio 2026) y sigue siendo válido como guía de implementación, pero tres cosas cambiaron con GA que vale la pena saber antes de leer: (1) el protocolo ahora soporta, además del esquema x402 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;exact&lt;/code&gt; que uso en este artículo, un esquema &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;upto&lt;/code&gt;&lt;/strong&gt; para pagos medidos con techo de gasto (liquidado vía contrato Permit2) y el nuevo &lt;strong&gt;Machine Payment Protocol (MPP)&lt;/strong&gt;, un estándar HTTP-nativo alternativo a x402; (2) la consola agregó &lt;strong&gt;Quick Create&lt;/strong&gt; para aprovisionar credenciales de Coinbase sin generar API keys a mano; (3) si usas &lt;strong&gt;Coinbase CDP&lt;/strong&gt; como proveedor, ahora necesitas una &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-marketplace-subscription.html&quot; target=&quot;_blank&quot;&gt;suscripción obligatoria en AWS Marketplace&lt;/a&gt; (“Coinbase Wallets for AgentCore Payments”) — sin ella, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreatePaymentConnector&lt;/code&gt; y cualquier operación de wallet Coinbase fallan con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SubscriptionRequiredException&lt;/code&gt;. Stripe (Privy), el proveedor que uso en este artículo, no requiere esa suscripción. Ver también el &lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/amazon-bedrock-agentcore-payments-is-now-generally-available-enabling-agents-to-transact-safely-and-autonomously-at-scale/&quot; target=&quot;_blank&quot;&gt;blog de GA&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Una aclaración antes de empezar, porque importa: &lt;strong&gt;todo el código de este artículo fue ejecutado contra una cuenta AWS real en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us-east-1&lt;/code&gt;&lt;/strong&gt;, con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore&amp;gt;=1.9.1&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;strands-agents&amp;gt;=1.40.0&lt;/code&gt;. El flujo completo — agente → HTTP 402 → firma → settlement — terminó en una transacción real de 0.15 USDC en Base Sepolia que puedes verificar on-chain (&lt;a href=&quot;https://sepolia.basescan.org/tx/0x40bc34959ec85efbb4a0afa61c3735e17beadc2a6967d288a6149e89138526e4&quot; target=&quot;_blank&quot;&gt;tx &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0x40bc...26e4&lt;/code&gt;&lt;/a&gt;). Al final del artículo hay una sección de notas de trinchera con todo lo que se rompió en el camino, que es donde está la mitad del valor.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #1&lt;/strong&gt;: El problema que resuelve AgentCore Payments no es “agentes pagando con cripto”. Es la &lt;strong&gt;fricción económica de los micropagos máquina-a-máquina&lt;/strong&gt;. Las tarjetas tradicionales tienen comisiones mínimas de 30 centavos por transacción — pagar 1.5 centavos por una consulta es matemáticamente imposible: la comisión mínima se come la transacción entera. Stablecoins sobre el protocolo x402 hacen el costo unitario viable.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;el-desafío-la-economía-imposible-del-pay-per-call&quot;&gt;El Desafío: La Economía Imposible del Pay-per-Call&lt;/h2&gt;

&lt;p&gt;Hay una verdad incómoda en cómo se está moviendo el ecosistema de APIs en 2026. Cada vez más proveedores están cambiando de modelo de suscripción a pay-per-use. Datos de mercado, scraping de contenido, MCP servers especializados, hasta tiempo de ejecución de modelos. La razón es directa: los agentes consumen cantidades impredecibles y a veces enormes, y los proveedores quieren cobrar por valor entregado, no por asientos.&lt;/p&gt;

&lt;p&gt;Pero pay-per-use rompe en el caso de los micropagos. El dinero se mueve sobre lo que en el mundo financiero se llama un &lt;em&gt;payment rail&lt;/em&gt;: la infraestructura concreta que transporta cada pago — la red de tarjetas, las transferencias bancarias, los procesadores. Y cada rail tradicional cobra una comisión mínima por transacción, de alrededor de 30 centavos. Cuando lo que quieres mover son 1.5 centavos, esa comisión mínima no es un detalle: supera al monto entero. El proveedor pierde dinero en cada llamada y la economía simplemente no cierra. x402 existe precisamente porque introduce un rail nuevo, nativo de internet, donde el costo unitario de mover fracciones de centavo sí es viable.&lt;/p&gt;

&lt;p&gt;Hay además otro problema más sutil: la &lt;strong&gt;multiplicación de cuentas&lt;/strong&gt;. Si tu agente puede llegar a necesitar datos de 50 proveedores distintos, ¿realmente vas a abrir 50 cuentas de billing, manejar 50 sets de credenciales, monitorear 50 dashboards y rotar 50 llaves API? Tu equipo de plataforma se va a quemar antes de llegar a 10.&lt;/p&gt;

&lt;p&gt;El blog de lanzamiento de AWS lo dice bastante claro: tradicionalmente esto eran “meses de esfuerzo de ingeniería”, y las consecuencias de equivocarse son altas — un flujo de pago mal configurado no produce una mala respuesta, mueve dinero real.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #2&lt;/strong&gt;: Cuando evalúes si tu organización necesita esto, no preguntes “¿tengo agentes que paguen?”. Pregunta “¿cuántos proveedores externos consumiría mi agente si la fricción de integración fuera cero?”. Esa segunda lista suele ser 5x más grande que la primera. Ese delta es la oportunidad real.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;la-solución-el-protocolo-x402-revivido&quot;&gt;La Solución: El Protocolo x402 Revivido&lt;/h2&gt;

&lt;p&gt;Antes de entrar al servicio AWS, hay que entender el protocolo que lo hace posible — porque sin x402, AgentCore Payments sería solo otra capa de billing.&lt;/p&gt;

&lt;p&gt;x402 reutiliza un status code HTTP que llevaba casi tres décadas durmiente: el famoso &lt;strong&gt;HTTP 402 Payment Required&lt;/strong&gt;. Estaba en el estándar HTTP/1.1 desde fines de los 90, etiquetado como “reserved for future use”. Coinbase decidió que el futuro era ahora.&lt;/p&gt;

&lt;p&gt;El flujo es elegantemente simple (describo x402 &lt;strong&gt;v2&lt;/strong&gt;, la versión vigente del protocolo desde diciembre de 2025; v1 sigue soportada como legacy, y es la razón por la que vas a encontrar tutoriales viejos con nombres de header distintos):&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Tu agente llama un endpoint pagado: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET /premium-data&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;El servidor responde &lt;strong&gt;HTTP 402 Payment Required&lt;/strong&gt; con un header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-REQUIRED&lt;/code&gt; (JSON en base64) que indica esquema de pago, red en formato CAIP-2 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eip155:84532&lt;/code&gt; para Base Sepolia), contrato del activo, destinatario, monto y timeout&lt;/li&gt;
  &lt;li&gt;El agente firma una autorización de transferencia &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;transferWithAuthorization&lt;/code&gt; (EIP-3009) con su wallet y la incluye en un header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-SIGNATURE&lt;/code&gt; (en v1 legacy el header era &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;X-PAYMENT&lt;/code&gt;)&lt;/li&gt;
  &lt;li&gt;El servidor le pasa esa firma a un &lt;strong&gt;facilitator&lt;/strong&gt; (Coinbase hostea uno en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://x402.org/facilitator&lt;/code&gt;, gratis en testnet, pero la spec es abierta), que la verifica y la presenta on-chain — la mayoría de implementaciones corren sobre Base usando USDC&lt;/li&gt;
  &lt;li&gt;El servidor recibe la confirmación con el hash de la transacción, libera el contenido y responde 200 con los datos y un header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-RESPONSE&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Un detalle que sorprende la primera vez: la wallet del agente &lt;strong&gt;no necesita ETH para gas&lt;/strong&gt;. La firma EIP-3009 es off-chain; quien paga el gas de presentar la transacción es el facilitator. El agente solo necesita el stablecoin que va a gastar.&lt;/p&gt;

&lt;p&gt;Lo brillante es que todo esto ocurre &lt;strong&gt;en el mismo loop de razonamiento del agente&lt;/strong&gt;. No hay redirección a un checkout, no hay confirmación humana, no hay sleep esperando aprobación. Para el agente, llamar un endpoint pagado se siente igual que llamar uno gratuito — solo que con un par de pasos extra que AgentCore maneja en background.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #3&lt;/strong&gt;: x402 no es un estándar AWS. Es un protocolo abierto gobernado por la &lt;strong&gt;x402 Foundation&lt;/strong&gt;, donde AWS y Coinbase son miembros. Esto importa para tu decisión arquitectónica: el protocolo no te encadena a AgentCore. Si mañana migras a otro proveedor que soporte x402, los endpoints que ya consumes siguen funcionando. AWS está apostando a que su capa de gestión (gobernanza, identidad, observabilidad) sea suficiente diferenciador.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;anatomía-del-servicio-los-cinco-recursos-que-necesitas&quot;&gt;Anatomía del Servicio: Los Cinco Recursos que Necesitas&lt;/h2&gt;

&lt;p&gt;AgentCore Payments expone cinco conceptos que vas a manejar. Vale la pena mapearlos antes del código porque la separación es deliberada — cada uno corresponde a un nivel distinto de gobernanza.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;PaymentCredentialProvider&lt;/strong&gt;: vive en AgentCore Identity, no en Payments. Es donde guardas tus credenciales del proveedor de wallet (API keys de Coinbase CDP o credenciales de Privy para Stripe). Se almacena en Secrets Manager por debajo, y AgentCore lo referencia por ARN. Ningún componente que toca runtime ve directamente las credenciales.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;PaymentManager&lt;/strong&gt;: el recurso top-level en tu cuenta AWS. Define cómo los agentes se autentican al data plane (IAM o JWT personalizado) y el rol IAM que el servicio asume en runtime. Cuando lo creas, AgentCore provisiona automáticamente una workload identity en AgentCore Identity para ese manager. Una organización típicamente tiene varios PaymentManagers — por aplicación, por ambiente (dev/staging/prod) o por equipo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;PaymentConnector&lt;/strong&gt;: la conexión entre tu PaymentManager y un proveedor de pagos externo. Cada connector apunta a un PaymentCredentialProvider y especifica si va contra Coinbase CDP o Stripe Privy. Un PaymentManager puede tener varios connectors (por ejemplo, uno para Coinbase y otro para Stripe). El mapeo connector → credential provider es 1:1.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;PaymentInstrument&lt;/strong&gt;: la wallet embebida de cada usuario final. Se crea vía API con el email del usuario como cuenta vinculada, y el proveedor (Privy en mi caso) aprovisiona la wallet por debajo. La respuesta incluye un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;redirectUrl&lt;/code&gt; al &lt;strong&gt;wallet hub&lt;/strong&gt; hosted donde el usuario fondea la wallet y le otorga al agente el permiso de firmar. Sin ese grant explícito del usuario, el agente no puede mover un centavo — y vas a ver en las notas de trinchera que ese detalle no es decorativo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;PaymentSession&lt;/strong&gt;: el contexto de gasto para una interacción individual del agente con un usuario final. Aquí vive el guardrail más crítico — el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maxSpendAmount&lt;/code&gt; con su &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;currency&lt;/code&gt; y el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expiry&lt;/code&gt;. Cuando la sesión expira o el límite se alcanza, los siguientes intentos de pago son &lt;strong&gt;denegados deterministicamente en la capa de infraestructura&lt;/strong&gt;. El agente no puede negociar consigo mismo para saltarse este límite.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #4&lt;/strong&gt;: La distinción PaymentManager vs PaymentSession es la separación clásica de control plane vs data plane que ya conoces de otros servicios AgentCore. Los managers y connectors son setup de infraestructura — los creas una vez con Terraform o CDK. Las sessions son runtime — las creas y destruyes por cada interacción de usuario.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;implementación-paso-a-paso&quot;&gt;Implementación Paso a Paso&lt;/h2&gt;

&lt;p&gt;Voy a mostrar la integración mínima con Strands Agents — el SDK con el que AWS empuja más fuerte últimamente y el que mejor integra con AgentCore Payments. Todos los snippets que siguen fueron ejecutados contra la cuenta real; donde la documentación oficial y la API discrepan, gana lo que la API aceptó de verdad.&lt;/p&gt;

&lt;h3 id=&quot;paso-1-configurar-el-paymentcredentialprovider&quot;&gt;Paso 1: Configurar el PaymentCredentialProvider&lt;/h3&gt;

&lt;p&gt;Esto es operación de control plane. Lo haces una vez con tus credenciales del proveedor — yo elegí &lt;strong&gt;Stripe Privy&lt;/strong&gt; para este experimento, y es el camino que validé de punta a punta hasta el settlement on-chain.&lt;/p&gt;

&lt;p&gt;Primero necesitas las credenciales del lado Privy:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Crea una app &lt;strong&gt;dedicada&lt;/strong&gt; en &lt;a href=&quot;https://dashboard.privy.io&quot; target=&quot;_blank&quot;&gt;dashboard.privy.io&lt;/a&gt; (no reutilices apps que sirvan otros propósitos) y copia el &lt;strong&gt;App ID&lt;/strong&gt; y el &lt;strong&gt;App Secret&lt;/strong&gt;.&lt;/li&gt;
  &lt;li&gt;En &lt;strong&gt;Wallet Infrastructure → Authorization&lt;/strong&gt;, genera un par de llaves P-256. Eso te da el &lt;strong&gt;Authorization ID&lt;/strong&gt; y la &lt;strong&gt;Authorization Private Key&lt;/strong&gt;.&lt;/li&gt;
  &lt;li&gt;La private key viene con el prefijo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;wallet-auth:&lt;/code&gt; — &lt;strong&gt;quítaselo&lt;/strong&gt; antes de pasarla a AWS. La regex del API no acepta el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;:&lt;/code&gt; y el error que devuelve no te dice nada de esto.&lt;/li&gt;
&lt;/ol&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;ctrl&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore-control&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;region_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us-east-1&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Setup en control plane - corre una sola vez
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;provider&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;ctrl&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_payment_credential_provider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;creditBureauResearchCreds&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;credentialProviderVendor&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;StripePrivy&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;providerConfigurationInput&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;stripePrivyConfiguration&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;appId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&amp;lt;PRIVY_APP_ID&amp;gt;&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;appSecret&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&amp;lt;PRIVY_APP_SECRET&amp;gt;&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;authorizationId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&amp;lt;PRIVY_AUTH_ID&amp;gt;&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# base64 puro, SIN el prefijo &quot;wallet-auth:&quot;
&lt;/span&gt;            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;authorizationPrivateKey&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&amp;lt;PRIVY_AUTH_PRIVATE_KEY&amp;gt;&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;CREDENTIAL_PROVIDER_ARN&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;provider&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;credentialProviderArn&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Los secretos terminan en Secrets Manager (bajo el namespace &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-identity!&lt;/code&gt;), y todo lo demás los referencia por ARN. Si prefieres Coinbase CDP, el vendor es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CoinbaseCDP&lt;/code&gt; con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;coinbaseCdpConfiguration&lt;/code&gt; (campos &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apiKeyId&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apiKeySecret&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;walletSecret&lt;/code&gt;) — ojo que no es un solo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apiKey&lt;/code&gt; como sugieren algunos ejemplos tempranos.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: Desde GA, usar &lt;strong&gt;Coinbase CDP&lt;/strong&gt; como proveedor exige suscribirte primero a &lt;strong&gt;“Coinbase Wallets for AgentCore Payments”&lt;/strong&gt; en &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-marketplace-subscription.html&quot; target=&quot;_blank&quot;&gt;AWS Marketplace&lt;/a&gt;. La suscripción es gratuita en sí misma (no tiene cargo adicional), pero es obligatoria: sin ella, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreatePaymentConnector&lt;/code&gt; y cualquier operación de wallet Coinbase (crear instrumento, procesar pago) fallan con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SubscriptionRequiredException&lt;/code&gt;. El uso real del wallet Coinbase se sigue midiendo y facturando por Marketplace contra tu cuenta AWS, con la tarifa pública de Coinbase. Este requisito &lt;strong&gt;no aplica a Stripe (Privy)&lt;/strong&gt;, el proveedor que uso en el resto de este artículo — si seguiste el camino de Privy, no te afecta.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;paso-2-crear-el-paymentmanager-y-el-connector&quot;&gt;Paso 2: Crear el PaymentManager y el Connector&lt;/h3&gt;

&lt;p&gt;Esto también es control plane. El PaymentManager define el authorizer (IAM en mi caso porque el agente corre dentro de AWS) y el rol IAM que el servicio asume en runtime para leer las credenciales.&lt;/p&gt;

&lt;p&gt;Dos detalles que la documentación no destaca lo suficiente: el &lt;strong&gt;nombre&lt;/strong&gt; del PaymentManager debe ser &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;[a-zA-Z][a-zA-Z0-9]{0,47}&lt;/code&gt; — solo alfanumérico, sin guiones. Y la primera vez conviene crear el PaymentManager &lt;strong&gt;desde la consola&lt;/strong&gt;, que genera el service role por ti con la trust policy y los permisos correctos (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore:CreateWorkloadIdentity&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GetWorkloadAccessToken&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GetResourcePaymentToken&lt;/code&gt;). Si prefieres tu propio rol, la doc de &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html&quot; target=&quot;_blank&quot;&gt;IAM roles para payments&lt;/a&gt; tiene las policies exactas.&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# Crear el PaymentManager (el tipo va en --authorizer-type, no en un JSON)&lt;/span&gt;
aws bedrock-agentcore-control create-payment-manager &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt; us-east-1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;researchAgentPayments&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--authorizer-type&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;AWS_IAM&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--role-arn&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:iam::123456789012:role/service-role/AgentCorePaymentsServiceRole&quot;&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# Crear el Connector que apunta al credential provider&lt;/span&gt;
aws bedrock-agentcore-control create-payment-connector &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--region&lt;/span&gt; us-east-1 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--payment-manager-id&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;paymentmanager-a1b2c3d4e5&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--name&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;pocPrivyConnector&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--type&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;StripePrivy&quot;&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
    &lt;span class=&quot;nt&quot;&gt;--credential-provider-configurations&lt;/span&gt; &lt;span class=&quot;s1&quot;&gt;&apos;[{
      &quot;stripePrivy&quot;: {&quot;credentialProviderArn&quot;: &quot;&amp;lt;CREDENTIAL_PROVIDER_ARN&amp;gt;&quot;}
    }]&apos;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Al crear el connector, el servicio le &lt;strong&gt;agrega al service role&lt;/strong&gt; los permisos para leer los secretos de ese credential provider específico. Guárdate ese dato: en las notas de trinchera vas a ver por qué importa.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/agentcore-payment/console-payment-manager.png&quot; alt=&quot;PaymentManager en la consola AWS con el conector Stripe Privy en estado Ready&quot; /&gt;
&lt;em&gt;El PaymentManager del POC en la consola, con su conector Stripe (Privy) en Ready. El “transaction error rate 82.9%” del panel de observabilidad es la cicatriz honesta del debugging — cada uno de esos errores está documentado en las notas de trinchera.&lt;/em&gt;&lt;/p&gt;

&lt;h3 id=&quot;paso-3-crear-el-payment-instrument&quot;&gt;Paso 3: Crear el Payment Instrument&lt;/h3&gt;

&lt;p&gt;Aquí AgentCore aprovisiona la wallet embebida para tu agente. Cada usuario final tiene su propia wallet, identificada por &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;userId&lt;/code&gt;. Esto se hace una vez por usuario, no por sesión.&lt;/p&gt;

&lt;p&gt;Nota la forma real de los parámetros: el manager va por &lt;strong&gt;ARN&lt;/strong&gt; (no por ID), el tipo es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;EMBEDDED_CRYPTO_WALLET&lt;/code&gt;, y la red a nivel de instrumento es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ETHEREUM&lt;/code&gt; o &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SOLANA&lt;/code&gt; — Base no es una red separada aquí; a nivel x402 aparece como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eip155:8453&lt;/code&gt; (mainnet) o &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eip155:84532&lt;/code&gt; (Sepolia).&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;uuid&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;agentcore&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;region_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us-east-1&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Provisionar wallet embebida para el usuario final
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instrument&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;agentcore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_payment_instrument&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;paymentManagerArn&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;arn:aws:bedrock-agentcore:us-east-1:123456789012:payment-manager/paymentmanager-a1b2c3d4e5&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;paymentConnectorId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;privy-x1y2z3w4v5&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;paymentInstrumentType&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;EMBEDDED_CRYPTO_WALLET&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;paymentInstrumentDetails&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;embeddedCryptoWallet&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;network&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;ETHEREUM&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;linkedAccounts&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;email&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;emailAddress&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;cliente@fintech.com&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;userId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;cliente-fintech-001&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;clientToken&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;uuid&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;uuid4&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()),&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Wallet creada: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instrument&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;paymentInstrumentId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Wallet hub:    &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instrument&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;paymentInstrumentDetails&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;redirectUrl&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Ese &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;redirectUrl&lt;/code&gt; es el &lt;strong&gt;wallet hub&lt;/strong&gt; del proveedor (al momento de escribir esto, el servicio aún no devuelve la URL para el conector StripePrivy — el camino real hoy es desplegar el &lt;a href=&quot;https://github.com/privy-io/aws-agentcore-sdk&quot; target=&quot;_blank&quot;&gt;template oficial de Privy&lt;/a&gt;, un Next.js que corre con tu App ID en minutos). Ahí el usuario final hace dos cosas: fondear la wallet (transferencia cripto, tarjeta, Apple Pay o ACH — en testnet, USDC gratis del &lt;a href=&quot;https://faucet.circle.com&quot; target=&quot;_blank&quot;&gt;faucet de Circle&lt;/a&gt;) y conectar el agente vía &lt;strong&gt;“Connect agent”&lt;/strong&gt;, que agrega la authorization key de tu credential provider como signer autorizado de la wallet.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/agentcore-payment/wallet-hub-connect-agent.png&quot; alt=&quot;Wallet hub de Privy mostrando el setup completo y las wallets del usuario&quot; /&gt;
&lt;em&gt;El wallet hub: crear wallets, conectar el agente y fondear. La wallet de $19.70 es la del agente del POC — empezó con $20.00 y ya pagó dos consultas de $0.15 al bureau.&lt;/em&gt; &lt;strong&gt;Este paso no es opcional ni saltable&lt;/strong&gt; — es una decisión consciente de AWS: el agente nunca tiene acceso a los fondos sin consentimiento explícito del usuario. Si te lo saltas, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; falla con un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDeniedException: &quot;Privy credentials are invalid&quot;&lt;/code&gt; que no menciona permisos por ningún lado. Me costó una noche entera entender eso.&lt;/p&gt;

&lt;h3 id=&quot;paso-4-crear-la-paymentsession-con-límites&quot;&gt;Paso 4: Crear la PaymentSession con Límites&lt;/h3&gt;

&lt;p&gt;Aquí es donde la mayoría de los CTOs respiran tranquilos. Cada sesión tiene un límite de gasto que se enforza en la capa de infraestructura — no en el código del agente, donde un prompt injection podría intentar bypasearlo.&lt;/p&gt;

&lt;p&gt;Detalle importante: la sesión &lt;strong&gt;no está atada a un instrumento&lt;/strong&gt; — se crea por usuario, y el instrumento se especifica solo al procesar el pago. El expiry va en &lt;strong&gt;minutos&lt;/strong&gt;, no segundos:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Crear una sesión con presupuesto definido
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;agentcore&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_payment_session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;paymentManagerArn&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;arn:aws:bedrock-agentcore:us-east-1:123456789012:payment-manager/paymentmanager-a1b2c3d4e5&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;userId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;cliente-fintech-001&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;expiryTimeInMinutes&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;30&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;limits&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;maxSpendAmount&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;5.00&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;     &lt;span class=&quot;c1&quot;&gt;# objeto Amount, no string plano
&lt;/span&gt;            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;currency&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;USD&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;paymentSession&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;

&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Sesión: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;paymentSessionId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Presupuesto: USD &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;limits&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;maxSpendAmount&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Después de cada pago, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_payment_session&lt;/code&gt; te devuelve &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;availableLimits.availableSpendAmount&lt;/code&gt; — el presupuesto restante. En mi prueba: $2.00 → $1.85 después de una consulta de $0.15, decrementado por el servicio, no por mi código.&lt;/p&gt;

&lt;h3 id=&quot;paso-5-integración-con-el-agente-strands&quot;&gt;Paso 5: Integración con el Agente Strands&lt;/h3&gt;

&lt;p&gt;Esto es lo bonito. Una vez configurado todo lo anterior, agregar pagos automáticos al agente son seis líneas:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strands&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Agent&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strands_tools&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;http_request&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bedrock_agentcore.payments.integrations.config&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;AgentCorePaymentsPluginConfig&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bedrock_agentcore.payments.integrations.strands.plugin&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;AgentCorePaymentsPlugin&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Configurar el plugin con los recursos creados arriba
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;config&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;AgentCorePaymentsPluginConfig&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;payment_manager_arn&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;arn:aws:bedrock-agentcore:us-east-1:123456789012:payment-manager/paymentmanager-a1b2c3d4e5&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;user_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;cliente-fintech-001&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;payment_instrument_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;instrument&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;paymentInstrumentId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;payment_session_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;paymentSessionId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;region&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us-east-1&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# El plugin intercepta automáticamente las respuestas HTTP 402
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;plugin&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;AgentCorePaymentsPlugin&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Agente de análisis crediticio para fintech LATAM
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;Agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;system_prompt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Eres un analista de riesgo crediticio. Cuando te piden 
    evaluar a un solicitante, consultas el bureau regional para obtener score 
    actualizado y noticias relevantes. Justifica tu dictamen con datos 
    específicos del bureau.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;http_request&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;plugins&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;plugin&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Caso de uso real: análisis de un solicitante
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;respuesta&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;
    Analiza el perfil crediticio del solicitante con ID 12345678.
    Necesito score actualizado del bureau y cualquier flag reciente.
    Usa el endpoint: https://api.mi-bureau.com/v2/credit-report
&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Lo que pasa cuando el agente llama el endpoint (lo verifiqué transacción por transacción):&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;La herramienta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;http_request&lt;/code&gt; hace &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GET&lt;/code&gt; al endpoint del bureau&lt;/li&gt;
  &lt;li&gt;El bureau responde &lt;strong&gt;HTTP 402&lt;/strong&gt; con el header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-REQUIRED&lt;/code&gt; pidiendo USD 0.15 en USDC&lt;/li&gt;
  &lt;li&gt;El plugin de AgentCore Payments intercepta la respuesta antes de que llegue al loop del agente, parsea los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;accepts&lt;/code&gt; y selecciona la red compatible con el instrumento&lt;/li&gt;
  &lt;li&gt;Llama &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt;: el servicio valida la request, &lt;strong&gt;verifica el presupuesto&lt;/strong&gt; (USD 0.15 &amp;lt; USD 5.00 disponibles, sigue), y firma la autorización EIP-3009 con la wallet Privy del usuario — la respuesta vuelve con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;status: PROOF_GENERATED&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;El plugin reintenta la llamada con el header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-SIGNATURE&lt;/code&gt; adjunto&lt;/li&gt;
  &lt;li&gt;El bureau valida la prueba con el facilitator, la liquida on-chain, y devuelve los datos con el txHash en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-RESPONSE&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;El agente recibe los datos como si la llamada hubiera sido directa&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;El agente no sabe que pagó — solo sabe que obtuvo los datos. En mi corrida, el dictamen crediticio del agente cerraba con una línea que me sigue gustando: &lt;em&gt;“Costo de consulta bureau: USD $0.15 (liquidado on-chain en Base Sepolia)”&lt;/em&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔧 &lt;strong&gt;ProTip #5&lt;/strong&gt;: El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;expiryTimeInMinutes&lt;/code&gt; de la PaymentSession es tu mejor amigo en producción. Va en &lt;strong&gt;minutos&lt;/strong&gt; (15 es el mínimo que acepta el API, 480 el máximo). Para un agente síncrono de research, el mínimo de 15 minutos sobra. Para un agente de análisis de larga duración, puedes extender hasta las 8 horas. &lt;strong&gt;No uses sesiones eternas&lt;/strong&gt; — el blast radius si una sesión se compromete escala linealmente con su duración.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;qué-vas-a-ver-en-runtime&quot;&gt;Qué Vas a Ver en Runtime&lt;/h2&gt;

&lt;p&gt;Tres comportamientos que vas a observar cuando lleves esto a un PoC, y que verifiqué en la corrida real:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El overhead por pago es de pocos segundos por transacción.&lt;/strong&gt; El blog oficial de AWS para Financial Services menciona “sub-2-second settlement” para una transacción x402; en mi prueba real, el ciclo completo 402 → &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; → retry → settlement on-chain en Base Sepolia tomó del orden de 3-5 segundos (la firma vía &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; es rápida; la confirmación on-chain depende de la red). Para un agente que hace 5-6 llamadas pagadas en una sesión, el overhead acumulado no es despreciable cuando tu UX es interactiva — diseña pensando en async cuando sea posible, o muestra un indicador de progreso explícito al usuario final.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Los límites se enforzan deterministicamente en la capa de infraestructura.&lt;/strong&gt; Cuando configuras &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maxSpendAmount&lt;/code&gt; en la PaymentSession, AgentCore Payments verifica el presupuesto en cada &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; &lt;strong&gt;antes&lt;/strong&gt; de firmar la transacción. Si la operación excedería el presupuesto, el API devuelve un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ValidationException&lt;/code&gt; indicando presupuesto insuficiente (el SDK de Strands lo convierte en una excepción &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InsufficientBudget&lt;/code&gt; y levanta un interrupt que tu aplicación puede manejar). Esto vive fuera del alcance del LLM — no hay prompt injection que pueda bypasear un límite que está enforzado del lado del servicio. Si vas a probar esto, vale la pena hacer el experimento explícito: configura un límite bajo, instruye al agente a “ignorar restricciones de presupuesto” y observa que el bloqueo es absoluto.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La observabilidad llega gratis a CloudWatch.&lt;/strong&gt; Cada transacción genera vended logs y traces de X-Ray. Vas a poder ver, transacción por transacción, el monto exacto, el endpoint pagado, la latencia de firma, la latencia de settlement y el balance restante de la sesión. Para auditoría financiera esto es no-negociable, y AgentCore lo da sin que tengas que escribir una línea de código adicional.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/agentcore-payment/agentcore-payments-observability.png&quot; alt=&quot;Dashboard de observabilidad de AgentCore Payments en CloudWatch&quot; /&gt;
&lt;em&gt;El dashboard del PaymentManager del POC: invocaciones, transacciones, sesiones con presupuesto, errores por tipo, throttles y latencia de invocación (~286ms). Todo esto sin escribir una línea de instrumentación.&lt;/em&gt;&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #6&lt;/strong&gt;: Cuando vayas a probarlo, agenda explícitamente un experimento de “presupuesto excedido”. No es paranoia — es la forma más rápida de validar que tu integración respeta los límites antes de conectarla a un endpoint real con dinero real. Hazlo con un mock endpoint que devuelva 402 con un monto fijo, y observa el comportamiento cuando tu sesión se queda sin presupuesto. Esa prueba te ahorra el día que un agente en producción intente vaciar una wallet por un bug en el prompt.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;notas-de-trinchera-lo-que-se-rompió-antes-de-funcionar&quot;&gt;Notas de Trinchera: Lo Que Se Rompió Antes de Funcionar&lt;/h2&gt;

&lt;p&gt;Esta sección no existe en el blog de lanzamiento de AWS, y es exactamente por eso que la escribo. Entre el “hello world” de la documentación y la primera transacción real on-chain hubo varias horas de debugging repartidas en varias sesiones. Estos son los cuatro hallazgos que te van a ahorrar ese tiempo.&lt;/p&gt;

&lt;h3 id=&quot;1-la-dirección-del-token-importa-carácter-por-carácter&quot;&gt;1. La dirección del token importa, carácter por carácter&lt;/h3&gt;

&lt;p&gt;Mi mock server publicaba como asset la dirección de USDC en Base Sepolia… con un typo en el último carácter (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;...f3dCF71&lt;/code&gt; en lugar de la canónica &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;...f3dCF7e&lt;/code&gt;). El error nació de un “fix” anterior: una dirección que había quedado con 39 caracteres hex, a la que le agregué el dígito que faltaba — el equivocado.&lt;/p&gt;

&lt;p&gt;La buena noticia: el servicio hoy valida esto y el error te da la respuesta completa:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: Payment asset is not a supported USDC token address
for network &apos;eip155:84532&apos;.
Received: 0x036cbD53842c5426634e7929541eC2318F3DCF71.
Expected: 0x036CbD53842c5426634e7929541eC2318f3dCF7e
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Lección: &lt;strong&gt;no tipees direcciones de contratos a mano&lt;/strong&gt;. Tómalas del &lt;a href=&quot;https://developers.circle.com/stablecoins/usdc-contract-addresses&quot; target=&quot;_blank&quot;&gt;registro oficial de Circle&lt;/a&gt; y verifica el checksum.&lt;/p&gt;

&lt;h3 id=&quot;2-un-checksum-eip-55-inválido-te-da-un-500-sin-pistas&quot;&gt;2. Un checksum EIP-55 inválido te da un 500 sin pistas&lt;/h3&gt;

&lt;p&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;payTo&lt;/code&gt; de mi servidor de prueba era una dirección escrita a mano con las mayúsculas “a ojo” — checksum EIP-55 inválido. ¿El resultado? No un error de validación: un &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;InternalServerException: Something went wrong in processing your request&lt;/code&gt;&lt;/strong&gt;, con reintentos automáticos del SDK incluidos. Cuatro variantes del payload después, la única diferencia entre mi llamada que funcionaba y la que explotaba era el casing de la dirección destino.&lt;/p&gt;

&lt;p&gt;Lección: si &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; te tira 500 genéricos, valida el checksum de &lt;strong&gt;todas&lt;/strong&gt; las direcciones del payload (con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eth_utils.to_checksum_address&lt;/code&gt; o equivalente) antes de sospechar del servicio.&lt;/p&gt;

&lt;h3 id=&quot;3-la-trampa-iam-recrear-el-credentialprovider-rompe-el-service-role&quot;&gt;3. La trampa IAM: recrear el CredentialProvider rompe el service role&lt;/h3&gt;

&lt;p&gt;Esta es la más sutil y la más valiosa. Cuando creas un PaymentConnector, el servicio le agrega al service role del PaymentManager una policy con permisos sobre &lt;strong&gt;los secretos específicos&lt;/strong&gt; de ese credential provider (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;secretsmanager:GetSecretValue&lt;/code&gt; sobre ARNs concretos, más &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore:GetResourcePaymentToken&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;Durante el debugging roté credenciales: borré y recreé el credential provider &lt;strong&gt;con el mismo nombre&lt;/strong&gt;. Los secretos backing en Secrets Manager se recrearon con ARNs nuevos… pero la policy del rol siguió apuntando a los viejos. Resultado en runtime:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;AccessDeniedException: Failed to obtain resource payment token.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Un error que no menciona ni IAM, ni secretos, ni el credential provider. El fix es actualizar a mano la policy &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AmazonBedrockAgentCorePaymentConnectorPolicyProd_*&lt;/code&gt; con los ARNs nuevos — o recrear el connector para que el servicio re-aprovisione los permisos.&lt;/p&gt;

&lt;p&gt;Lección: el aprovisionamiento de permisos por-conector ocurre &lt;strong&gt;solo al crear el conector&lt;/strong&gt;. Si rotas o recreas el credential provider, el rol queda huérfano y nada te lo advierte.&lt;/p&gt;

&lt;h3 id=&quot;4-la-prueba-final-settlement-real-verificable-on-chain&quot;&gt;4. La prueba final: settlement real verificable on-chain&lt;/h3&gt;

&lt;p&gt;Con todo lo anterior resuelto, el ciclo completo quedó así: el agente Strands recibió el 402, el plugin llamó &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; (respuesta: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PROOF_GENERATED&lt;/code&gt; con la autorización EIP-3009 firmada por la wallet Privy), reintentó con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-SIGNATURE&lt;/code&gt;, y mi servidor liquidó el pago con el facilitator hosted de x402 — que presentó la &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;transferWithAuthorization&lt;/code&gt; on-chain pagando él el gas.&lt;/p&gt;

&lt;p&gt;La evidencia es pública y verificable:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Transacción&lt;/strong&gt;: &lt;a href=&quot;https://sepolia.basescan.org/tx/0x40bc34959ec85efbb4a0afa61c3735e17beadc2a6967d288a6149e89138526e4&quot; target=&quot;_blank&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0x40bc34959ec85efbb4a0afa61c3735e17beadc2a6967d288a6149e89138526e4&lt;/code&gt;&lt;/a&gt; (Base Sepolia, status success)&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Transfer&lt;/strong&gt;: wallet del agente → merchant, 0.15 USDC&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Saldos&lt;/strong&gt;: agente 20.00 → 19.85 USDC; merchant 0.00 → 0.15 USDC&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Presupuesto de sesión&lt;/strong&gt;: $2.00 → $1.85, decrementado por AgentCore&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Y como un solo punto de datos no es evidencia, lo corrí de nuevo: &lt;a href=&quot;https://sepolia.basescan.org/tx/0x79af051588bc414150a7508df24e5566b7f5930d65351b4127017a6d30772a8e&quot; target=&quot;_blank&quot;&gt;segunda liquidación&lt;/a&gt;, mismo flujo, saldo del agente ahora en 19.70 USDC.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/agentcore-payment/basescan-settlement.png&quot; alt=&quot;Detalle en Basescan de la transacción de settlement del agente&quot; /&gt;
&lt;em&gt;La liquidación vista en Basescan: transfer de 0.15 USDC desde la wallet del agente al merchant. Fíjate en el “Value: 0 ETH” y el “From” que no es la wallet del agente — quien presenta la transacción (y paga el gas) es el facilitator; la wallet del agente solo firmó la autorización EIP-3009.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Del lado merchant usé el paquete oficial &lt;a href=&quot;https://pypi.org/project/x402/&quot; target=&quot;_blank&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;x402&lt;/code&gt; de PyPI&lt;/a&gt; (de la x402 Foundation): los schemas v2 y el cliente del facilitator vienen listos, y el header &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PAYMENT-SIGNATURE&lt;/code&gt; que genera el plugin de AgentCore valida directo contra el schema &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PaymentPayload&lt;/code&gt; del paquete. AWS y el ecosistema x402 abierto son interoperables de verdad, no solo en el slide.&lt;/p&gt;

&lt;p&gt;Dos sutilezas más que descubrí en esta etapa: el facilitator hosted soporta x402 v2 con identificadores CAIP-2 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eip155:84532&lt;/code&gt;), pero para v1 legacy solo acepta el naming viejo (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;base-sepolia&lt;/code&gt;) — si tu merchant sirve v1 con CAIP-2, el settle falla. Y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; genera la prueba firmada &lt;strong&gt;aunque la wallet tenga saldo cero&lt;/strong&gt; (la firma es off-chain); el saldo solo importa cuando el facilitator intenta liquidar. No asumas que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PROOF_GENERATED&lt;/code&gt; implica fondos.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🧪 &lt;strong&gt;ProTip #7&lt;/strong&gt;: Si desarrollas en Windows, corre los demos con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PYTHONUTF8=1&lt;/code&gt;. La consola en cp1252 crashea con el primer emoji que el modelo decida poner en su respuesta — y los modelos aman los emojis.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;lecciones-a-tener-en-cuenta-antes-de-producción&quot;&gt;Lecciones a Tener en Cuenta Antes de Producción&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;El modelo de wallet por usuario genera fricción de onboarding.&lt;/strong&gt; Cada usuario final tiene que pasar por el wallet hub para fondear y autorizar al agente. Eso es UX adicional que tienes que diseñar en tu producto. Para una fintech con miles de usuarios, vale la pena evaluar si el modelo embebido (donde tu app abstrae completamente la wallet detrás de tu UI) o el modelo connect (donde el usuario trae su propia wallet) encaja mejor con tu flujo de KYC y onboarding existente.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Las regiones disponibles eran limitadas en preview.&lt;/strong&gt; us-east-1, us-west-2, eu-central-1 y ap-southeast-2, sin cobertura LATAM.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: Con GA (agosto 2026) la cobertura europea se completó — hoy son &lt;strong&gt;doce regiones&lt;/strong&gt;: us-east-1, us-east-2, us-west-2, eu-central-1, eu-west-1, eu-west-2, eu-south-1, eu-west-3, eu-south-2, eu-north-1, ap-southeast-1 y ap-southeast-2. Pero si tu workload tiene data residency requirements en Brasil o México, la brecha persiste: São Paulo sigue sin soporte, igual que Mumbai, Tokio y Seúl. Tu opción sigue siendo cross-region invocation desde Lambda en LATAM hacia una región soportada, asumiendo el costo de latencia adicional. Verifica la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html&quot; target=&quot;_blank&quot;&gt;tabla oficial de regiones&lt;/a&gt; antes de comprometerte con una arquitectura.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;El x402 Bazaar es interesante pero todavía angosto.&lt;/strong&gt; Se publicita “10,000+ endpoints x402” disponibles a través del Bazaar MCP server, pero la realidad es que la mayoría son endpoints de Coinbase y proveedores cripto-nativos. Para proveedores tradicionales de datos financieros LATAM (bureaus regionales, fintechs latinoamericanas), la adopción de x402 está empezando. Esto va a cambiar rápido, pero hoy probablemente tengas que conversar con tus proveedores existentes para que implementen x402 — o levantar un adapter intermedio que traduzca tu billing actual a x402.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El costo real por transacción no es el gas — es la wallet operation fee del proveedor.&lt;/strong&gt; Aquí hay un detalle que cambia el modelo económico y que conviene tener claro antes de prometerle números a tu CFO. El gas on-chain sobre Base es marginal: el blog oficial de AWS para Financial Services menciona ~USD $0.0001 por settlement. Pero ese no es el costo dominante. Cada &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt; dispara una operación de wallet en tu proveedor, y eso se cobra aparte: al momento de escribir esto, Coinbase CDP cobra del orden de USD $0.005 por wallet operation, y Stripe Privy tiene su propia fee por &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ProcessPayment&lt;/code&gt;. Para una consulta de $0.15 eso es ~3% de overhead; pero para el caso de fracciones de centavo del ProTip #1 — pagar $0.015 por un tick de datos — esos $0.005 son &lt;strong&gt;un tercio del costo de la transacción&lt;/strong&gt;. La conclusión práctica: x402 hace viable el micropago frente a la tarjeta tradicional, pero la wallet operation fee del proveedor define tu piso real. Por debajo de cierto ticket, ni x402 cierra la economía. Modela ese costo por proveedor antes de comprometerte a un volumen.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #8&lt;/strong&gt;: Si vas a llevar esto a producción, decide desde el día uno cómo vas a reflejar las transacciones de la wallet del agente en tu contabilidad. Cada llamada pagada es un gasto real que tu sistema financiero tiene que reconciliar. Las APIs de Coinbase CDP y Stripe Privy permiten exportar el historial completo de transacciones — agenda un job de reconciliación nocturno desde el día uno o vas a estar pagando un consultor forense seis meses después para reconstruir qué pasó.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;la-foto-completa-pagos-como-la-cuarta-capa-de-un-agente&quot;&gt;La Foto Completa: Pagos como la Cuarta Capa de un Agente&lt;/h2&gt;

&lt;p&gt;Si sigues esta serie, ya cubrimos las tres capas de estado de un agente en AgentCore:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;AgentCore Policy&lt;/a&gt;&lt;/strong&gt; — Lo que el agente &lt;em&gt;puede&lt;/em&gt; hacer&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;AgentCore Memory Episódica&lt;/a&gt;&lt;/strong&gt; — Lo que el agente &lt;em&gt;aprendió&lt;/em&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/agentcore-session-storage.html&quot; target=&quot;_blank&quot;&gt;AgentCore Session Storage&lt;/a&gt;&lt;/strong&gt; — Lo que el agente &lt;em&gt;construyó&lt;/em&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;AgentCore Payments agrega una cuarta capa que cambia cualitativamente lo que un agente puede hacer:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;AgentCore Payments&lt;/strong&gt; — Lo que el agente puede &lt;em&gt;adquirir&lt;/em&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Y esa palabra, &lt;em&gt;adquirir&lt;/em&gt;, es la que vuelve esto interesante. Un agente con razonamiento, herramientas, memoria y filesystem es un agente sofisticado. Un agente con razonamiento, herramientas, memoria, filesystem &lt;strong&gt;y la capacidad de pagar por recursos&lt;/strong&gt; es algo cualitativamente distinto — es un actor económico autónomo dentro de límites que tú defines.&lt;/p&gt;

&lt;p&gt;Para un CTO de fintech LATAM, eso abre un espacio de diseño nuevo. Tu agente de análisis crediticio puede consultar bureaus regionales bajo demanda en lugar de mantener suscripciones planas. Tu agente de research de mercados puede pagar por feeds de tick data solo cuando hay volatilidad real. Tu agente de KYC puede consultar listas OFAC pagadas en tiempo real sin que tu equipo de plataforma haya integrado cada proveedor a mano.&lt;/p&gt;

&lt;p&gt;La pregunta arquitectónica importante no es “¿debería usar AgentCore Payments?”. Es &lt;strong&gt;“¿cuántos contratos plan-based estoy pagando hoy de los que ya pasaría a pay-per-call si la fricción técnica fuera cero?”&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Esa lista, en tu propia organización, probablemente sea más larga de lo que imaginas.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;AgentCore Payments empezó este artículo en preview; desde el 18 de agosto de 2026 está en &lt;strong&gt;disponibilidad general&lt;/strong&gt;, con más regiones, soporte para MPP y el esquema x402 &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;upto&lt;/code&gt;, y Quick Create para Coinbase. El ecosistema de proveedores x402 sigue siendo joven fuera de Coinbase y cripto-nativos, y va a haber gotchas que descubrirás solo cuando lo metas en tu propio caso de uso — los cuatro que documento arriba siguen vigentes tal cual, GA no los cambió. Pero el cambio que representa el servicio no es cosmético.&lt;/p&gt;

&lt;p&gt;Es la primera vez que una nube hyperscaler trata “pagar por algo” como una primitiva de plataforma con la misma calidad de gobernanza que el resto de los recursos AWS — identity, observability, IAM, audit trails. Antes era plomería que cada equipo construía. Ahora es un servicio gestionado, con todas las limitaciones y ventajas que eso implica.&lt;/p&gt;

&lt;p&gt;Para CTOs y arquitectos cloud evaluando dónde meter la próxima inversión en agentes, mi sugerencia honesta: agenda una semana para hacer un PoC con un caso de uso concreto. No con el caso de uso final perfecto — con el más simple que puedas armar. Vas a aprender más sobre las implicaciones reales en 5 días de tener-tu-agente-pagando-cosas que en 5 meses de leer blogposts (incluido este).&lt;/p&gt;

&lt;p&gt;Y si esa primera semana te convence — y vale la pena ver qué dices después de la primera transacción exitosa de 1.5 centavos — entonces empieza a diseñar la pregunta más interesante: &lt;strong&gt;qué tipo de producto puedes construir tú que hoy es imposible porque la fricción de pagos era el bloqueador&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Esa pregunta sigue sin respuesta para la mayoría de las organizaciones. Y el primero en responderla en tu vertical probablemente se quede con ese mercado.&lt;/p&gt;

&lt;hr /&gt;

&lt;p&gt;¿Estás evaluando AgentCore Payments en tu organización? ¿Tu caso de uso son micropagos de datos, transacciones comerciales, o algo todavía más extraño? Me interesa saber qué están considerando — los comentarios están abiertos.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/agents-that-transact-introducing-amazon-bedrock-agentcore-payments-built-with-coinbase-and-stripe/&quot; target=&quot;_blank&quot;&gt;Blog de lanzamiento: Agents that transact&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html&quot; target=&quot;_blank&quot;&gt;Documentación oficial: AgentCore Payments&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-getting-started.html&quot; target=&quot;_blank&quot;&gt;Get started con AgentCore Payments&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-iam-roles.html&quot; target=&quot;_blank&quot;&gt;IAM roles para AgentCore Payments&lt;/a&gt; — el modelo de 4 roles y los permisos por-conector&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-process-payment.html&quot; target=&quot;_blank&quot;&gt;Procesar un pago (formatos v1/v2 de ProcessPayment)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://www.x402.org/&quot; target=&quot;_blank&quot;&gt;Especificación x402 Protocol&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://pypi.org/project/x402/&quot; target=&quot;_blank&quot;&gt;Paquete &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;x402&lt;/code&gt; en PyPI&lt;/a&gt; — schemas, middleware y cliente de facilitator&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://bazaar.x402.org/&quot; target=&quot;_blank&quot;&gt;Coinbase x402 Bazaar&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://developers.circle.com/stablecoins/usdc-contract-addresses&quot; target=&quot;_blank&quot;&gt;USDC contract addresses (Circle)&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://faucet.circle.com&quot; target=&quot;_blank&quot;&gt;Faucet de USDC testnet (Circle)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Thu, 11 Jun 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/agentcore-payments.html</link>
                <guid isPermaLink="true">https://gerardo.dev/agentcore-payments.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>AgentCore</category>
                
                <category>Payments</category>
                
                <category>x402</category>
                
                <category>GenAI</category>
                
                <category>LLM</category>
                
                <category>Agents</category>
                
                <category>Fintech</category>
                
                
            </item>
        
            <item>
                <title>AWS Agent Registry: gobernanza y catálogo privado de agentes para evitar la proliferación</title>
                <description>&lt;p&gt;Hace dos semanas, en una llamada con un amigo, salió la frase que vengo escuchando en distintos formatos desde principios de año:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;“Tengo cuatro equipos construyendo agentes en paralelo. Hace dos meses descubrí que dos de ellos estaban haciendo lo mismo. Lo peor: ninguno tiene los mismos guardrails.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;No es la primera vez. La conversación se repite con variaciones predecibles entre líderes de plataforma de varias empresas latinoamericanas con las que vengo trabajando: la primera ola de agentes corporativos llegó por iniciativa de cada squad, sin coordinación, y ahora alguien tiene que poner orden antes de que la lista pase de 8 agentes a 50.&lt;/p&gt;

&lt;p&gt;Si estás del lado de “todavía no llegamos a 8”, buenas noticias: AWS sacó en preview el servicio que necesitabas hace seis meses. El &lt;strong&gt;9 de abril de 2026&lt;/strong&gt; anunciaron &lt;strong&gt;AWS Agent Registry&lt;/strong&gt;, un catálogo privado para tu organización donde se publican agentes, servidores MCP, skills y recursos personalizados con un flujo de aprobación enchufable. Si estás del lado de “tengo 50 agentes y un mapa hecho a mano en Confluence”, también buenas noticias: el camino para migrar al Registry empieza el día que tu organización entiende lo que viene a continuación.&lt;/p&gt;

&lt;p&gt;Este post es el resultado de pasar la última semana levantando un laboratorio integral en mi cuenta — desde Terraform de IAM hasta Claude Code conectado al Registry vía MCP — y documentando las &lt;strong&gt;doce trampas reales&lt;/strong&gt; que aparecieron en el camino (once de la API hoy más una de la spec A2A upstream que ya pinta en el horizonte). Algunas son sutiles. Cuatro de ellas van a hacer que tu primer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create_registry_record&lt;/code&gt; falle de manera no obvia. Te las marco para que no pierdas el rato que perdí yo.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: &lt;strong&gt;AWS Agent Registry alcanzó disponibilidad general (GA) el 31 de agosto de 2026&lt;/strong&gt;, según el &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/08/aws-agent-registry-generally-available/&quot; target=&quot;_blank&quot;&gt;anuncio oficial&lt;/a&gt;. Todo lo que sigue en este artículo describe el comportamiento del servicio en preview (abril 2026) y el laboratorio de Aurora Capital sigue siendo válido tal cual — las 12 trampas de la API no cambiaron con GA. Lo que sí cambió: hay pricing real (ver FAQ de costos, más abajo), y GA cerró tres de las cinco brechas que documento en “Lo que todavía no está” (soporte IaC, federación cross-account, auto-indexado de runtimes) — marcadas inline donde corresponde. Las regiones se mantienen igual, 5 en total.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #1&lt;/strong&gt;: La gobernanza de agentes es una decisión del día 1, no del día 100. La diferencia entre “qué bueno que pusimos un catálogo” y “ahora tenemos que migrar 47 agentes hacia el catálogo retroactivamente” se mide en semanas-persona perdidas. El servicio ya existe; el caso de adopción es contundente.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Si vienes de mi último post — el &lt;a href=&quot;/chunking-benchmark.html&quot; target=&quot;_blank&quot;&gt;benchmark de las 5 estrategias de chunking en Bedrock Knowledge Bases&lt;/a&gt; — el ángulo de éste es distinto. Allá el lector ideal era el desarrollador iterando sobre RAG. Acá es quien pisa el freno antes de que la dispersión se vuelva irreversible: CTOs, líderes de plataforma y arquitectos que están viendo crecer el inventario de agentes y entienden que sin un catálogo van a terminar reinventando ServiceCatalog desde cero, peor.&lt;/p&gt;

&lt;h2 id=&quot;el-costo-real-del-agente-duplicado&quot;&gt;El costo real del agente duplicado&lt;/h2&gt;

&lt;p&gt;Cuando escuchas “duplicación”, quizás te imaginas dos desarrolladores escribiendo el mismo código. La realidad de la duplicación de agentes es peor: dos pipelines distintos consumiendo presupuesto de Bedrock, dos conjuntos de roles IAM que nadie audita, dos integraciones con Jira que se contradicen entre sí cuando el mismo ticket viaja por ambas, y la incertidumbre de no saber cuál de los dos es el “oficial” cuando llega un incidente de producción.&lt;/p&gt;

&lt;p&gt;Multiplícalo por una organización con siete squads y la primera ola de adopción de GenAI:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;Squad SRE construye un agente de triage de incidentes que llama a Jira.&lt;/li&gt;
  &lt;li&gt;Squad Customer Lifecycle construye un agente de onboarding que también llama a Jira para crear tickets de KYC.&lt;/li&gt;
  &lt;li&gt;Squad Billing construye un servidor MCP para Stripe que internamente reusa una función de redacción de PII que ya existía como herramienta aislada en el equipo de Compliance.&lt;/li&gt;
  &lt;li&gt;Squad Data tiene un envoltorio de Athena que el equipo de Analytics no encuentra y reconstruye con SQL libre, abriendo un agujero de seguridad que el primero ya había cerrado.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Cada decisión individual fue racional. Sumadas, son una pesadilla de gobernanza. Y ningún ticket de Jira va a coordinar esto retroactivamente — para cuando el problema es visible, ya tienes que escribir un programa de migración con su propio backlog.&lt;/p&gt;

&lt;p&gt;La pregunta no es si necesitas un catálogo de agentes. Es si lo estás poniendo cuando puedes (8 agentes) o cuando te toca (50).&lt;/p&gt;

&lt;h2 id=&quot;aws-agent-registry-en-dos-minutos&quot;&gt;AWS Agent Registry, en dos minutos&lt;/h2&gt;

&lt;p&gt;Agent Registry vive bajo la sección &lt;strong&gt;Discover&lt;/strong&gt; en la consola de AgentCore — no bajo Build ni Test. Esa ubicación dice algo: AWS está marcando el Registry como un servicio de descubrimiento, no de construcción. Es un detalle de experiencia de usuario que predice cómo va a evolucionar el producto: la integración futura con Runtime y Gateway probablemente sea automática (un agente desplegado se autoindexa), pero hoy no lo es. Por ahora todo es manual.&lt;/p&gt;

&lt;p&gt;Lo que catalogás:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;MCP servers&lt;/strong&gt; — valida contra el &lt;a href=&quot;https://modelcontextprotocol.io&quot; target=&quot;_blank&quot;&gt;schema oficial MCP&lt;/a&gt;. Los servidores MCP que tu agente cliente debe saber que existen.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Agents&lt;/strong&gt; — valida contra el &lt;a href=&quot;https://a2aproject.github.io/A2A/&quot; target=&quot;_blank&quot;&gt;schema A2A AgentCard&lt;/a&gt;. Agentes corporativos que otros agentes pueden invocar.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Skills&lt;/strong&gt; — capacidades reutilizables (paquetes Python, librerías) con su propia metadata más documentación markdown.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Custom resources&lt;/strong&gt; — cualquier JSON que definas. Es la salida de escape para herramientas Lambda, endpoints HTTPS internos o cualquier cosa que no encaje en MCP, A2A o Skill.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Cada record vive un &lt;strong&gt;ciclo de aprobación&lt;/strong&gt;:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/lifecycle.svg&quot; alt=&quot;Diagrama del ciclo de vida de un Registry Record: DRAFT, PENDING_APPROVAL, APPROVED, DEPRECATED y REJECTED&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Solo los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;APPROVED&lt;/code&gt; aparecen en búsquedas. Los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;REJECTED&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;DEPRECATED&lt;/code&gt; se mantienen como historial pero son invisibles para los consumers.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Costo durante el preview&lt;/strong&gt;: cero. Cuando salga a disponibilidad general (GA) el precio combina dos ejes: “Net Records” (registros vivos en cualquier momento; borrar uno descuenta) y API calls de discovery (Search, List, Get).&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: Con GA (31 de agosto de 2026) el precio ya es real, tal como se anticipaba: Net Records + API calls de discovery, con &lt;strong&gt;Free Tier mensual&lt;/strong&gt; de 5,000 Net Records, 1,000,000 de llamadas Search y 2,000,000 de llamadas Get+List combinadas — ver la &lt;a href=&quot;https://aws.amazon.com/bedrock/agentcore/pricing/&quot; target=&quot;_blank&quot;&gt;página oficial de pricing&lt;/a&gt;. Un laboratorio del tamaño del de este artículo (8 records, un puñado de búsquedas) se queda cómodamente dentro del Free Tier.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Regiones del preview&lt;/strong&gt; (cinco): &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us-east-1&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us-west-2&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ap-southeast-2&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ap-northeast-1&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;eu-west-1&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: GA no amplió la cobertura regional — siguen siendo las mismas cinco. Verifica siempre la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html&quot; target=&quot;_blank&quot;&gt;tabla oficial de regiones&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Superficie de API&lt;/strong&gt; (control plane más data plane):&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Plano&lt;/th&gt;
      &lt;th&gt;Acciones clave&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-control&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateRegistry&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateRegistryRecord&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SubmitRegistryRecordForApproval&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;UpdateRegistryRecordStatus&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SearchRegistryRecords&lt;/code&gt;, MCP endpoint HTTP path-based&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;&lt;strong&gt;boto3 ≥ 1.42.87&lt;/strong&gt; es requisito; si tu SDK es más antiguo, los métodos no existen. La AWS CLI llegó tarde: los servicios &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-control&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore&lt;/code&gt; aterrizaron en &lt;strong&gt;AWS CLI v2 ≥ 2.34.28&lt;/strong&gt;. Si al ejecutar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws bedrock-agentcore-control list-registries&lt;/code&gt; recibes &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Found invalid choice&lt;/code&gt;, corre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws --version&lt;/code&gt; y sube a 2.34.28 o posterior. boto3 los tiene desde &amp;gt;= 1.42.87, así que para iterar rápido durante el preview lo más simple es Python.&lt;/p&gt;

&lt;h2 id=&quot;las-cuatro-personas-la-espina-dorsal-del-modelo&quot;&gt;Las cuatro personas: la espina dorsal del modelo&lt;/h2&gt;

&lt;p&gt;Lo que más me llamó la atención mientras leía la documentación de IAM del Registry fue que AWS nombra explícitamente cuatro personas. No es marketing — es un mapa directo a políticas IAM separadas, y es la primera vez en AgentCore que la separación de roles está tan limpia.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/personas.svg&quot; alt=&quot;Diagrama de las 4 personas del modelo IAM: Administrator, Publisher, Curator y Consumer con sus permisos delimitados&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Administrator&lt;/strong&gt;. El dueño de la infraestructura del Registry. Crea los registries, define la autenticación (IAM o JWT), conecta EventBridge para automatizar la aprobación, decide si la aprobación automática está activa (en producción siempre desactivada). Tiene acceso total — incluida la posibilidad de aprobar o rechazar manualmente cualquier record sin pasar por el Curator.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Publisher&lt;/strong&gt;. El constructor dentro de los squads. Crea registry records que describen sus recursos, itera sobre ellos en estado DRAFT y los envía para aprobación cuando están listos. Lo que &lt;strong&gt;no puede&lt;/strong&gt; hacer (y vas a ver &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDenied&lt;/code&gt; real si lo intenta): aprobar sus propios records, borrar registries, ni siquiera borrar sus propios records publicados.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Curator&lt;/strong&gt; (o Approver). El guardián de calidad. Recibe records en estado pending approval — vía correo, Slack o ticket según cómo conectes EventBridge — evalúa contra los estándares de la organización y aprueba o rechaza con razón obligatoria. También deprecia records que ya no se usan. Lo que no puede: crear ni modificar el contenido de un record. Su único superpoder es decidir transiciones de estado.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Consumer&lt;/strong&gt;. Cualquiera que busque recursos para usar. Solo ve records APPROVED. Por defecto opera contra el data plane (Search más MCP endpoint). Su rol es el más restringido y el más interesante: cuando conectás Claude Code o cualquier agente cliente al Registry, las credenciales que firman cada request son las del rol Consumer.&lt;/p&gt;

&lt;p&gt;Esta separación parece obvia hasta que tratas de implementarla. Cuando armas las políticas inline con alcance mínimo persona por persona, vas a chocar contra el primer hallazgo del laboratorio — y es uno que la documentación no anticipa.&lt;/p&gt;

&lt;h2 id=&quot;manos-a-la-obra-el-laboratorio-de-aurora-capital&quot;&gt;Manos a la obra: el laboratorio de Aurora Capital&lt;/h2&gt;

&lt;p&gt;Para aterrizar todo esto armé un laboratorio que simula una fintech latinoamericana ficticia llamada &lt;strong&gt;Aurora Capital&lt;/strong&gt;, con siete squads y la primera ola de agentes corporativos. La organización está construida con suficiente especificidad para que los demos no se sientan de juguete: monedas reales (MXN, COP, ARS, BRL, CLP, PEN), squads con dueños identificables y casos de uso plausibles donde la duplicación es inminente.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/architecture.svg&quot; alt=&quot;Arquitectura del laboratorio Aurora Capital: Terraform para IAM y EventBridge, Python para Registry y records, MCP proxy y Claude Code como consumer&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Los ocho records del catálogo:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;#&lt;/th&gt;
      &lt;th&gt;Tipo&lt;/th&gt;
      &lt;th&gt;Recurso&lt;/th&gt;
      &lt;th&gt;Owner&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;1&lt;/td&gt;
      &lt;td&gt;MCP server&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;jira-mcp-server&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad SRE&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;2&lt;/td&gt;
      &lt;td&gt;MCP server&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe-payments-mcp&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad Billing&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;3&lt;/td&gt;
      &lt;td&gt;A2A Agent&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;incident-triage-agent&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad SRE&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;4&lt;/td&gt;
      &lt;td&gt;A2A Agent&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;customer-onboarding-agent&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad Customer Lifecycle&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;5&lt;/td&gt;
      &lt;td&gt;Skill&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pii-redaction-skill&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad Compliance&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;6&lt;/td&gt;
      &lt;td&gt;Skill&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;currency-conversion-skill&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad Treasury&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;7&lt;/td&gt;
      &lt;td&gt;Custom&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;athena-query-tool&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad Data&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;8&lt;/td&gt;
      &lt;td&gt;Custom&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;slack-notifier-tool&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Squad Platform&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Y la dinámica del demo: el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;slack-notifier-tool&lt;/code&gt; lo va a rechazar el Curator porque su endpoint mTLS no está en el catálogo de herramientas internas documentado. Los otros siete pasan a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;APPROVED&lt;/code&gt; y se vuelven descubribles.&lt;/p&gt;

&lt;p&gt;La pila técnica que armé tiene dos partes claras:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Terraform&lt;/strong&gt; crea los 4 roles IAM (uno por persona), un tópico SNS con suscripción por correo y una regla EventBridge que captura &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SubmitRegistryRecordForApproval&lt;/code&gt; y notifica al Curator.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Python (boto3)&lt;/strong&gt; crea el registry y los records, y ejecuta los envíos, las aprobaciones y las búsquedas.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;¿Por qué no Terraform para el Registry? Porque al &lt;strong&gt;28 de abril de 2026&lt;/strong&gt;, ni &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;hashicorp/aws&lt;/code&gt; (v6.42.0) ni &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;hashicorp/awscc&lt;/code&gt; (v1.81.0) tienen &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws_bedrockagentcore_registry&lt;/code&gt; ni &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_record&lt;/code&gt;. El AWS Provider tiene 12 recursos AgentCore (runtime, gateway, browser, code interpreter, memory, etc.) pero el Registry no aparece todavía. Eso te dice exactamente qué tan nuevo es: la forma de la API se está estabilizando todavía.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #2&lt;/strong&gt;: Si en tu organización la regla es “todo en Terraform o nada”, el Registry no califica todavía. La forma sana de adoptarlo durante el preview es dejar IAM y EventBridge en Terraform (donde son fundacionales y no van a cambiar) y manejar el Registry desde Python o desde la consola hasta que el provider lo soporte. No ensucies tu código base con un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;local-exec&lt;/code&gt; apurado.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: Este gap se cerró con GA. El &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/08/aws-agent-registry-generally-available/&quot; target=&quot;_blank&quot;&gt;anuncio de disponibilidad general&lt;/a&gt; confirma soporte para provisionar y gestionar registries como código con &lt;strong&gt;AWS CloudFormation, Terraform y AWS CDK&lt;/strong&gt;. Si estás retomando este laboratorio hoy, vale la pena migrar la parte de Python (creación de registry y records) a tu IaC habitual en lugar de mantener el workaround del ProTip #2 — verifica la versión mínima del provider en el registro de Terraform antes de migrar.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;el-primer-choque-con-iam-que-la-documentación-no-anticipa&quot;&gt;El primer choque con IAM (que la documentación no anticipa)&lt;/h2&gt;

&lt;p&gt;Con los 4 roles armados con políticas inline que tienen exactamente los permisos de cada persona, lancé el primer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create_registry&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;control&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore-control&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;control&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_registry&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;aurora-capital-prod&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Aurora Capital — registry corporativo de agentes&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;registryArn&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;])&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# → arn:aws:bedrock-agentcore:us-east-1:123456789012:registry/aurora-capital-prod
&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;status&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;])&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# → CREATING
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;API response 200 OK. Status CREATING, esperable. Al minuto siguiente, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_registry&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;aurora-capital-prod&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;status&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;CREATE_FAILED&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;statusReason&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Unable to create workload identity because access was denied.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CREATE_FAILED&lt;/code&gt;. ¿Acceso denegado por qué? El registro de CloudTrail aclara: internamente, el Registry provisiona un &lt;strong&gt;workload identity&lt;/strong&gt; asociado al registry, y esa creación se hace con las credenciales del caller (mi rol Admin). El rol Admin con una política inline de solo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore:*Registry*&lt;/code&gt; no tiene los permisos suficientes — faltan acciones internas de AgentCore más IAM &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PassRole&lt;/code&gt; más algo de Secrets Manager y KMS para el workload identity.&lt;/p&gt;

&lt;p&gt;El arreglo correcto es la política administrada oficial:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;aws_iam_role_policy_attachment&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;admin_full_access&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;role&lt;/span&gt;       &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;aws_iam_role&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;admin&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;name&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;policy_arn&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:iam::aws:policy/BedrockAgentCoreFullAccess&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BedrockAgentCoreFullAccess&lt;/code&gt; incluye: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore:*&lt;/code&gt; sobre cualquier ARN, IAM &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;GetRole&lt;/code&gt;/&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ListRoles&lt;/code&gt;/&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PassRole&lt;/code&gt; (este último limitado a roles &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;*BedrockAgentCore*&lt;/code&gt; con condición &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;iam:PassedToService = bedrock-agentcore.amazonaws.com&lt;/code&gt;), Secrets Manager para secrets prefijados &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore*&lt;/code&gt;, y KMS condicionado a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws:CalledVia = bedrock-agentcore.amazonaws.com&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #3&lt;/strong&gt;: La política inline con alcance mínimo funciona perfecto para Publisher, Curator y Consumer — esos AccessDenied del demo de gobernanza son reales y se sostienen. Pero el rol que ejecuta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateRegistry&lt;/code&gt; necesita &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BedrockAgentCoreFullAccess&lt;/code&gt;. La documentación de “Get Started” usa esta política administrada en los ejemplos sin remarcar por qué; cuando intentas ser más restrictivo, la API responde 200 y el registry queda muerto en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CREATE_FAILED&lt;/code&gt;. Es un patrón engañoso que vale la pena conocer de antemano.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Y una segunda sutileza relacionada, esta vez de Terraform y SSO:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;aws_caller_identity&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;current&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# Si corrés desde una sesión SSO, devuelve:&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_AdministratorAccess_31df6209ac649496/gerardo.arroyo&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Si usas ese ARN literal como Principal en la trust policy de tus 4 roles, IAM puede rechazarlo (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;MalformedPolicyDocument&lt;/code&gt;) o aceptarlo y dejarte con un principal atado a un session name que cambia entre inicios de sesión. Hay que derivar el rol IAM permanente del permission set de SSO. Yo lo resolví con un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;local&lt;/code&gt; de Terraform que detecta SSO y traduce:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;locals&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;_caller_arn&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;aws_caller_identity&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;current&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;arn&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;_is_sso&lt;/span&gt;     &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;startswith&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;split&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;/&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;local&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;_caller_arn&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)[&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;AWSReservedSSO_&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

  &lt;span class=&quot;nx&quot;&gt;caller_role_arn&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;local&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;_is_sso&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;format&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:iam::%s:role/aws-reserved/sso.amazonaws.com/%s&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;aws_caller_identity&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;current&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;account_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;split&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;/&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;local&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;_caller_arn&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)[&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;local&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;_caller_arn&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Con el Admin policy correcto y los trust policies apuntando al rol SSO permanente, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create_registry&lt;/code&gt; ahora termina en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;READY&lt;/code&gt; en menos de un minuto:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/01-registry-ready.png&quot; alt=&quot;Registry Aurora Capital creado con status Ready&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Status &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Ready&lt;/code&gt;, auth type &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AWS_IAM&lt;/code&gt;, ARN visible. Ahora podemos publicar records.&lt;/p&gt;

&lt;h2 id=&quot;cuatro-descriptors-cuatro-formas-y-solo-una-está-bien-documentada&quot;&gt;Cuatro descriptors, cuatro formas (y solo una está bien documentada)&lt;/h2&gt;

&lt;p&gt;Llegamos al hallazgo más rico del laboratorio: ningún descriptor del Registry tiene la forma “obvia”. MCP es el único confirmado contra documentación oficial y funciona al primer intento. Los otros tres — A2A, Skill, Custom — tienen formas que solo descubres cuando tu primer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create_registry_record&lt;/code&gt; falla. Tres iteraciones de error después, llegas a la forma correcta.&lt;/p&gt;

&lt;p&gt;Acá van los cuatro, con la forma que funciona en producción y el error que ibas a comer si llegabas con la inferencia natural.&lt;/p&gt;

&lt;h3 id=&quot;mcp--el-único-bien-documentado&quot;&gt;MCP — el único bien documentado&lt;/h3&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;control&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_registry_record&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;registryId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;registry_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;stripe-payments-mcp&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;descriptorType&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;MCP&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;descriptors&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;mcp&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;server&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inlineContent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;auroracapital/stripe-payments-mcp&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Operaciones de pagos contra Stripe&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;version&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;2.1.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;})},&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inlineContent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;create_payment_intent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inputSchema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{...}},&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;issue_refund&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inputSchema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{...}},&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;})}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;recordVersion&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;2.1&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;server&lt;/code&gt; es obligatorio, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tools&lt;/code&gt; es opcional. Ambos van con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;inlineContent&lt;/code&gt; que es un string JSON serializado. Confirmado contra docs oficiales — no tuve sorpresas con MCP.&lt;/p&gt;

&lt;h3 id=&quot;a2a--falta-el-protocolversion&quot;&gt;A2A — falta el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;protocolVersion&lt;/code&gt;&lt;/h3&gt;

&lt;p&gt;Mi inferencia inicial del A2A AgentCard no incluía un campo que el Registry exige. El error real:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: a2a.agentCard inlineContent does not match any supported version
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El mensaje no menciona qué campo falta, solo dice “does not match any supported version”. El campo es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;protocolVersion&lt;/code&gt;, va al inicio del AgentCard, y es obligatorio:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;agent_card&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;protocolVersion&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;0.3.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;# ← obligatorio, fácil de olvidar
&lt;/span&gt;    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;auroracapital/customer-onboarding-agent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Onboarding end-to-end de nuevos clientes retail&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;version&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;1.2.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;url&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;https://agents.aurora-capital.internal/onboarding&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;capabilities&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;streaming&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;pushNotifications&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;defaultInputModes&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;image&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;skills&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[...],&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;descriptors&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;a2a&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;agentCard&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inlineContent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;agent_card&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)}}}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El Registry sigue la &lt;a href=&quot;https://a2aproject.github.io/A2A/&quot; target=&quot;_blank&quot;&gt;especificación abierta de A2A&lt;/a&gt;, donde &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;protocolVersion&lt;/code&gt; es obligatorio. Si construyes el AgentCard a mano (en lugar de generarlo desde un SDK A2A oficial), es fácil saltarlo.&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;⏳ &lt;strong&gt;Detalle de versión que vale la pena conocer&lt;/strong&gt;: la spec A2A upstream ya liberó &lt;strong&gt;v1.0.0&lt;/strong&gt; y movió &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;protocolVersion&lt;/code&gt; del top level del AgentCard a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;supportedInterfaces[].protocolVersion&lt;/code&gt;. El Registry hoy valida contra el shape anterior (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;protocolVersion&lt;/code&gt; en el top level con valores tipo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.3.0&lt;/code&gt;), así que si copias un AgentCard generado con un SDK A2A v1.0 vas a comer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ValidationException&lt;/code&gt;. Hasta que AWS actualice el schema soportado, el camino que funciona es el de este post: top level + &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;0.3.0&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;skill--cuatro-sorpresas-en-un-solo-descriptor&quot;&gt;Skill — cuatro sorpresas en un solo descriptor&lt;/h3&gt;

&lt;p&gt;Este es el campeón de los errores secuenciales. Mi inferencia inicial chocó cuatro veces antes de llegar a la forma correcta.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sorpresa 1&lt;/strong&gt;: la key NO se llama &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skill&lt;/code&gt;. Botocore te corta antes de llamar a la API:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ParamValidationError: Unknown parameter in descriptors: &quot;skill&quot;,
must be one of: mcp, a2a, custom, agentSkills
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;La key correcta es &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentSkills&lt;/code&gt;&lt;/strong&gt; en plural. Bien.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sorpresa 2&lt;/strong&gt;: adentro no va &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;inlineContent&lt;/code&gt; directo. Hay sub-keys específicas:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ParamValidationError: Unknown parameter in descriptors.agentSkills: &quot;inlineContent&quot;,
must be one of: skillMd, skillDefinition
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Las sub-keys válidas son &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skillDefinition&lt;/code&gt;&lt;/strong&gt; (JSON estructurado con metadata y package info) y &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skillMd&lt;/code&gt;&lt;/strong&gt; (markdown con la documentación). Y el descriptor acepta las dos a la vez — de hecho, lo recomendado es mandar ambas porque el search indexa los dos lados.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sorpresa 3&lt;/strong&gt;: el enum del &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;descriptorType&lt;/code&gt; en la API también es distinto. Probé con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;descriptorType=&quot;SKILL&quot;&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: Value at &apos;descriptorType&apos; failed to satisfy constraint:
Member must satisfy enum value set: [A2A, CUSTOM, MCP, AGENT_SKILLS]
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El enum es &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AGENT_SKILLS&lt;/code&gt;&lt;/strong&gt; (plural, con guion bajo), no &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SKILL&lt;/code&gt;. La inconsistencia entre la sub-key (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agentSkills&lt;/code&gt;, camelCase) y el enum del descriptorType (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AGENT_SKILLS&lt;/code&gt;, mayúsculas con guion bajo) es desafortunada pero hay que conocerla.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Sorpresa 4&lt;/strong&gt;: el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;skillMd&lt;/code&gt; requiere YAML frontmatter al inicio. Mandé markdown plano:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: agentSkills.skillMd inlineContent must start with frontmatter
delimited by &apos;---&apos;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Tu skillMd tiene que empezar con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;---\n&amp;lt;YAML&amp;gt;\n---\n&lt;/code&gt; antes del cuerpo markdown. Si vienes del mundo de Jekyll, te suena familiar — es exactamente el patrón.&lt;/p&gt;

&lt;p&gt;La forma final que funciona, después de las cuatro iteraciones:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;control&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_registry_record&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;registryId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;registry_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;pii-redaction-skill&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;descriptorType&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;AGENT_SKILLS&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;        &lt;span class=&quot;c1&quot;&gt;# ← plural y mayúsculas
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;descriptors&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;agentSkills&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;                  &lt;span class=&quot;c1&quot;&gt;# ← plural y camelCase
&lt;/span&gt;            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;skillDefinition&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inlineContent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;pii-redaction&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;title&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;PII Redaction Skill&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;version&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;1.0.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;owner&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;compliance@aurora-capital.internal&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;tags&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;compliance&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;privacy&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;pii&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;redaction&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;latam&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;package&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;python&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;aurora-pii-redaction&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;registry&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;https://artifactory.aurora-capital.internal/pypi/&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;version&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;1.0.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;skillMd&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inlineContent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;---&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name: pii-redaction&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;version: 1.0.0&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;---&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;# PII Redaction Skill&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Librería que aplica reglas regex + ML...&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;recordVersion&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;1.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔧 &lt;strong&gt;ProTip #4&lt;/strong&gt;: De los cuatro descriptors del Registry, solo MCP funciona al primer intento. A2A te pide &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;protocolVersion&lt;/code&gt; con un error críptico, AGENT_SKILLS te tira cuatro errores secuenciales (key plural, sub-keys específicas, enum distinto, frontmatter YAML), y Custom es el más limpio pero rompe el patrón de los otros tres. Si vas a publicar muchos records, escribe una capa que normalice cada tipo — ahorra horas.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;custom--sin-sub-key-el-más-simple&quot;&gt;Custom — sin sub-key, el más simple&lt;/h3&gt;

&lt;p&gt;El último descriptor cierra el patrón rompiéndolo. Mi inferencia natural fue &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;{&quot;custom&quot;: {&quot;schema&quot;: {&quot;inlineContent&quot;: ...}}}&lt;/code&gt; siguiendo la lógica de MCP y AGENT_SKILLS. Error:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ParamValidationError: Unknown parameter in descriptors.custom: &quot;schema&quot;,
must be one of: inlineContent
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Custom es plano. Sin sub-key intermedia:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;descriptors&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;custom&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inlineContent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Después de pelearte con AGENT_SKILLS, esta forma se siente como un alivio. Pero el costo es la inconsistencia: tres patrones distintos para cuatro tipos de record. Si AWS estabiliza esto antes de GA, espero que homologuen — pero mientras tanto, asume que ninguna forma es trivial.&lt;/p&gt;

&lt;p&gt;Con las cuatro formas resueltas, los 8 records de Aurora Capital se publican sin más drama. Pasan de DRAFT a PENDING_APPROVAL cuando los enviamos para aprobación, y EventBridge dispara la notificación al Curator.&lt;/p&gt;

&lt;h2 id=&quot;el-flujo-de-aprobación-real-con-statusreason-obligatorio&quot;&gt;El flujo de aprobación real (con statusReason obligatorio)&lt;/h2&gt;

&lt;p&gt;El Curator recibe el correo vía SNS y ejecuta:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;control&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore-control&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# firmado como Curator
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;control&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;update_registry_record_status&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;registryId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;registry_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;recordId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;record_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;status&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;APPROVED&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;statusReason&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Cumple estándares de seguridad y naming. Documentación clara.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Mi inferencia inicial usaba &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;newStatus&lt;/code&gt;. La API es estricta y te lo dice:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ParamValidationError:
Missing required parameter in input: &quot;status&quot;
Missing required parameter in input: &quot;statusReason&quot;
Unknown parameter in input: &quot;newStatus&quot;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Dos hallazgos en uno: el parámetro es &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;status&lt;/code&gt;&lt;/strong&gt; (no &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;newStatus&lt;/code&gt;), y &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;statusReason&lt;/code&gt; es obligatorio en cualquier transición&lt;/strong&gt;, incluyendo APPROVED. No puedes aprobar sin razón. La documentación del SDK no lo aclara como required, pero la API sí lo aplica.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #5&lt;/strong&gt;: El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;statusReason&lt;/code&gt; obligatorio en cualquier transición — incluso APPROVED — es una política de gobernanza aplicada por la API. Es brillante: cada decisión de aprobación deja un rastro de auditoría estructurado. La razón “ok” parece tentadora cuando estás aprobando 50 records seguidos, pero es exactamente la actitud que el Registry está desarmando. Trata la razón como contrato con tu yo del futuro: en seis meses, cuando alguien pregunte “¿por qué se aprobó esto?”, la respuesta está ahí.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Para el demo, aprobé 7 de los 8 records y rechazé &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;slack-notifier-tool&lt;/code&gt; con razón:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;control&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;update_registry_record_status&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;registryId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;registry_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;recordId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;slack_record_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;status&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;REJECTED&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;statusReason&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;El endpoint mTLS no está en el catálogo de tools internos. &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Documentar en confluence/internal-tools antes de re-submitir.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Resultado en consola:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/02-records-status.png&quot; alt=&quot;Registry records: 7 approved, 1 rejected&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Los contadores de la consola — Total submitted 8, Approved 7, Rejected 1 — confirman el flujo. Y el slack-notifier-tool aparece como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Rejected&lt;/code&gt; en la tabla con razón visible al hacer clic.&lt;/p&gt;

&lt;p&gt;Acá vale destacar lo que pasa en negativo: el rol Publisher no puede ejecutar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update_registry_record_status&lt;/code&gt;. El demo lo prueba explícitamente — intenté aprobar como Publisher y recibí &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AccessDeniedException&lt;/code&gt;. Cuando rompes la línea de las personas, el Registry te corta. Es exactamente el modelo que quieres en producción.&lt;/p&gt;

&lt;h2 id=&quot;búsqueda-híbrida-la-realidad-detrás-de-la-promesa-semántica&quot;&gt;Búsqueda híbrida: la realidad detrás de la promesa “semántica”&lt;/h2&gt;

&lt;p&gt;Acá entramos en la sección donde el marketing y la ejecución divergen, y donde tu lectura honesta del producto vale más que la nota del anuncio. La documentación del Registry promete &lt;strong&gt;búsqueda híbrida&lt;/strong&gt;: keyword y semántica corriendo en paralelo, con fusión de ranking, sobre los campos &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;name&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;description&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;descriptors&lt;/code&gt; (incluyendo nombres de tools, descripciones, input schemas y capabilities).&lt;/p&gt;

&lt;p&gt;Para entender qué hace la búsqueda en la práctica, probé 22 consultas distintas contra los 8 records aprobados; abajo muestro las 15 más reveladoras agrupadas por patrón. La conclusión es matizada y vale la pena documentarla.&lt;/p&gt;

&lt;h3 id=&quot;consultas-cortas-1-3-palabras--keyword-puro-de-facto&quot;&gt;Consultas cortas (1-3 palabras) → keyword puro de facto&lt;/h3&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Consulta&lt;/th&gt;
      &lt;th&gt;Coincidencias&lt;/th&gt;
      &lt;th&gt;Comentario&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe-payments-mcp&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅ keyword en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;name&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;payments&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe-payments-mcp&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅ keyword en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;description&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;payment&lt;/code&gt; (singular)&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;❌ sin stemming&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;payment intent&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;❌ el orden de palabras importa&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;payment processing&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cobrar&lt;/code&gt; (verbo)&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;❌ la descripción dice “cobro” (sustantivo), no “cobrar”&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;issue refund&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;jira-mcp-server&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;🤔 “issue” es muy fuerte en jira&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Para consultas cortas, la parte semántica aporta poco. Stemming, expansión de sinónimos, separación de CamelCase — cosas que esperas de cualquier buscador moderno — no funcionan. El Registry te trata como &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;grep&lt;/code&gt;.&lt;/p&gt;

&lt;h3 id=&quot;consultas-naturales-largas-5-palabras--ahí-sí-hay-magia&quot;&gt;Consultas naturales largas (5+ palabras) → ahí sí hay magia&lt;/h3&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Consulta&lt;/th&gt;
      &lt;th&gt;Top hit&lt;/th&gt;
      &lt;th&gt;Comentario&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;find me an agent that helps with new customer onboarding for retail clients&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;customer-onboarding-agent&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;I want to redact PII from text before sending to an LLM&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pii-redaction-skill&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool to convert from MXN to USD&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;currency-conversion-skill&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agent for production incident triage and runbook suggestion&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;incident-triage-agent&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;necesito procesar un pago en pesos mexicanos&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe-payments-mcp&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅ multilingüe&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;redactar información personal antes de pasarla a un LLM&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pii-redaction-skill&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Acá sí: consultas largas en lenguaje natural — incluyendo las que están en español contra records descriptos mayormente en inglés — ranquean al record correcto. La búsqueda semántica multilingüe funciona y es el verdadero diferenciador del producto.&lt;/p&gt;

&lt;h3 id=&quot;pero-el-ranking-se-ensucia-con-keyword-fuerte&quot;&gt;Pero el ranking se ensucia con keyword fuerte&lt;/h3&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Consulta&lt;/th&gt;
      &lt;th&gt;Top hit obtenido&lt;/th&gt;
      &lt;th&gt;Top hit esperado&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;I need to charge a customer in Mexican pesos&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;jira-mcp-server&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe-payments-mcp&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;how can I issue a refund to a customer&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;jira-mcp-server&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stripe-payments-mcp&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Jira aparece primero en consultas de pagos porque las palabras &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;issue&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;customer&lt;/code&gt; son muy frecuentes en las descripciones de sus tools, y el componente keyword del scoring las pesa demasiado. La parte semántica suma para Stripe pero no alcanza para superar el keyword en Jira.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #6&lt;/strong&gt;: La “búsqueda semántica” del Registry es real pero condicional. Se activa de verdad solo con consultas naturales largas (5+ palabras) y se ensucia cuando dos records comparten palabras genéricas (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;customer&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;issue&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agent&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool&lt;/code&gt;). Eso define cómo describís tus records: haz descripciones específicas y evita vocabulario genérico que vaya a competir contra otros records de la organización. Y para los demos públicos, elige consultas deliberadamente largas — las cortas dan resultados que te van a hacer dudar del producto.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Hay un detalle adicional sobre &lt;strong&gt;consistencia eventual&lt;/strong&gt;: durante el laboratorio vi cómo la consulta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;compliance&lt;/code&gt; pasaba de 1 a 2 coincidencias entre los primeros 3 minutos y los 15 minutos posteriores a la aprobación. El indexado de la búsqueda no es instantáneo. Si tu demo va a buscar inmediatamente después de aprobar, considera esperar un par de minutos antes de filmar.&lt;/p&gt;

&lt;p&gt;La consola tiene su propia interfaz de búsqueda y muestra los 7 records aprobados con tarjetas visuales:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/03-search-results.png&quot; alt=&quot;Resultados de búsqueda en la consola con 7 records aprobados&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Notar que el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;slack-notifier-tool&lt;/code&gt; rechazado no aparece — es invisible para la búsqueda, exactamente como el modelo de gobernanza lo promete.&lt;/p&gt;

&lt;h2 id=&quot;el-cierre-claude-code-descubre-tu-organización&quot;&gt;El cierre: Claude Code descubre tu organización&lt;/h2&gt;

&lt;p&gt;Hasta acá tenemos un catálogo construido, gobernanza aplicada por la API y búsqueda funcional. Falta la pregunta que importa: &lt;strong&gt;¿cómo lo consume un desarrollador en su día a día?&lt;/strong&gt; La respuesta es lo que hace popular al Registry: cualquier cliente MCP-compatible — incluido Claude Code — puede conectarse al Registry y descubrir agentes, tools y skills sin que el desarrollador abra la consola de AWS.&lt;/p&gt;

&lt;p&gt;Hay tres pasos: (1) construir la URL del MCP endpoint, (2) firmar las requests con SigV4 porque el Registry usa AWS_IAM, (3) configurar el cliente MCP para que sepa hablar con eso.&lt;/p&gt;

&lt;h3 id=&quot;la-url-del-endpoint-que-la-documentación-no-anuncia-de-forma-obvia&quot;&gt;La URL del endpoint, que la documentación no anuncia de forma obvia&lt;/h3&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;get_registry()&lt;/code&gt; no devuelve un campo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mcpEndpoint&lt;/code&gt;. La respuesta trae &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;name&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;status&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;registryArn&lt;/code&gt; y poco más. El path del endpoint sigue una convención basada en path:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;https://bedrock-agentcore.&amp;lt;region&amp;gt;.amazonaws.com/registry/&amp;lt;registryId&amp;gt;/mcp
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Singular &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;registry&lt;/code&gt;, no plural. Hay que construirlo a mano a partir del &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;registryId&lt;/code&gt;. Verificable desde Python con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;requests + botocore.auth.SigV4Auth&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;botocore.auth&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;SigV4Auth&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;botocore.awsrequest&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;AWSRequest&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;requests&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;creds&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nc&quot;&gt;Session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;().&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get_credentials&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;().&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get_frozen_credentials&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;endpoint&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;https://bedrock-agentcore.us-east-1.amazonaws.com/registry/&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;registry_id&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;/mcp&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;jsonrpc&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;2.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;method&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;tools/list&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;params&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{}}&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;req&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;AWSRequest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;method&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;POST&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;url&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;endpoint&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                 &lt;span class=&quot;n&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                 &lt;span class=&quot;n&quot;&gt;headers&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Content-Type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;application/json&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;span class=&quot;nc&quot;&gt;SigV4Auth&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;creds&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us-east-1&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;add_auth&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;resp&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;requests&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;post&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;endpoint&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;body&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;headers&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;req&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;headers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Esto funciona desde Python. Pero Claude Code no soporta SigV4 nativo en transporte HTTP — espera &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stdio&lt;/code&gt; o HTTP simple sin firma AWS. Hay que poner un proxy en el medio.&lt;/p&gt;

&lt;h3 id=&quot;el-puente-que-faltaba-mcp-proxy-for-aws&quot;&gt;El puente que faltaba: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mcp-proxy-for-aws&lt;/code&gt;&lt;/h3&gt;

&lt;p&gt;AWS publicó un proxy oficial para este caso exacto: &lt;a href=&quot;https://github.com/aws/mcp-proxy-for-aws&quot; target=&quot;_blank&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mcp-proxy-for-aws&lt;/code&gt;&lt;/a&gt;. Se ejecuta vía &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;uvx&lt;/code&gt;, levanta un MCP server local en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stdio&lt;/code&gt; y firma con SigV4 cada request al endpoint AWS. Eso lo vuelve invisible para el cliente MCP — Claude Code se conecta como si fuera cualquier MCP server stdio.&lt;/p&gt;

&lt;p&gt;La configuración va en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.mcp.json&lt;/code&gt; en la raíz del proyecto (alcance del proyecto):&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;mcpServers&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;aurora-capital-registry&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;type&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;stdio&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;command&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;uvx&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;args&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;mcp-proxy-for-aws@latest&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;https://bedrock-agentcore.us-east-1.amazonaws.com/registry/&amp;lt;registryId&amp;gt;/mcp&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;--service&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;bedrock-agentcore&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;--region&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;  &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;us-east-1&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Las credenciales las toma del entorno AWS estándar — un perfil que asume el rol Consumer del laboratorio. Si quieres blindar al cliente contra cualquier write accidental, agrégale &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--read-only&lt;/code&gt; a los args del proxy: deshabilita los tools que requieren permisos de escritura, lo cual encaja perfecto con la persona Consumer (descubre, consume, no muta). Reinicias Claude Code y el MCP server &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aurora-capital-registry&lt;/code&gt; aparece disponible con una única herramienta: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;search_registry_records&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚀 &lt;strong&gt;ProTip #7&lt;/strong&gt;: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mcp-proxy-for-aws&lt;/code&gt; es la pieza que cierra el círculo entre AgentCore y los IDEs y agentes que hablan MCP. Sin él, conectar Claude Code a cualquier endpoint AgentCore que use AWS_IAM es manual y frágil. Con él, cualquier cliente MCP estándar se puede conectar de forma transparente. Vale la pena conocerlo aunque hoy no lo uses — es probable que cualquier integración futura entre AgentCore y herramientas externas pase por este proxy.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;el-momento-que-vale-el-viaje&quot;&gt;El momento que vale el viaje&lt;/h3&gt;

&lt;p&gt;Con la conexión activa, le tiré a Claude Code en el IDE:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;em&gt;“Find me an agent that helps with new customer onboarding for retail clients.”&lt;/em&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Sin nombrar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;customer-onboarding-agent&lt;/code&gt;, sin saber qué Squad lo construyó, sin abrir Confluence. Claude consultó el Registry vía MCP y respondió:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;Encontré exactamente lo que necesitas. &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;customer-onboarding-agent&lt;/code&gt;&lt;/strong&gt; v1.2.0 (Aurora Capital, Squad Customer Lifecycle).&lt;/p&gt;

  &lt;ul&gt;
    &lt;li&gt;&lt;strong&gt;Endpoint&lt;/strong&gt;: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;https://agents.aurora-capital.internal/onboarding&lt;/code&gt;&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Capabilities&lt;/strong&gt;: streaming + push notifications, input modes text + image (acepta foto del documento)&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Soporta&lt;/strong&gt;: MX, CO, AR, BR, CL, PE&lt;/li&gt;
  &lt;/ul&gt;

  &lt;p&gt;Tres skills disponibles:&lt;/p&gt;
  &lt;ul&gt;
    &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kyc_document_validation&lt;/code&gt; — Valida cédula/INE/DNI según país, detecta forgery con OCR&lt;/li&gt;
    &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sanctions_screening&lt;/code&gt; — Cruza nombre + fecha de nacimiento contra OFAC, ONU, listas locales&lt;/li&gt;
    &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;account_provisioning&lt;/code&gt; — Crea la cuenta en core banking, asigna producto inicial&lt;/li&gt;
  &lt;/ul&gt;

  &lt;p&gt;Es exactamente el flujo retail que pediste. Si quieres probarlo, manda un POST al endpoint A2A con un payload que invoque &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kyc_document_validation&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Una sola pasada. El desarrollador recibió: el endpoint, las capacidades, los modos de entrada, las skills disponibles y una recomendación de cómo empezar. &lt;strong&gt;El Registry le devolvió el descriptor A2A completo embebido&lt;/strong&gt; con todo el AgentCard, y Claude lo tradujo a una respuesta accionable.&lt;/p&gt;

&lt;p&gt;Eso es lo que estoy llamando el “último kilómetro” del Registry: no es solo que el catálogo existe — es que el catálogo es consultable en el contexto donde el desarrollador ya está trabajando, en lenguaje natural, sin sobrecarga.&lt;/p&gt;

&lt;p&gt;Esto es la imagen que te llevas del producto cuando funciona bien:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/aws-agent-registry/04-record-detail.png&quot; alt=&quot;Detalle del athena-query-tool con detalles del record y configuración del protocolo completa&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Cada record viene con todo lo que un consumer necesita — no solo nombre y descripción, sino el descriptor completo con schemas, endpoints e información del paquete. Una sola ida y vuelta, todo el contrato del recurso.&lt;/p&gt;

&lt;h2 id=&quot;lecciones-aprendidas&quot;&gt;Lecciones aprendidas&lt;/h2&gt;

&lt;p&gt;Después de la semana del laboratorio, lo que me llevo en limpio sobre el producto y sobre cómo recomendarlo a clientes:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El modelo de las 4 personas es la decisión arquitectónica más fuerte del servicio.&lt;/strong&gt; No es marketing — la separación se sostiene en IAM, los AccessDenied del demo son reales, y la disciplina que impone (Publisher no aprueba lo suyo, Curator no escribe contenido) mapea exactamente lo que quieres en gobernanza corporativa. Si tu organización ya tiene roles equivalentes para otros recursos AWS, mapearlos al Registry es directo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Los descriptors no estaban listos para producción en preview.&lt;/strong&gt; Tres de cuatro tipos requieren iteración a mano para descubrir la forma correcta. Vale la pena escribir una capa de envoltorio que normalice — vas a publicar los mismos tipos muchas veces y no quieres mantener cuatro patrones distintos en tu código base. El &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/08/aws-agent-registry-generally-available/&quot; target=&quot;_blank&quot;&gt;anuncio de GA&lt;/a&gt; no menciona cambios en la forma de los descriptors, pero no lo tomes como confirmación — valida contra la &lt;a href=&quot;https://docs.aws.amazon.com/agent-registry/&quot; target=&quot;_blank&quot;&gt;referencia de API vigente&lt;/a&gt; antes de asumir que las cuatro formas de abajo siguen intactas.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La búsqueda semántica tiene un punto óptimo estrecho.&lt;/strong&gt; Funciona perfecto cuando el consumer hace consultas naturales largas (lo cual encaja bien con agentes conversacionales) y se rompe cuando le tiras palabras clave sueltas (lo cual descalifica buena parte del uso humano directo). Esa restricción está bien si el caso de uso primario es Claude Code, Kiro u otros agentes consultando el Registry. Es problemática si piensas en desarrolladores tirando &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;grep&lt;/code&gt; desde la consola.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La brecha entre la API y la realidad de producción estaba en EventBridge y el SDK.&lt;/strong&gt; EventBridge tiene el evento (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Registry Record State Change&lt;/code&gt;) y la integración funciona, pero la documentación de la forma exacta del payload estaba rezagada respecto a la implementación. El SDK boto3 tenía los métodos pero la AWS CLI todavía estaba alcanzando el ritmo. El Terraform Provider no tenía los recursos. Estas tres brechas eran típicas de un servicio en preview.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: La brecha de IaC se cerró con GA — CloudFormation, Terraform y CDK ya tienen soporte oficial. No verifiqué si la documentación del payload de EventBridge o el ritmo boto3/CLI siguen rezagados; si dependes de eso, valida contra la documentación vigente antes de asumir que se resolvió igual de limpio.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Costo cero durante el preview fue el punto óptimo para adoptarlo temprano.&lt;/strong&gt; Con GA (31 de agosto de 2026) ya hay precio real por Net Records + API calls, con Free Tier mensual (ver la sección de costo más arriba). Si todavía no migraste tu inventario, vale la pena revisar cuánto de tu volumen actual cae dentro del Free Tier antes de que el gasto se vuelva una línea que alguien tenga que justificar.&lt;/p&gt;

&lt;h2 id=&quot;lo-que-todavía-no-está&quot;&gt;Lo que todavía no está&lt;/h2&gt;

&lt;p&gt;Para que tu mapa mental sea completo, esto &lt;strong&gt;no&lt;/strong&gt; existía en el preview (abril 2026) y vale la pena saber qué esperar — marco con 🔄 lo que GA ya resolvió:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;Auto-indexado de runtimes desplegados&lt;/strong&gt;. Si tenías un agente en AgentCore Runtime, no se autopublicaba al Registry. Lo registrabas manualmente.&lt;/p&gt;

    &lt;blockquote class=&quot;q-left&quot;&gt;
      &lt;p&gt;🔄 &lt;strong&gt;Resuelto en GA (agosto 2026)&lt;/strong&gt;: el Registry ahora puede &lt;strong&gt;auto-detectar agentes en AgentCore Runtime y AgentCore Gateway en toda la organización&lt;/strong&gt; y traerlos a un registry central, sin autoría manual. Ver el &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/08/aws-agent-registry-generally-available/&quot; target=&quot;_blank&quot;&gt;anuncio de GA&lt;/a&gt;.&lt;/p&gt;
    &lt;/blockquote&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;Federación entre registries&lt;/strong&gt;. Cada cuenta tenía sus propios registries; no había forma nativa de exponer un registry de la cuenta de Platform a las cuentas de los squads.&lt;/p&gt;

    &lt;blockquote class=&quot;q-left&quot;&gt;
      &lt;p&gt;🔄 &lt;strong&gt;Resuelto en GA (agosto 2026)&lt;/strong&gt;: con &lt;strong&gt;AWS Resource Access Manager (RAM)&lt;/strong&gt; ya puedes compartir registries entre cuentas y crear registries a nivel organización. No es federación completa (sigue siendo “un registry compartido”, no “múltiples registries unificados”), pero cierra el caso de uso de Aurora Capital: la cuenta de Platform puede compartir su registry con las cuentas de cada squad.&lt;/p&gt;
    &lt;/blockquote&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Versionamiento avanzado&lt;/strong&gt;. El Registry soporta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;recordVersion&lt;/code&gt; pero no implementa diffing consciente de SemVer entre versiones. Tú marcas 1.0, 1.1, 2.0 — el Registry no te avisa si rompes compatibilidad. &lt;em&gt;(Sin cambios confirmados en GA — no encontré mención de esto en el anuncio ni en la documentación; sigue como estaba en preview, verifica antes de asumir.)&lt;/em&gt;&lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;Soporte completo en IaC&lt;/strong&gt;. Ni Terraform, ni CDK, ni la AWS CLI tenían los recursos completos.&lt;/p&gt;

    &lt;blockquote class=&quot;q-left&quot;&gt;
      &lt;p&gt;🔄 &lt;strong&gt;Resuelto en GA (agosto 2026)&lt;/strong&gt;: soporte oficial para &lt;strong&gt;AWS CloudFormation, Terraform y AWS CDK&lt;/strong&gt; para provisionar y gestionar registries como código, más tagging para organización, cost allocation y control de acceso.&lt;/p&gt;
    &lt;/blockquote&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Métricas y tableros listos&lt;/strong&gt;. CloudWatch tiene los logs pero no había un tablero nativo del tipo “qué records son los más buscados, cuáles tienen más rechazos, etc.” &lt;em&gt;(Sin cambios confirmados en GA — el anuncio no menciona dashboards nuevos; si esto es un bloqueante para tu adopción, verifica el estado actual antes de planificar.)&lt;/em&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;GA (31 de agosto de 2026) cerró tres de las cinco brechas de arriba: auto-indexado, sharing cross-account e IaC. Versionamiento SemVer-aware y dashboards nativos no aparecen mencionados en el anuncio de GA — si tu adopción depende de alguno de los dos, no asumas que se resolvieron y verifica contra la &lt;a href=&quot;https://docs.aws.amazon.com/agent-registry/&quot; target=&quot;_blank&quot;&gt;documentación vigente&lt;/a&gt;.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;Si tienes más de tres equipos construyendo agentes en paralelo en tu organización, el momento para adoptar Agent Registry sigue siendo ahora — el servicio pasó a GA el 31 de agosto de 2026, con Free Tier generoso (5,000 Net Records/mes) y soporte IaC nuevo, así que la barrera de entrada bajó en vez de subir. Cualquiera que llegue al Registry con 50 agentes va a tener que escribir un programa de migración antes de extraer valor; cualquiera que llegue con 8 lo va a integrar en un sprint.&lt;/p&gt;

&lt;p&gt;El producto tiene aristas, sí. Cuatro descriptors con formas inconsistentes y una búsqueda semántica con punto óptimo estrecho — eso GA no lo cambió. Pero el Provider de Terraform ya llegó y el SDK ya no va tan por delante de la CLI. El modelo conceptual — las 4 personas, el flujo de aprobación aplicado por la API, el MCP endpoint consumible desde cualquier cliente — es sólido y se siente como un servicio de plataforma, no como un experimento.&lt;/p&gt;

&lt;p&gt;Y el cierre con Claude Code es el momento donde el retorno se vuelve obvio. Cuando un desarrollador puede preguntar en lenguaje natural “¿hay algún agente que haga X?” y recibir el contrato completo del recurso en una sola pasada, sin abrir Confluence ni preguntar en Slack, ahí es donde la inversión de gobernanza se paga sola.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #8&lt;/strong&gt;: El catálogo previene la duplicación, pero solo si los Publishers son disciplinados al describir sus recursos. Haz descripciones específicas, usa vocabulario que tu Consumer ideal escribiría como consulta, evita palabras genéricas (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;tool&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;agent&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;service&lt;/code&gt;) sin contexto. La búsqueda del Registry es tan buena como el peor descriptor que tengas indexado. Esa disciplina la imponen los Curators en la aprobación — usa el rechazo con razón concreta para enseñar a tus Publishers a escribir buenas descripciones.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;El repositorio completo del laboratorio está en &lt;a href=&quot;https://github.com/codecr/bedrock-agent-registry&quot; target=&quot;_blank&quot;&gt;github.com/codecr/bedrock-agent-registry&lt;/a&gt; — Terraform para los 4 roles IAM y EventBridge, Python para registry y records, los 8 records de Aurora Capital con las formas corregidas, y la &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;.mcp.json&lt;/code&gt; de Claude Code lista para usar. Si quieres reproducir el laboratorio en tu cuenta, necesitas boto3 ≥ 1.42.87 y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;BedrockAgentCoreFullAccess&lt;/code&gt; en el rol que ejecuta el primer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create_registry&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Si te quedaste con ganas de algo más sobre la pila Bedrock + GenAI, te dejo mi post anterior — el &lt;a href=&quot;/chunking-benchmark.html&quot; target=&quot;_blank&quot;&gt;benchmark real de las 5 estrategias de chunking en Bedrock Knowledge Bases&lt;/a&gt; — donde aplico el mismo patrón de “manos a la obra con todas las sutilezas honestas” pero del lado de RAG.&lt;/p&gt;

&lt;p&gt;Y si estás del lado donde esto resuena — donde tienes varios equipos construyendo agentes en paralelo y no quieres esperar a tener 50 para empezar a poner orden — me encantaría escuchar tu caso. ¿Cómo se ve tu inventario de agentes hoy? ¿Quién tomaría el rol de Curator en tu organización? ¿Hay algún squad que ya esté duplicando capacidades sin darse cuenta?&lt;/p&gt;

&lt;p&gt;Comenta abajo o escríbeme por LinkedIn.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! 🚀&lt;/p&gt;
</description>
                <pubDate>Wed, 29 Apr 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/aws-agent-registry.html</link>
                <guid isPermaLink="true">https://gerardo.dev/aws-agent-registry.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>AgentCore</category>
                
                <category>Registry</category>
                
                <category>GenAI</category>
                
                <category>MCP</category>
                
                <category>A2A</category>
                
                <category>Governance</category>
                
                
            </item>
        
            <item>
                <title>Benchmark Real: 5 Estrategias de Chunking en Amazon Bedrock Knowledge Bases</title>
                <description>&lt;p&gt;Hace algunas semanas me encontré con una pregunta que escucho cada vez más seguido en las conversaciones con arquitectos y equipos de desarrollo:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;“Voy a implementar un RAG con Bedrock Knowledge Bases, ¿qué estrategia de chunking uso? Veo que hay cinco y todas suenan razonables.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Es una pregunta sensata y honestamente no tenía una respuesta que me dejara tranquilo. La documentación de AWS explica cada estrategia con claridad. Los blogs técnicos hablan de ellas en términos conceptuales. Las comparativas que había visto solían quedarse en el “cada una tiene su caso de uso”. Pero pocos datos concretos sobre cómo se comportan con corpus real.&lt;/p&gt;

&lt;p&gt;Así que decidí hacer el benchmark yo mismo. Con una metodología reproducible, datos reales, y métricas objetivas. Lo que encontré me sorprendió lo suficiente como para que valga la pena este artículo, porque &lt;strong&gt;la realidad es bastante distinta de lo que sugiere la documentación&lt;/strong&gt;.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;Spoiler&lt;/strong&gt;: De las 5 estrategias, solo 3 pudieron procesar un corpus de documentación técnica real. Las otras 2 fallaron en la etapa de ingesta, no por mala calidad de chunking, sino por &lt;strong&gt;límites duros del servicio que no se mencionan al momento de elegir la estrategia&lt;/strong&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;En este artículo comparto la metodología completa, los resultados cuantitativos (25 preguntas evaluadas con LLM-as-a-judge), y algo que me parece aún más valioso: los 7 problemas de infraestructura que tuve que resolver para que todo funcionara con Terraform. Porque el código de ejemplo “oficial” asume cosas que no siempre son ciertas.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;&lt;strong&gt;📌 TL;DR — Datos clave antes de seguir leyendo&lt;/strong&gt;&lt;/p&gt;

  &lt;ul&gt;
    &lt;li&gt;&lt;strong&gt;Titan V2 embeddings&lt;/strong&gt;: límite de 50,000 caracteres / 8,192 tokens por request → hace inviable &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; para corpus normal.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;SEMANTIC chunking&lt;/strong&gt;: límite empírico de 1 MB por archivo → falla con la mayoría de documentación técnica.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;S3 Vectors&lt;/strong&gt;: límite de 2,048 bytes de filterable metadata → resolver declarando &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;nonFilterableMetadataKeys&lt;/code&gt; al crear el índice.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Sonnet 4.6 no estaba en la allowlist de jueces&lt;/strong&gt; de Bedrock Evaluations cuando corrí esto (4.5 y Opus 4.5 sí, desde mediados de 2026; Sonnet 4.6 se habilitó para RAG/KB en septiembre de 2026) → usar Nova Pro como juez cross-family sigue siendo la recomendación.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Ganadores del benchmark con corpus real&lt;/strong&gt;: Custom (0.94), Hierarchical (0.92), Fixed (0.88) en Correctness. NONE y SEMANTIC fallaron en ingesta antes de poder evaluarse justamente.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Recomendación para producción&lt;/strong&gt;: arranca con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt; (max_tokens=512, overlap=20%) + S3 Vectors + evaluación periódica. Cambia solo si los datos justifican la complejidad.&lt;/li&gt;
  &lt;/ul&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;el-contexto-por-qué-esto-me-importa&quot;&gt;El Contexto: Por Qué Esto Me Importa&lt;/h2&gt;

&lt;p&gt;Llevo varios proyectos construyendo RAGs sobre Bedrock Knowledge Bases, y cada vez que llega el momento de configurar el chunking aparece la misma conversación. Alguien del equipo pregunta “¿hierarchical o semantic?”, otro dice “probemos fixed, suena lo más seguro”, y al final &lt;strong&gt;la decisión se toma por intuición&lt;/strong&gt;, no por evidencia.&lt;/p&gt;

&lt;p&gt;El problema con ese enfoque es que cuando el RAG no funciona bien en producción, no sabemos si fue el chunking, el embedding, el retrieval, o el generator. Estamos debuggeando a ciegas.&lt;/p&gt;

&lt;p&gt;Mi objetivo con este benchmark era doble:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Producir datos reproducibles&lt;/strong&gt; que cualquier equipo pueda usar para justificar una decisión de arquitectura.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Aislar el chunking como variable única&lt;/strong&gt; para que los resultados sean honestos.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Spoiler adicional: lograr esa segunda parte fue más difícil de lo que esperaba.&lt;/p&gt;

&lt;h2 id=&quot;las-5-estrategias-de-chunking-y-una-aclaración-importante&quot;&gt;Las 5 Estrategias de Chunking (Y una aclaración importante)&lt;/h2&gt;

&lt;p&gt;Antes de entrar a los resultados, vamos a alinearnos sobre qué son estas 5 estrategias. Según la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-chunking.html&quot; target=&quot;_blank&quot;&gt;documentación oficial de Amazon Bedrock&lt;/a&gt;, las opciones disponibles en el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ChunkingConfiguration&lt;/code&gt; son:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Estrategia&lt;/th&gt;
      &lt;th&gt;Qué hace&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;No chunkea. Cada archivo se trata como un único chunk.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Divide el texto en chunks de un tamaño aproximado configurable (tokens), con overlap.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HIERARCHICAL&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Divide el documento en dos capas: chunks “padre” grandes y chunks “hijo” más pequeños derivados de ellos.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;Divide basándose en similitud semántica entre oraciones usando un embedding model.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt; (Lambda)&lt;/td&gt;
      &lt;td&gt;Tu propia lógica de chunking ejecutada como transformación Lambda.&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #1&lt;/strong&gt;: En muchos lugares verás mencionado “multimodal chunking” como una sexta estrategia. No lo es. El chunking multimodal (audio, video, imágenes) ocurre &lt;strong&gt;a nivel del embedding model&lt;/strong&gt; (por ejemplo, Nova multimodal embeddings) y su configuración es independiente de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ChunkingConfiguration&lt;/code&gt;. Las 5 estrategias de arriba aplican &lt;strong&gt;solo a documentos de texto&lt;/strong&gt;, aunque tengas contenido multimodal en tu data source. Esta confusión se la veo a muchos arquitectos.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;el-setup-aislar-el-chunking-como-única-variable&quot;&gt;El Setup: Aislar el Chunking Como Única Variable&lt;/h2&gt;

&lt;p&gt;La tesis del benchmark es simple: si vas a comparar estrategias de chunking, &lt;strong&gt;todo lo demás debe ser idéntico entre las KBs&lt;/strong&gt;. Cualquier otra variable contamina los resultados.&lt;/p&gt;

&lt;p&gt;Por eso, las 5 Knowledge Bases comparten:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;El mismo corpus en S3 (3 archivos)&lt;/li&gt;
  &lt;li&gt;El mismo embedding model: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;amazon.titan-embed-text-v2:0&lt;/code&gt;, 1024 dimensiones&lt;/li&gt;
  &lt;li&gt;El mismo vector store: &lt;strong&gt;Amazon S3 Vectors&lt;/strong&gt; (más sobre esto más adelante)&lt;/li&gt;
  &lt;li&gt;El mismo modelo generador: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;us.anthropic.claude-sonnet-4-6&lt;/code&gt; vía inference profile&lt;/li&gt;
  &lt;li&gt;El mismo modelo juez: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;amazon.nova-pro-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;El mismo conjunto de 25 preguntas con ground truth&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Lo único que cambia entre KBs: el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ChunkingConfiguration&lt;/code&gt;.&lt;/p&gt;

&lt;h3 id=&quot;por-qué-s3-vectors-como-backend&quot;&gt;¿Por qué S3 Vectors como backend?&lt;/h3&gt;

&lt;p&gt;Cuando empecé a armar esta infraestructura, originalmente apunté a OpenSearch Serverless, que es el backend por default cuando creas una KB desde la consola. Hice el cálculo de costos:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Backend&lt;/th&gt;
      &lt;th&gt;Costo base por tener la infra arriba&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;OpenSearch Serverless (vector collection)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;~$11.52 USD/día&lt;/strong&gt; (floor de 2 OCUs × $0.24/hora, mínimo obligatorio en producción para vector collections)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;S3 Vectors&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;$0 base&lt;/strong&gt; — pagas solo storage ($0.06/GB/mes), PUT ($0.20/GB) y queries ($2.5/M API calls + $/TB procesados)&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Para un benchmark que implica varias iteraciones y potencial debugging, esa diferencia es determinante. &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2025/12/amazon-s3-vectors-generally-available/&quot; target=&quot;_blank&quot;&gt;Amazon S3 Vectors alcanzó GA el 2 de diciembre de 2025&lt;/a&gt; y se integra nativamente con Bedrock Knowledge Bases. El storage cuesta $0.06/GB/mes, los PUT cuestan $0.20/GB logical subido, y las queries se cobran por API call ($2.50/M) más $/TB procesados. No hay costo base por mantener la infra arriba — a diferencia de las OCUs de OpenSearch, no hay compute corriendo cuando no estás usando el servicio.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #2&lt;/strong&gt;: S3 Vectors tiene tres trade-offs que debes conocer antes de elegirlo:&lt;/p&gt;

  &lt;ol&gt;
    &lt;li&gt;&lt;strong&gt;Latencia&lt;/strong&gt;: 100-800ms vs 10-100ms de OpenSearch.&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Solo búsqueda semántica&lt;/strong&gt;: no soporta hybrid search en Bedrock KB (confirmado en &lt;a href=&quot;https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-bedrock-kb.html&quot; target=&quot;_blank&quot;&gt;la documentación oficial&lt;/a&gt;).&lt;/li&gt;
    &lt;li&gt;&lt;strong&gt;Metadata limitado&lt;/strong&gt;: máximo 1KB de custom metadata y 35 keys por vector cuando se usa con Bedrock KB. Si usas chunking &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HIERARCHICAL&lt;/code&gt; con token counts altos, AWS advierte explícitamente que puedes exceder los límites de metadata porque las relaciones parent-child se guardan como non-filterable metadata.&lt;/li&gt;
  &lt;/ol&gt;

  &lt;p&gt;Para un benchmark offline esto no importa. Para producción con keyword matching exacto o metadata rica, probablemente quieras OpenSearch. Usa S3 Vectors cuando priorices costo sobre latencia extrema.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;el-corpus&quot;&gt;El Corpus&lt;/h3&gt;

&lt;p&gt;Elegí 3 documentos con estructuras distintas, a propósito, para estresar diferentes supuestos:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Archivo&lt;/th&gt;
      &lt;th&gt;Tamaño&lt;/th&gt;
      &lt;th&gt;Caracteres aprox.&lt;/th&gt;
      &lt;th&gt;Estructura&lt;/th&gt;
      &lt;th&gt;Hipótesis inicial&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;well-architected-framework.pdf&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;14 MB&lt;/td&gt;
      &lt;td&gt;~2,530,000&lt;/td&gt;
      &lt;td&gt;Jerárquica marcada (6 pilares → principios → prácticas)&lt;/td&gt;
      &lt;td&gt;Debería favorecer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HIERARCHICAL&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-dg.pdf&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;17 MB&lt;/td&gt;
      &lt;td&gt;~2,400,000&lt;/td&gt;
      &lt;td&gt;Prosa técnica densa con cambios sutiles de tema&lt;/td&gt;
      &lt;td&gt;Debería favorecer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;blog-rag-evaluation.html&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;1 MB&lt;/td&gt;
      &lt;td&gt;~1,080,000&lt;/td&gt;
      &lt;td&gt;Narrativa larga tipo blog&lt;/td&gt;
      &lt;td&gt;Debería exponer limitaciones de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Como voy a mostrar más adelante, &lt;strong&gt;ninguna de esas hipótesis iniciales sobrevivió al primer intento de ingestión&lt;/strong&gt;. Y ese fue precisamente el hallazgo más importante.&lt;/p&gt;

&lt;h2 id=&quot;hallazgo-1-none-no-es-tan-inocente-como-suena&quot;&gt;Hallazgo #1: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; No Es Tan Inocente Como Suena&lt;/h2&gt;

&lt;p&gt;Mi primer intento de ingestar el corpus con la estrategia &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; arrojó este error:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Malformed input request: expected maxLength: 50000, actual: 2530200,
please reformat your input and try again. 
(Service: BedrockRuntime, Status Code: 400)
Issue occurred while processing file: well-architected-framework.pdf
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Confieso que me tomó un segundo entender lo que estaba pasando.&lt;/p&gt;

&lt;p&gt;La estrategia &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; instruye a Bedrock a &lt;strong&gt;no hacer chunking&lt;/strong&gt;: el documento completo se manda al embedding model como un solo request. Y aquí está el detalle crucial: según la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html&quot; target=&quot;_blank&quot;&gt;documentación oficial de Amazon Titan Text Embeddings V2&lt;/a&gt;, el modelo acepta &lt;em&gt;“como máximo 8,192 tokens o 50,000 caracteres”&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;Mi PDF de Well-Architected tiene 2.5 millones de caracteres. Cincuenta veces el límite.&lt;/p&gt;

&lt;h3 id=&quot;qué-significa-esto-en-la-práctica&quot;&gt;¿Qué significa esto en la práctica?&lt;/h3&gt;

&lt;p&gt;La estrategia &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; es perfectamente válida, pero &lt;strong&gt;solo si tu corpus ya viene pre-chunkeado&lt;/strong&gt;. Es decir, solo si cada archivo en tu bucket S3 es una unidad lógica pequeña (una FAQ, un producto, un ticket, una definición de glosario) que cabe en esos 50,000 caracteres.&lt;/p&gt;

&lt;p&gt;La propia documentación lo reconoce, aunque de forma sutil:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;“If you choose this option [NONE], you may want to pre-process your documents by splitting them into separate files.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Pero la palabra clave aquí es “may” (podrías). En la realidad es un “must” (debes).&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #3&lt;/strong&gt;: Cuando veas la opción &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; en la consola de Bedrock, mentalmente tradúcela a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;PRE_CHUNKED&lt;/code&gt;. No es “sin chunking”: es “chunking delegado a ti, antes de subir a S3”. Si tu corpus son PDFs técnicos normales, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; va a fallar. Si es una base de datos de preguntas frecuentes con una pregunta por archivo, es perfecta.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Resultado: con mi corpus, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; indexó &lt;strong&gt;1 de 3 documentos&lt;/strong&gt; (el HTML de 1 MB también excedió el límite en muchas partes, pero procesó algo). Los dos PDFs fallaron completamente.&lt;/p&gt;

&lt;h2 id=&quot;hallazgo-2-semantic-tiene-un-límite-de-1mb-por-archivo-que-no-se-documenta-al-elegirla&quot;&gt;Hallazgo #2: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; Tiene un Límite de 1MB Por Archivo Que No Se Documenta al Elegirla&lt;/h2&gt;

&lt;p&gt;Pasé a la siguiente estrategia con cierta expectativa. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; chunking analiza el texto con un embedding model auxiliar y detecta “breakpoints” entre oraciones donde cambia el tema. Suena bien para documentación técnica densa con cambios sutiles de tema, ¿no?&lt;/p&gt;

&lt;p&gt;El log de ingesta me dijo otra cosa:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;File body text exceeds size limit of 1000000 for semantic chunking.
[Files: s3://.../bedrock-agentcore-dg.pdf, 
        s3://.../well-architected-framework.pdf]
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Mil millones, no. &lt;strong&gt;Un millón&lt;/strong&gt; de caracteres. Por archivo.&lt;/p&gt;

&lt;h3 id=&quot;por-qué-esto-es-problemático&quot;&gt;¿Por qué esto es problemático?&lt;/h3&gt;

&lt;p&gt;Revisé la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/kb-chunking.html&quot; target=&quot;_blank&quot;&gt;documentación de chunking&lt;/a&gt; cuidadosamente. Describe los parámetros de semantic chunking (max tokens, buffer size, breakpoint percentile threshold). Habla de los costos adicionales por usar un foundation model. Pero &lt;strong&gt;el límite de 1 MB por archivo no se menciona en la pantalla donde eliges la estrategia&lt;/strong&gt;. Lo descubres cuando la ingestión falla.&lt;/p&gt;

&lt;p&gt;Y es un límite práctico, no teórico: una documentación de desarrollador promedio de AWS ya excede ese tamaño. Un whitepaper normal lo excede. Prácticamente cualquier documentación técnica real de más de unas 200-300 páginas lo excede.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;ProTip #4&lt;/strong&gt;: Si tienes documentación técnica grande y quieres usar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; chunking, &lt;strong&gt;tienes que hacer pre-splitting tú mismo antes de subir a S3&lt;/strong&gt;. Lo cual tiene una ironía interesante: estás haciendo chunking manual para poder usar la estrategia de chunking “semántica”. Para la mayoría de corpus empresariales reales (manuales, políticas, whitepapers), &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; no es viable sin preprocesamiento significativo.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Resultado: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; también indexó &lt;strong&gt;1 de 3 documentos&lt;/strong&gt; (solo el HTML del blog, que estaba justo debajo del límite).&lt;/p&gt;

&lt;h2 id=&quot;el-corte-cualitativo-antes-de-medir-calidad&quot;&gt;El Corte Cualitativo Antes de Medir Calidad&lt;/h2&gt;

&lt;p&gt;Después de los dos primeros hallazgos, ya tenía la mitad de la historia del benchmark antes de correr una sola evaluación. Esta es la tabla que nadie te muestra cuando comparas estrategias de chunking:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Estrategia&lt;/th&gt;
      &lt;th&gt;Documentos indexados&lt;/th&gt;
      &lt;th&gt;Por qué&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;1 / 3&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Falla con archivos &amp;gt; 50,000 caracteres&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;3 / 3&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;✅ Sin restricciones prácticas de tamaño&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HIERARCHICAL&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;3 / 3&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;✅ Sin restricciones prácticas de tamaño&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;1 / 3&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Falla con archivos &amp;gt; 1,000,000 caracteres&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;3 / 3&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;✅ (después de resolver 3 gotchas que veremos después)&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Antes de evaluar calidad de retrieval, &lt;strong&gt;solo 3 de las 5 estrategias pueden ingestar documentación técnica normal sin preprocesamiento&lt;/strong&gt;. Este es el dato que deberías llevarte aunque no leas nada más del artículo.&lt;/p&gt;

&lt;h2 id=&quot;los-7-gotchas-de-infraestructura-que-nadie-documenta-junto&quot;&gt;Los 7 Gotchas de Infraestructura Que Nadie Documenta Junto&lt;/h2&gt;

&lt;p&gt;Antes de mostrar los números cuantitativos, necesito contar algo que me tomó más tiempo de lo que esperaba: los problemas de infraestructura que aparecieron al intentar desplegar todo con Terraform. Son 7 en total, y son el tipo de cosa que solo descubres cuando te sientas a hacerlo desde cero, sin la consola asistiéndote.&lt;/p&gt;

&lt;p&gt;Los dejo aquí porque cualquier persona que intente reproducir este benchmark va a encontrarse con varios de ellos, y tenerlos juntos en un solo lugar ahorra mucho tiempo.&lt;/p&gt;

&lt;h3 id=&quot;gotcha-1-por-qué-falla-la-ingesta-con-filterable-metadata-must-have-at-most-2048-bytes&quot;&gt;Gotcha #1: ¿Por qué falla la ingesta con “Filterable metadata must have at most 2048 bytes”?&lt;/h3&gt;

&lt;p&gt;Al primer intento de ingesta, las &lt;strong&gt;5 KBs&lt;/strong&gt; fallaron con el mismo error:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Invalid record for key &apos;&amp;lt;uuid&amp;gt;&apos;: 
Filterable metadata must have at most 2048 bytes
(Service: S3Vectors, Status Code: 400)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;S3 Vectors tiene un límite de 2,048 bytes de metadata “filtrable” por vector. Por default, Bedrock KB mete dos cosas como filtrable: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AMAZON_BEDROCK_TEXT&lt;/code&gt; (el texto del chunk) y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;AMAZON_BEDROCK_METADATA&lt;/code&gt; (metadata del documento). Casi cualquier chunk de tamaño razonable excede los 2 KB solo con el texto.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;La solución&lt;/strong&gt;: al crear el índice de S3 Vectors, declarar explícitamente esos campos como no-filtrables:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;aws_s3vectors_index&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;strategies&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;c1&quot;&gt;# ... otros campos ...&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;metadata_configuration&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;nx&quot;&gt;non_filterable_metadata_keys&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
      &lt;span class=&quot;s2&quot;&gt;&quot;AMAZON_BEDROCK_TEXT&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;s2&quot;&gt;&quot;AMAZON_BEDROCK_METADATA&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚨 &lt;strong&gt;ProTip #5&lt;/strong&gt;: Los índices de S3 Vectors son &lt;strong&gt;inmutables&lt;/strong&gt;. Si creas un índice sin esta configuración y te das cuenta después, no hay manera de editarlo: tienes que hacer &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;terraform destroy&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;apply&lt;/code&gt; otra vez. Verifica esto antes de aprovisionar.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;gotchas-2-4-por-qué-la-lambda-del-custom-chunker-falla-con-access-denied-for-lambdainvokefunction&quot;&gt;Gotchas #2-4: ¿Por qué la Lambda del CUSTOM chunker falla con “Access denied for lambda:InvokeFunction”?&lt;/h3&gt;

&lt;p&gt;Configurar un Lambda chunker suena directo en el papel: escribes el código, le das permisos IAM, listo. En la práctica, tuve que resolver tres problemas distintos que se manifiestan &lt;strong&gt;con errores muy similares&lt;/strong&gt;. Si resuelves solo uno o dos, sigue fallando pero con un mensaje que parece el mismo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Problema 1: Falta la &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws_lambda_permission&lt;/code&gt;&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Primer error:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Access denied for lambda:InvokeFunction for Lambda function ARN
arn:aws:lambda:us-east-1:...:function:...-chunker:$LATEST.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Darle al IAM role del KB un permiso &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;lambda:InvokeFunction&lt;/code&gt; &lt;strong&gt;no basta&lt;/strong&gt;. Lambda también exige que la función tenga una resource-based policy que permita a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock.amazonaws.com&lt;/code&gt; invocarla:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;resource&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;aws_lambda_permission&quot;&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;bedrock_invoke&quot;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;statement_id&lt;/span&gt;  &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;AllowBedrockKBInvoke&quot;&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;action&lt;/span&gt;        &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;lambda:InvokeFunction&quot;&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;function_name&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;aws_lambda_function&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;custom_chunker&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;function_name&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;principal&lt;/span&gt;     &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;bedrock.amazonaws.com&quot;&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;source_arn&lt;/span&gt;    &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:bedrock:${var.aws_region}:${data.aws_caller_identity.current.account_id}:knowledge-base/*&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Cuando creas la KB por consola, AWS genera este permiso automáticamente. Con Terraform crudo, tienes que declararlo explícitamente.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Problema 2: El Resource del role del KB necesita incluir el qualifier wildcard&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Con el permiso resource-based en su lugar, el siguiente intento falló &lt;strong&gt;con el mismo mensaje&lt;/strong&gt;. La diferencia sutil: ahora el problema es del lado del IAM role del KB.&lt;/p&gt;

&lt;p&gt;La razón: Bedrock invoca la Lambda usando el ARN qualificado &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&amp;lt;arn&amp;gt;:$LATEST&lt;/code&gt;, no el ARN base. Si tu policy dice:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;Resource&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;aws_lambda_function&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;custom_chunker&lt;/span&gt;&lt;span class=&quot;err&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;arn&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;IAM no matchea. La solución es incluir ambos:&lt;/p&gt;

&lt;div class=&quot;language-hcl highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;Resource&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
  &lt;span class=&quot;nx&quot;&gt;aws_lambda_function&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;custom_chunker&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;arn&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;s2&quot;&gt;&quot;${aws_lambda_function.custom_chunker.arn}:*&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Problema 3: El contrato del handler usa keys relativos, no URIs S3&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Con los dos problemas IAM resueltos, la Lambda al fin se invocaba. Y explotaba con:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValueError: Invalid S3 URI: intermediate/.../well-architected-framework_1.JSON
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Los ejemplos que circulan muestran &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;event[&quot;inputFiles&quot;][*][&quot;contentBatches&quot;][*][&quot;key&quot;]&lt;/code&gt; tratado como si fuera un URI &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;s3://bucket/key&lt;/code&gt;. No lo es. Bedrock manda &lt;strong&gt;solo el key path&lt;/strong&gt; relativo al bucket intermedio, que te llega en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;event[&quot;bucketName&quot;]&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;handler&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;intermediate_bucket&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bucketName&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;input_file&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inputFiles&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;batch&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;input_file&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;contentBatches&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;key&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;batch&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# relative path, NO un URI
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;s3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get_object&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Bucket&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;intermediate_bucket&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# ... procesar chunking ...
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;s3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;put_object&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Bucket&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;intermediate_bucket&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Key&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;output_key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Body&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;...)&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# Output: key, NO URI
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;processed_batches&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;append&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;key&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_key&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔧 &lt;strong&gt;ProTip #6&lt;/strong&gt;: Para tener un CUSTOM chunker funcional desplegado con Terraform necesitas los tres fixes juntos. Resolver solo uno o dos produce errores que se parecen lo suficiente como para mandarte a debuggear la cosa equivocada. Si el tuyo no funciona a la primera, revisa los tres antes de asumir que es otra cosa.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;gotcha-5-por-qué-sonnet-46-no-aparece-como-modelo-juez-válido-en-bedrock-evaluations&quot;&gt;Gotcha #5: ¿Por qué Sonnet 4.6 no aparece como modelo juez válido en Bedrock Evaluations?&lt;/h3&gt;

&lt;p&gt;Cuando intenté usar Sonnet 4.6 como juez para las evaluaciones:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: The requested evaluator model(s)
us.anthropic.claude-sonnet-4-6 are not supported.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Retrocediendo a Sonnet 3.7:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: Access denied. This Model is marked by provider as
Legacy and you have not been actively using the model in the last 30 days.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Bedrock Evaluations mantiene una &lt;strong&gt;allowlist fija&lt;/strong&gt; de modelos que pueden actuar como juez. Según la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/evaluation-judge.html&quot; target=&quot;_blank&quot;&gt;documentación oficial&lt;/a&gt; verificada a abril 2026, la lista es:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;amazon.nova-pro-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-3-5-sonnet-20240620-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-3-5-sonnet-20241022-v2:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-3-7-sonnet-20250219-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-3-haiku-20240307-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-3-5-haiku-20241022-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;meta.llama3-1-70b-instruct-v1:0&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mistral.mistral-large-2402-v1:0&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Tres observaciones importantes:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Sonnet 4.6 no está en la lista&lt;/strong&gt;. Tampoco, en abril de 2026, Sonnet 4.5 ni Opus 4.x. La allowlist iba dos generaciones atrás del estado del arte.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;La consola de Bedrock muestra cualquier inference profile disponible&lt;/strong&gt; al elegir juez, incluyendo modelos que luego serán rechazados. La validación ocurre server-side en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CreateEvaluationJob&lt;/code&gt;.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Los modelos “soportados” pueden volverse inutilizables por desuso&lt;/strong&gt;. Si un modelo está marcado como Legacy y tu cuenta no lo invocó en 30 días, Bedrock lo deniega aunque esté en la allowlist.&lt;/li&gt;
&lt;/ol&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (agosto 2026)&lt;/strong&gt;: La allowlist se amplió y el punto 1 ya no aplica completo. La &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/evaluation-judge.html&quot; target=&quot;_blank&quot;&gt;documentación oficial&lt;/a&gt; hoy incluye &lt;strong&gt;Claude Sonnet 4.5&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-sonnet-4-5-20250929-v1:0&lt;/code&gt;), &lt;strong&gt;Opus 4.5&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;anthropic.claude-opus-4-5-20251101-v1:0&lt;/code&gt;) y &lt;strong&gt;Haiku 4.5&lt;/strong&gt;, además de Nova 2 Lite, Nova Premier y Nova Micro — tanto para métricas built-in como custom. Sonnet 4.6 &lt;strong&gt;sigue ausente&lt;/strong&gt;, así que el error que gatilló este gotcha se reproduce igual, pero la brecha bajó de dos generaciones a una. Los puntos 2 y 3 siguen vigentes tal cual. Y mi solución no cambia: Nova Pro como juez sigue siendo la elección correcta, solo que ahora por el argumento metodológico del ProTip #7 y no por falta de opciones.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: El punto 1 ya cayó del todo, al menos parcialmente en alcance. Verificado a septiembre de 2026 mientras preparaba el &lt;a href=&quot;/managed-kb-vs-chunking.html&quot; target=&quot;_blank&quot;&gt;benchmark de Managed Knowledge Base&lt;/a&gt;, &lt;strong&gt;Sonnet 4.6 ya es seleccionable como juez para evaluación RAG/KB&lt;/strong&gt;. Dos advertencias sobre el punto 3, que sigue siendo el más traicionero: &lt;strong&gt;Nova Premier quedó marcado &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Legacy&lt;/code&gt;&lt;/strong&gt; con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;endOfLifeTime=2026-09-14&lt;/code&gt;, así que desaparece como opción de juez; y mi recomendación de fondo no se mueve un milímetro — seguí usando Nova Pro como juez cross-family en el benchmark nuevo, con Sonnet 4.6 disponible y todo, precisamente por el ProTip #7.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Mi solución&lt;/strong&gt;: usar &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;amazon.nova-pro-v1:0&lt;/code&gt; como juez. Además de estar en la lista oficial, me dio algo técnicamente más defendible para el artículo: &lt;strong&gt;un juez cross-family&lt;/strong&gt; (AWS Nova evaluando respuestas de Anthropic Sonnet 4.6), lo cual reduce el sesgo de auto-evaluación intra-familia.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎓 &lt;strong&gt;ProTip #7&lt;/strong&gt;: Adopta cross-family judging como patrón, no solo por las limitaciones de AWS sino porque es metodológicamente más sólido. “Claude evaluando a Claude” es una crítica válida en papers académicos. Nova evaluando Claude (o viceversa) elimina esa crítica.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;gotcha-6-por-qué-el-eval-job-falla-con-metric-name-builtincontextrelevance-is-not-available&quot;&gt;Gotcha #6: ¿Por qué el eval job falla con “metric name Builtin.ContextRelevance is not available”?&lt;/h3&gt;

&lt;p&gt;Mi siguiente intento, después de resolver el juez:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;ValidationException: The metric name Builtin.ContextRelevance is not available
for RAG retrieveAndGenerate evaluations.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Bedrock Evaluations divide las métricas built-in para RAG en &lt;strong&gt;dos conjuntos mutuamente excluyentes&lt;/strong&gt; según el tipo de job:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Métrica&lt;/th&gt;
      &lt;th&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieveAndGenerate&lt;/code&gt; (end-to-end)&lt;/th&gt;
      &lt;th&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieve&lt;/code&gt; (solo retrieval)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.Correctness&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.Completeness&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.Helpfulness&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.Faithfulness&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.ContextRelevance&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Builtin.ContextCoverage&lt;/code&gt;&lt;/td&gt;
      &lt;td&gt;❌&lt;/td&gt;
      &lt;td&gt;✅&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Si mandas una métrica del set equivocado, &lt;strong&gt;el job completo falla&lt;/strong&gt;, incluso si las otras métricas sí aplican al tipo de job.&lt;/p&gt;

&lt;p&gt;Además, hay un matiz importante sobre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieveAndGenerate&lt;/code&gt;: este tipo de job produce scores que combinan &lt;strong&gt;ambas cosas&lt;/strong&gt;: el retrieval y la generación. De ahí que Correctness y Faithfulness puedan caer simultáneamente cuando el retrieval falla (como veremos en la Observación 3). Para aislar si el problema está en el retrieval o en el generator, necesitas correr también el job &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieve&lt;/code&gt;-only con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextRelevance&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextCoverage&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;La &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-evaluation-metrics.html&quot; target=&quot;_blank&quot;&gt;documentación oficial&lt;/a&gt; sí separa las métricas por tipo de job, pero muchos ejemplos y blogs listan las 6 en la misma lista, induciendo al error.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #8&lt;/strong&gt;: Para un benchmark completo necesitas &lt;strong&gt;dos&lt;/strong&gt; jobs por KB: uno &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieveAndGenerate&lt;/code&gt; con las 4 métricas de generación, y otro &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;retrieve&lt;/code&gt; con las 2 de retrieval. Eso duplica el costo y tiempo de evaluación. En este benchmark corrí solo los jobs end-to-end; un siguiente paso sería correr también retrieve-only para tener las 6 métricas.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;gotcha-7-por-qué-bedrock-evaluations-dice-does-not-have-permission-to-call-the-kb-api-aunque-las-policies-parezcan-correctas&quot;&gt;Gotcha #7: ¿Por qué Bedrock Evaluations dice “does not have permission to call the KB API” aunque las policies parezcan correctas?&lt;/h3&gt;

&lt;p&gt;Ultimo gotcha. Con todo lo anterior resuelto, los eval jobs seguían fallando:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;The provided role does not have permission to call the KB API.
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El mensaje te hace pensar que es un problema de permissions policy. En realidad son dos cosas:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Trust policy&lt;/strong&gt;: el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws:SourceArn&lt;/code&gt; debe incluir el pattern de evaluation jobs:
    &lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Condition&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;StringLike&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;aws:SourceArn&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:bedrock:us-east-1:&amp;lt;account&amp;gt;:evaluation-job/*&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Permission policy&lt;/strong&gt;: los ARNs de las KBs que el job va a consultar deben estar &lt;strong&gt;específicos&lt;/strong&gt;, no con wildcard:
    &lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Resource&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:bedrock:us-east-1:&amp;lt;account&amp;gt;:knowledge-base/&amp;lt;kb-id-1&amp;gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;err&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;    &lt;/div&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Cualquiera de las dos ausente produce el mismo error genérico. Te manda a buscar el bug en el lugar equivocado.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #9&lt;/strong&gt;: Cuando Bedrock Evaluations te diga “does not have permission to call the KB API”, siempre revisa &lt;strong&gt;ambos&lt;/strong&gt; lados del IAM: trust policy Y permission policy. No es lo mismo que cuando otros servicios AWS dan ese error.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;sumando-los-gotchas&quot;&gt;Sumando los Gotchas&lt;/h3&gt;

&lt;p&gt;Los 7 problemas me tomaron varias horas de debugging. Todos son resolvibles y todos están arreglados en &lt;a href=&quot;https://github.com/codecr/bedrock-chunking-benchmark&quot; target=&quot;_blank&quot;&gt;el repositorio&lt;/a&gt; con el código Terraform completo. Pero vale la pena documentarlos juntos porque &lt;strong&gt;nadie lo había hecho antes&lt;/strong&gt; y porque cualquier persona que replique esto va a tropezar con al menos 3 de ellos.&lt;/p&gt;

&lt;p&gt;Ahora sí, los números del benchmark.&lt;/p&gt;

&lt;h2 id=&quot;los-resultados-cuantitativos&quot;&gt;Los Resultados Cuantitativos&lt;/h2&gt;

&lt;p&gt;25 preguntas con ground truth. 5 Knowledge Bases. 125 prompts al generator (Claude Sonnet 4.6) y cerca de 500 juicios del evaluator (Nova Pro). Los scores son el promedio por métrica sobre las 25 preguntas:&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/2026/bedrock-chunking-benchmark.png&quot; alt=&quot;Benchmark de las 5 estrategias de chunking en Amazon Bedrock Knowledge Bases&quot; /&gt;
&lt;em&gt;Figura 1: Scores promedio por estrategia de chunking en 25 preguntas con ground truth. El “cliff” entre el grupo alto (Custom, Hierarchical, Fixed) y el grupo bajo (None, Semantic) está causado por fallas de ingesta, no por calidad intrínseca del chunking.&lt;/em&gt;&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Estrategia&lt;/th&gt;
      &lt;th&gt;Correctness&lt;/th&gt;
      &lt;th&gt;Completeness&lt;/th&gt;
      &lt;th&gt;Helpfulness&lt;/th&gt;
      &lt;th&gt;Faithfulness&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;custom&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;0.940&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;0.790&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;0.873&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;0.820&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;hierarchical&lt;/td&gt;
      &lt;td&gt;0.920&lt;/td&gt;
      &lt;td&gt;0.750&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;0.887&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;0.810&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;fixed&lt;/td&gt;
      &lt;td&gt;0.880&lt;/td&gt;
      &lt;td&gt;0.760&lt;/td&gt;
      &lt;td&gt;0.880&lt;/td&gt;
      &lt;td&gt;0.810&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;none&lt;/td&gt;
      &lt;td&gt;0.261&lt;/td&gt;
      &lt;td&gt;0.210&lt;/td&gt;
      &lt;td&gt;0.710&lt;/td&gt;
      &lt;td&gt;0.228&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;semantic&lt;/td&gt;
      &lt;td&gt;0.160&lt;/td&gt;
      &lt;td&gt;0.104&lt;/td&gt;
      &lt;td&gt;0.580&lt;/td&gt;
      &lt;td&gt;0.140&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Déjame compartir cinco observaciones con los datos en la mano.&lt;/p&gt;

&lt;h3 id=&quot;observación-1-hay-dos-grupos-no-un-ranking-continuo&quot;&gt;Observación 1: Hay Dos Grupos, No un Ranking Continuo&lt;/h3&gt;

&lt;p&gt;Fixed, Hierarchical y Custom viven entre 0.75 y 0.94 en todas las métricas. None y Semantic viven entre 0.10 y 0.71. La brecha en Correctness entre el tercer lugar del grupo alto (Fixed, 0.880) y el mejor del grupo bajo (None, 0.261) es de &lt;strong&gt;0.619 puntos&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Eso no se explica con varianza estadística. Es un corte cualitativo producido por las limitaciones de ingesta que documenté arriba. &lt;strong&gt;Los scores bajos de None y Semantic no son un juicio sobre la calidad de esas estrategias&lt;/strong&gt;: son la consecuencia aritmética de que no pudieron indexar 2 de los 3 documentos.&lt;/p&gt;

&lt;p&gt;Si solo hubieras mirado esta tabla sin el contexto de ingesta, habrías concluido que Semantic chunking es terrible. Y sería una conclusión falsa. Lo que es terrible es intentar aplicar Semantic chunking a un corpus que excede su límite operacional.&lt;/p&gt;

&lt;h3 id=&quot;observación-2-entre-las-3-estrategias-buenas-el-margen-es-pequeño&quot;&gt;Observación 2: Entre las 3 Estrategias “Buenas”, el Margen es Pequeño&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Custom&lt;/strong&gt; gana 3 de 4 métricas (Correctness, Completeness, Faithfulness).&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Hierarchical&lt;/strong&gt; gana Helpfulness por 0.007 sobre Fixed (prácticamente un empate).&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Diferencia entre el primero (Custom, 0.940) y el tercero (Fixed, 0.880) en Correctness: 0.060&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Un margen de 0.06 es medible pero no aplastante. Mi chunker custom (un recursive character splitter markdown-aware) está haciendo algo útil, pero &lt;strong&gt;no justifica el costo operacional&lt;/strong&gt; del Lambda para un corpus genérico: Fixed te da el 94% del resultado sin los 3 gotchas de IAM, sin el costo del Lambda, sin el debugging adicional.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🎯 &lt;strong&gt;ProTip #10&lt;/strong&gt;: Un custom chunker solo vale la pena si tienes un formato de documento muy específico donde el chunker genérico rompe unidades semánticas clave de tu dominio (código fuente, transcripts de llamadas, logs estructurados, contratos con cláusulas numeradas). Para documentación técnica estándar, Fixed gana por simplicidad operacional.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;observación-3-faithfulness-es-la-métrica-más-discriminativa&quot;&gt;Observación 3: Faithfulness Es la Métrica Más Discriminativa&lt;/h3&gt;

&lt;p&gt;Mira la diferencia entre Correctness y Faithfulness para las estrategias que fallaron:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Estrategia&lt;/th&gt;
      &lt;th&gt;Correctness&lt;/th&gt;
      &lt;th&gt;Faithfulness&lt;/th&gt;
      &lt;th&gt;Diferencia&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;none&lt;/td&gt;
      &lt;td&gt;0.261&lt;/td&gt;
      &lt;td&gt;0.228&lt;/td&gt;
      &lt;td&gt;-0.033&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;semantic&lt;/td&gt;
      &lt;td&gt;0.160&lt;/td&gt;
      &lt;td&gt;0.140&lt;/td&gt;
      &lt;td&gt;-0.020&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Faithfulness cae más fuerte que Correctness cuando la KB no tiene el contenido. ¿Por qué? &lt;strong&gt;Porque una respuesta puede ser correcta sin estar fundada en el contexto recuperado&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Cuando la KB no tiene el documento relevante indexado, Sonnet 4.6 igual produce una respuesta usando su conocimiento paramétrico. Si la respuesta casualmente coincide con el ground truth, Correctness le pone un score decente. Pero Faithfulness mide si la respuesta está sustentada en &lt;strong&gt;lo que la KB retornó&lt;/strong&gt;, y la KB no retornó nada útil. Por eso Faithfulness se colapsa.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔍 &lt;strong&gt;ProTip #11&lt;/strong&gt;: Si estás diagnosticando un RAG que parece dar respuestas correctas pero “sospechosas”, &lt;strong&gt;Faithfulness es la métrica que te va a confirmar lo que intuyes&lt;/strong&gt;. Una caída de Faithfulness es el indicador más temprano de que tu KB no está trayendo el contexto real — más sensible que Correctness.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;observación-4-semantic-terminó-peor-que-none-el-análisis-contraintuitivo&quot;&gt;Observación 4: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; Terminó Peor Que &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt;. El Análisis Contraintuitivo&lt;/h3&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;Hallazgo clave&lt;/strong&gt;: Cuando una estrategia de chunking no puede ingestar la mayoría del corpus, &lt;strong&gt;el chunking fino amplifica el ruido de lo poco que sí ingestó&lt;/strong&gt;. El chunking ausente lo unifica en un chunk gigante coherente que al menos es interpretable. Esto no es crítica a SEMANTIC como técnica — es un recordatorio de que los scores bajos no son representativos de la estrategia en su caso de uso adecuado.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Este fue el resultado que más me hizo detenerme a pensar. Semantic debería ser &lt;em&gt;al menos tan bueno&lt;/em&gt; como None: chunkear “semánticamente” debería ser mejor que no chunkear.&lt;/p&gt;

&lt;p&gt;Los datos dicen lo contrario. En las 4 métricas, Semantic está por debajo de None.&lt;/p&gt;

&lt;p&gt;Mi hipótesis, después de analizar los datos:&lt;/p&gt;

&lt;p&gt;Ambas estrategias solo pudieron indexar &lt;strong&gt;el mismo archivo&lt;/strong&gt;: el HTML del blog (1.08 MB). Pero lo hacen de formas distintas:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt; indexa ese HTML como un único chunk gigante&lt;/strong&gt; de aproximadamente 1 millón de caracteres. Cuando el retrieval hace match sobre cualquier pregunta que se relacione al contenido del blog, recupera el blog entero como contexto. El recall es perfecto (todo el contenido está ahí), aunque el contexto sea muy ruidoso (la mayor parte del chunk no aplica a la pregunta).&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt; subdivide ese mismo HTML en chunks más chicos y coherentes&lt;/strong&gt;. Para las ~20 preguntas del benchmark cuyo tema &lt;strong&gt;no está&lt;/strong&gt; en el blog (sino en los PDFs que Semantic no pudo indexar), el retrieval devuelve chunks pequeños que son superficialmente relevantes pero vacíos del contenido que la pregunta realmente necesita. El juez califica la respuesta como no fiel (el contexto recuperado no la soporta) &lt;strong&gt;y&lt;/strong&gt; no correcta.&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;En otras palabras: &lt;strong&gt;cuando tu estrategia no puede ingestar la mayoría del corpus, el chunking fino amplifica el ruido de lo poco que sí ingestó. El chunking ausente lo unifica en un chunk gigante coherente que al menos es interpretable&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Esto no es una crítica a Semantic como técnica. Es un recordatorio adicional de que con un corpus que la estrategia no puede procesar, ningún score va a ser bueno, y los scores bajos &lt;strong&gt;tampoco son representativos de la estrategia en su caso de uso adecuado&lt;/strong&gt;.&lt;/p&gt;

&lt;h3 id=&quot;observación-5-helpfulness-es-la-métrica-menos-útil-para-comparar-chunking&quot;&gt;Observación 5: Helpfulness Es la Métrica Menos Útil Para Comparar Chunking&lt;/h3&gt;

&lt;p&gt;Mira el rango de Helpfulness entre todas las estrategias:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;custom: 0.873&lt;/li&gt;
  &lt;li&gt;hierarchical: 0.887&lt;/li&gt;
  &lt;li&gt;fixed: 0.880&lt;/li&gt;
  &lt;li&gt;none: 0.710&lt;/li&gt;
  &lt;li&gt;semantic: 0.580&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;El rango total es 0.30 puntos. Comparado con Correctness (rango 0.78) y Faithfulness (rango 0.68), &lt;strong&gt;Helpfulness casi no diferencia&lt;/strong&gt;. Incluso las estrategias que indexaron casi nada del corpus sacaron entre 0.58 y 0.71.&lt;/p&gt;

&lt;p&gt;El juez parece premiar “que la respuesta esté bien escrita, estructurada y sea útil en sí misma”, independientemente de si es correcta o fiel al contexto. Es una métrica de forma más que de fondo.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;💡 &lt;strong&gt;ProTip #12&lt;/strong&gt;: Si vas a elegir 3 métricas para comparar estrategias de chunking, elige &lt;strong&gt;Correctness, Faithfulness y Completeness&lt;/strong&gt; en ese orden. Helpfulness es útil para medir la calidad &lt;em&gt;del generator&lt;/em&gt;, no del &lt;em&gt;chunking&lt;/em&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2 id=&quot;tabla-de-decisión-qué-estrategia-para-tu-caso&quot;&gt;Tabla de Decisión: ¿Qué Estrategia Para Tu Caso?&lt;/h2&gt;

&lt;p&gt;Después de todo este análisis, esta es la recomendación que yo le daría a alguien hoy:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Tu caso de uso&lt;/th&gt;
      &lt;th&gt;Estrategia recomendada&lt;/th&gt;
      &lt;th&gt;Razón&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Documentación técnica (whitepapers, developer guides, manuales corporativos)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt;&lt;/strong&gt; (max_tokens=512, overlap=20%)&lt;/td&gt;
      &lt;td&gt;Ingresa todo, scores altos, mínima complejidad. Cubre el 80% de casos.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Documentos con jerarquía muy marcada (libros con capítulos/secciones, documentación de APIs)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;HIERARCHICAL&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Usa la estructura real del documento. Margen pequeño pero medible sobre FIXED_SIZE.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Corpus pre-chunkeado (cada archivo es una FAQ, un ticket, un producto)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;NONE&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Único caso legítimo. Cada archivo debe ser &amp;lt; 50,000 caracteres.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Corpus de artículos/emails/blogs cortos (cada archivo &amp;lt; 1 MB)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;SEMANTIC&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Preserva fronteras semánticas naturales. Solo si todos tus archivos son pequeños.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Formato muy específico (código fuente, transcripts, logs con estructura)&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;CUSTOM&lt;/code&gt;&lt;/strong&gt; (Lambda)&lt;/td&gt;
      &lt;td&gt;Cuando el chunker genérico rompe unidades semánticas del dominio. Asegúrate de tener presupuesto para debugging.&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;No estás seguro&lt;/td&gt;
      &lt;td&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;En serio. Empieza por aquí. Mide. Cambia después si los datos justifican el cambio.&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;h2 id=&quot;mi-recomendación-personal&quot;&gt;Mi Recomendación Personal&lt;/h2&gt;

&lt;p&gt;Si mañana tuviera que construir un RAG de producción con Bedrock Knowledge Bases, arrancaría con esta configuración:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Chunking&lt;/strong&gt;: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FIXED_SIZE&lt;/code&gt;, max_tokens=512, overlap=20%&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Backend&lt;/strong&gt;: S3 Vectors (excepto que necesite hybrid search)&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Embedding&lt;/strong&gt;: Titan Text Embeddings v2, 1024 dimensiones&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Generator&lt;/strong&gt;: Claude Sonnet 4.6 vía inference profile&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Evaluation&lt;/strong&gt;: jobs periódicos con Nova Pro como juez (cross-family)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Y &lt;strong&gt;mediría Faithfulness y Correctness en un set de preguntas con ground truth desde el día 1&lt;/strong&gt;. Solo consideraría moverme a Hierarchical o Custom si los números muestran un gap específico que justifique la complejidad adicional.&lt;/p&gt;

&lt;p&gt;El chunking se vende a veces como la gran palanca del RAG. La realidad es que lo que más mueve la aguja es:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Que tu estrategia pueda ingestar tu corpus sin preprocesamiento manual.&lt;/li&gt;
  &lt;li&gt;Que tengas forma de medir que está funcionando.&lt;/li&gt;
  &lt;li&gt;Que puedas iterar sobre esa medición.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Todo lo demás es ajuste fino.&lt;/p&gt;

&lt;h2 id=&quot;lo-que-queda-pendiente&quot;&gt;Lo Que Queda Pendiente&lt;/h2&gt;

&lt;p&gt;Este benchmark tiene un scope acotado a propósito. Lo que sí podría ser un siguiente paso:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Métricas retrieval-only&lt;/strong&gt; (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextRelevance&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ContextCoverage&lt;/code&gt;) con un segundo set de eval jobs. Lo dejé afuera por la partición de métricas (gotcha #6).&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Grid search de parámetros&lt;/strong&gt; dentro de cada estrategia. ¿Qué pasa si Fixed usa max_tokens=1024 en vez de 512? ¿Cuánto mueve la aguja el overlap?&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Corpus en español&lt;/strong&gt;. Este benchmark usó documentación en inglés. Titan v2 es multilingüe, pero valdría la pena verificar si el corte cualitativo es igual en otros idiomas.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Costo por consulta en producción&lt;/strong&gt; con patrones de tráfico realistas. Este benchmark mide calidad; el costo operacional en tiempo real merece su propio análisis.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Si alguno de estos temas te interesa o quieres verlo cubierto en un artículo siguiente, déjame un comentario. Y si replicas este benchmark en tu propia cuenta y encuentras más gotchas o mejores resultados, me encantaría saberlo.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;Armar este benchmark me cambió la forma de pensar sobre chunking en Bedrock Knowledge Bases. No porque descubrí que tal o cual estrategia es “mejor”, sino porque me quedó claro que &lt;strong&gt;la discusión normal sobre chunking tiene el orden equivocado&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Primero importa si tu estrategia puede ingestar tu corpus. Después importa si tu infra está bien configurada. Después importa tener métricas objetivas para comparar. Y solo al final, mucho después, importa el matiz de cuál estrategia tiene 0.06 puntos más que otra en una métrica específica.&lt;/p&gt;

&lt;p&gt;Si este artículo te ahorra una tarde de debugging con los gotchas de infraestructura, me alegra el día. Si te ayuda a tomar una decisión de arquitectura con evidencia en vez de intuición, mejor todavía.&lt;/p&gt;

&lt;p&gt;El código completo del benchmark (Terraform + Python + preguntas de evaluación) está en &lt;a href=&quot;https://github.com/codecr/bedrock-chunking-benchmark&quot; target=&quot;_blank&quot;&gt;github.com/codecr/bedrock-chunking-benchmark&lt;/a&gt;. Cualquiera puede reproducir los resultados en su cuenta por unos 18-20 USD aproximadamente, gracias al costo prácticamente nulo de S3 Vectors como backend.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🚀 &lt;strong&gt;Pro Tip Final&lt;/strong&gt;: Si vas a llevar un RAG a producción, invierte tiempo en evaluación &lt;strong&gt;antes&lt;/strong&gt; de invertir tiempo en chunking. Una estrategia de chunking “mediocre” con buena evaluación te va a llevar más lejos que la “mejor” estrategia sin forma de medir si está funcionando.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Si te interesa profundizar en otras capacidades de Bedrock relacionadas, te invito a leer mis artículos sobre &lt;a href=&quot;/bedrock-evaluations.html&quot; target=&quot;_blank&quot;&gt;Bedrock Evaluations&lt;/a&gt; y &lt;a href=&quot;/bedrock-guardrails.html&quot; target=&quot;_blank&quot;&gt;Bedrock Guardrails&lt;/a&gt;, que complementan bien este análisis.&lt;/p&gt;

&lt;p&gt;¡Nos vemos en el próximo artículo! No olviden compartir en los comentarios si han tenido experiencias similares configurando Knowledge Bases en producción, o si tienen dudas sobre alguno de los hallazgos. ¡Feliz desarrollo! 🚀&lt;/p&gt;
</description>
                <pubDate>Fri, 24 Apr 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/chunking-benchmark.html</link>
                <guid isPermaLink="true">https://gerardo.dev/chunking-benchmark.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>KnowledgeBases</category>
                
                <category>S3Vectors</category>
                
                <category>RAG</category>
                
                <category>GenAI</category>
                
                <category>Chunking</category>
                
                
            </item>
        
            <item>
                <title>Tu agente de código nunca más empezará desde cero: Session Storage en AgentCore Runtime</title>
                <description>&lt;h1 id=&quot;tu-agente-de-código-nunca-más-empezará-desde-cero-session-storage-en-agentcore-runtime&quot;&gt;Tu agente de código nunca más empezará desde cero: Session Storage en AgentCore Runtime&lt;/h1&gt;

&lt;p&gt;Imagina este escenario: tu coding agent pasó los últimos 40 minutos scaffoldeando un proyecto Node.js. Instaló dependencias, escribió los modelos, configuró el ORM, dejó las pruebas unitarias a medio terminar. Tienes que cerrar la sesión. Al día siguiente retomas el trabajo — y el agente empieza desde cero. Sin archivos. Sin &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;node_modules&lt;/code&gt;. Sin ningún rastro de lo que construyó.&lt;/p&gt;

&lt;p&gt;Eso no es un bug de tu agente. Es el comportamiento por diseño de cualquier runtime de agentes sin persistencia. Cada sesión arranca desde un filesystem limpio.&lt;/p&gt;

&lt;p&gt;Y hay una distinción importante que vale la pena hacer antes de entrar al código:&lt;/p&gt;

&lt;blockquote&gt;
  &lt;p&gt;&lt;strong&gt;Memoria episódica&lt;/strong&gt; (que cubrimos en el &lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;artículo anterior&lt;/a&gt;) guarda &lt;em&gt;lo que aprendió&lt;/em&gt; el agente: patrones, reflexiones, experiencias pasadas. &lt;strong&gt;Session Storage&lt;/strong&gt; guarda &lt;em&gt;lo que construyó&lt;/em&gt;: archivos, dependencias, artefactos, estado operacional del proyecto.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Son dos formas de persistencia complementarias, no intercambiables. Un agente de producción serio necesita las dos.&lt;/p&gt;

&lt;p&gt;Hoy nos enfocamos en la segunda.&lt;/p&gt;

&lt;h2 id=&quot;el-problema-con-los-agentes-efímeros&quot;&gt;El Problema con los Agentes Efímeros&lt;/h2&gt;

&lt;p&gt;El runtime de AgentCore, como cualquier sistema de cómputo serverless, es &lt;strong&gt;efímero por diseño&lt;/strong&gt;. Cuando una sesión termina o se detiene, el computo asociado se destruye. La próxima vez que invoques la misma sesión, AWS provisiona un nuevo entorno limpio.&lt;/p&gt;

&lt;p&gt;Para agentes conversacionales simples, esto no es un problema. Para coding agents, agentes de análisis de datos de larga duración, o cualquier agente que trabaje con el filesystem, es un bloqueante serio:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;El agente instala paquetes → sesión se detiene → debe reinstalar todo&lt;/li&gt;
  &lt;li&gt;El agente genera artefactos intermedios → sesión se reinicia → archivos perdidos&lt;/li&gt;
  &lt;li&gt;El agente hace checkpoints de un proceso largo → reinicio → sin checkpoints&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Las soluciones tradicionales son dolorosas: sincronizar con S3 manualmente, usar EFS con configuración VPC, o escribir lógica de checkpoint propia. Todas funcionan, pero agregan complejidad operacional que el equipo tiene que mantener.&lt;/p&gt;

&lt;p&gt;AgentCore Runtime Session Storage es la respuesta gestionada de AWS a este problema.&lt;/p&gt;

&lt;h2 id=&quot;cómo-funciona-session-storage&quot;&gt;Cómo Funciona Session Storage&lt;/h2&gt;

&lt;p&gt;Session Storage es una capacidad gestionada del AgentCore Runtime. Tu agente lee y escribe en un directorio local normal — digamos &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/mnt/workspace&lt;/code&gt; — y el runtime replica ese estado de forma transparente hacia almacenamiento durable.&lt;/p&gt;

&lt;p&gt;El ciclo de vida es el siguiente:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Primera invocación de una sesión&lt;/strong&gt; — Se provisiona nuevo compute. El directorio en el mount path aparece vacío.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;El agente escribe archivos&lt;/strong&gt; — Operaciones normales de filesystem (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mkdir&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;write&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;npm install&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git init&lt;/code&gt;). Los datos se replican asíncronamente al storage durable.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;La sesión se detiene&lt;/strong&gt; — El compute se destruye. Los datos pendientes de replicar se flushean durante el shutdown graceful.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Siguiente invocación con el mismo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sessionId&lt;/code&gt;&lt;/strong&gt; — Nuevo compute, pero el filesystem se restaura exactamente donde quedó.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Lo que más me llamó la atención al probarlo: no hay API especial para esto. Tu agente simplemente usa el filesystem como siempre. El runtime maneja todo lo demás.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;Importante&lt;/strong&gt;: Cuando llames explícitamente a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;StopRuntimeSession&lt;/code&gt;, espera a que la operación complete antes de retomar la sesión. Esto garantiza que todos los datos se flusheen al storage durable antes del siguiente inicio.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;aislamiento-por-sesión&quot;&gt;Aislamiento por Sesión&lt;/h3&gt;

&lt;p&gt;Cada sesión tiene su propio storage aislado. Una sesión no puede leer ni escribir en el storage de otra sesión del mismo agente, ni de agentes distintos. Esto es importante para casos multi-tenant o cuando múltiples usuarios tienen sesiones paralelas con el mismo agente.&lt;/p&gt;

&lt;h3 id=&quot;ciclo-de-vida-del-storage&quot;&gt;Ciclo de Vida del Storage&lt;/h3&gt;

&lt;p&gt;Los datos persisten mientras la sesión esté activa. Hay dos condiciones que reinician el filesystem a estado limpio:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;La sesión no es invocada por &lt;strong&gt;14 días consecutivos&lt;/strong&gt;.&lt;/li&gt;
  &lt;li&gt;La versión del agent runtime es actualizada. Si haces un deploy nuevo, las sesiones existentes arrancarán con filesystem vacío.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Este segundo punto es un &lt;strong&gt;gotcha real&lt;/strong&gt; para producción: si tienes sesiones de larga duración activas y haces un deploy, pierden su estado de filesystem. Diseña tu agente para manejar este caso.&lt;/p&gt;

&lt;h2 id=&quot;implementación-coding-agent-con-session-storage-en-agentcore-runtime&quot;&gt;Implementación: Coding Agent con Session Storage en AgentCore Runtime&lt;/h2&gt;

&lt;p&gt;Vamos a construir un coding agent que demuestre la persistencia en acción: crea un proyecto, se detiene, retoma y continúa donde quedó — tanto en archivos como en conversación.&lt;/p&gt;

&lt;h3 id=&quot;prerequisitos&quot;&gt;Prerequisitos&lt;/h3&gt;

&lt;p&gt;Antes de empezar, verifica que tienes:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;AWS CLI&lt;/strong&gt; configurado con permisos sobre &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore-control&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ecr&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Docker con Buildx&lt;/strong&gt; — ejecuta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker buildx version&lt;/code&gt; para confirmar&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Repositorio ECR&lt;/strong&gt; creado en tu cuenta para la imagen del agente&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Región&lt;/strong&gt;: Session Storage está disponible en múltiples regiones (us-west-2, us-east-1, eu-central-1, ap-northeast-1 y otras) — consulta la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-persistent-filesystems.html#session-storage-networking&quot; target=&quot;_blank&quot;&gt;lista actualizada en la documentación oficial&lt;/a&gt; antes de desplegar&lt;/li&gt;
&lt;/ul&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;pip &lt;span class=&quot;nb&quot;&gt;install &lt;/span&gt;strands-agents strands-agents-tools bedrock-agentcore boto3
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;rol-iam-para-el-agent-runtime&quot;&gt;Rol IAM para el Agent Runtime&lt;/h3&gt;

&lt;p&gt;El runtime necesita un rol que AgentCore pueda asumir. La &lt;strong&gt;trust policy&lt;/strong&gt;:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Version&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2012-10-17&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Statement&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Effect&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Allow&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Principal&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Service&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;bedrock-agentcore.amazonaws.com&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Action&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;sts:AssumeRole&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Y la &lt;strong&gt;permissions policy&lt;/strong&gt; con los permisos mínimos necesarios:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Version&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2012-10-17&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Statement&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Effect&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Allow&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Action&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;bedrock:InvokeModel&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;bedrock:InvokeModelWithResponseStream&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Resource&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;*&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Effect&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Allow&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Action&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;ecr:GetDownloadUrlForLayer&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;ecr:BatchGetImage&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;ecr:GetAuthorizationToken&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Resource&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;*&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Effect&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Allow&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Action&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;logs:CreateLogGroup&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;logs:CreateLogStream&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;logs:PutLogEvents&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;Resource&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;arn:aws:logs:us-west-2:TU_CUENTA:*&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;estructura-del-proyecto&quot;&gt;Estructura del Proyecto&lt;/h3&gt;

&lt;p&gt;Tres archivos en el mismo directorio:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;coding-agent/
├── Dockerfile
├── coding_agent.py
└── requirements.txt
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;el-contenedor&quot;&gt;El Contenedor&lt;/h3&gt;

&lt;p&gt;AgentCore Runtime ejecuta contenedores &lt;strong&gt;ARM64 exclusivamente&lt;/strong&gt;. Si desarrollas en una máquina x86/amd64, necesitas cross-compilation con Docker Buildx:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c&quot;&gt;# Crear un builder para ARM64&lt;/span&gt;
docker buildx create &lt;span class=&quot;nt&quot;&gt;--use&lt;/span&gt;

&lt;span class=&quot;c&quot;&gt;# Build + push directo a ECR&lt;/span&gt;
docker buildx build &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--platform&lt;/span&gt; linux/arm64 &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;-t&lt;/span&gt; TU_CUENTA.dkr.ecr.us-west-2.amazonaws.com/coding-agent:latest &lt;span class=&quot;se&quot;&gt;\&lt;/span&gt;
  &lt;span class=&quot;nt&quot;&gt;--push&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;⚠️ &lt;strong&gt;Gotcha&lt;/strong&gt;: Si usas &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker build&lt;/code&gt; normal sin buildx, la imagen resultante será amd64 aunque estés en una máquina ARM. AgentCore la rechazará con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Architecture incompatible&lt;/code&gt;. En mi experiencia, cuando la cross-compilation desde x86 no producía una imagen ARM válida, usar el driver &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker-container&lt;/code&gt; explícito (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--driver docker-container&lt;/code&gt;) lo resolvió — pero la documentación oficial solo requiere &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker buildx&lt;/code&gt; sin especificar driver. Si tienes problemas con la arquitectura, ese es el primer ajuste a probar.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Dockerfile&lt;/code&gt; necesita Python para el agente y Node.js porque el agente crea proyectos Node:&lt;/p&gt;

&lt;div class=&quot;language-dockerfile highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;FROM&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; python:3.12-slim&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;WORKDIR&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; /app&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;RUN &lt;/span&gt;apt-get update &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; apt-get &lt;span class=&quot;nb&quot;&gt;install&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-y&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--no-install-recommends&lt;/span&gt; &lt;span class=&quot;se&quot;&gt;\
&lt;/span&gt;    git curl &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;rm&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-rf&lt;/span&gt; /var/lib/apt/lists/&lt;span class=&quot;k&quot;&gt;*&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;RUN &lt;/span&gt;curl &lt;span class=&quot;nt&quot;&gt;-fsSL&lt;/span&gt; https://deb.nodesource.com/setup_20.x | bash - &lt;span class=&quot;se&quot;&gt;\
&lt;/span&gt;    &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; apt-get &lt;span class=&quot;nb&quot;&gt;install&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-y&lt;/span&gt; nodejs &lt;span class=&quot;se&quot;&gt;\
&lt;/span&gt;    &lt;span class=&quot;o&quot;&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;rm&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-rf&lt;/span&gt; /var/lib/apt/lists/&lt;span class=&quot;k&quot;&gt;*&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;COPY&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; requirements.txt .&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;RUN &lt;/span&gt;pip &lt;span class=&quot;nb&quot;&gt;install&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;--no-cache-dir&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-r&lt;/span&gt; requirements.txt

&lt;span class=&quot;k&quot;&gt;COPY&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; coding_agent.py .&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;RUN &lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;mkdir&lt;/span&gt; &lt;span class=&quot;nt&quot;&gt;-p&lt;/span&gt; /mnt/workspace

&lt;span class=&quot;k&quot;&gt;EXPOSE&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; 8080&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;CMD&lt;/span&gt;&lt;span class=&quot;s&quot;&gt; [&quot;python&quot;, &quot;coding_agent.py&quot;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Y el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;requirements.txt&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;strands-agents
strands-agents-tools
bedrock-agentcore
boto3
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;el-agente&quot;&gt;El Agente&lt;/h3&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strands&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Agent&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strands.session&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;FileSessionManager&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strands.models&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BedrockModel&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;strands_tools&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file_read&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file_write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;shell&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bedrock_agentcore.runtime&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;BedrockAgentCoreApp&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Habilita herramientas sin confirmación interactiva
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;environ&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;BYPASS_TOOL_CONSENT&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;app&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;BedrockAgentCoreApp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# El workspace persiste entre sesiones gracias a Session Storage
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;WORKSPACE&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;/mnt/workspace&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;BedrockModel&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;model_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us.anthropic.claude-sonnet-4-20250514-v1:0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;tools&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;file_read&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;file_write&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;shell&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;

&lt;span class=&quot;nd&quot;&gt;@app.entrypoint&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;handle_request&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;session_id&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;session_id&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;default&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;c1&quot;&gt;# El historial de conversación también persiste en el workspace
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# — mismo directorio, sin costo adicional
&lt;/span&gt;    &lt;span class=&quot;n&quot;&gt;session_manager&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;FileSessionManager&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;session_id&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;storage_dir&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;WORKSPACE&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;/.sessions&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;agent&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nc&quot;&gt;Agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;session_manager&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;session_manager&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;system_prompt&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Eres un coding assistant. &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Los archivos del proyecto están en /mnt/workspace. &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Cuando retomes una sesión, primero revisa qué hay en el workspace &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;antes de asumir que debes empezar desde cero.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;agent&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;message&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;__main__&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;app&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;run&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Observa el punto de diseño en el &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;system_prompt&lt;/code&gt;: le indicamos al agente que revise el workspace antes de actuar. Sin esto, el agente podría no “notar” que hay archivos existentes y proponer empezar de nuevo. La persistencia de filesystem es transparente para el runtime, pero el agente necesita saber que debe buscarla.&lt;/p&gt;

&lt;p&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FileSessionManager&lt;/code&gt; guarda el historial de conversación en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/mnt/workspace/.sessions/&lt;/code&gt; — el mismo directorio que persiste. Esto significa que el agente también recuerda &lt;em&gt;qué prometió hacer&lt;/em&gt; en la sesión anterior, no solo los archivos que creó.&lt;/p&gt;

&lt;h3 id=&quot;configurar-el-agent-runtime-con-session-storage&quot;&gt;Configurar el Agent Runtime con Session Storage&lt;/h3&gt;

&lt;p&gt;Al crear el agent runtime, agrega &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;filesystemConfigurations&lt;/code&gt; con un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sessionStorage&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# deploy.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;argparse&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;REGION&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us-west-2&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;ACCOUNT_ID&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;TU_CUENTA&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;RUNTIME_NAME&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;coding_agent&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;ROLE_ARN&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;arn:aws:iam::&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ACCOUNT_ID&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;:role/AgentExecutionRole&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;CONTAINER_URI&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ACCOUNT_ID&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;.dkr.ecr.&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;REGION&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;.amazonaws.com/coding-agent:latest&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;client&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore-control&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;region_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;REGION&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;


&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;create_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;create_agent_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;agentRuntimeName&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;RUNTIME_NAME&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;roleArn&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ROLE_ARN&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;agentRuntimeArtifact&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;containerConfiguration&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;containerUri&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;CONTAINER_URI&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;networkConfiguration&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;networkMode&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;PUBLIC&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# Requerido si tu agente necesita acceso a internet (Bedrock, npm, pip)
&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;filesystemConfigurations&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;sessionStorage&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;mountPath&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;/mnt/workspace&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;arn&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;agentRuntimeArn&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# AWS agrega un sufijo aleatorio al nombre: coding_agent-XXXXXXXXXX
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# Consulta el ARN completo con:
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;#   aws bedrock-agentcore-control list-agent-runtimes
&lt;/span&gt;    &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;✅ Agent Runtime creado: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;arn&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;arn&lt;/span&gt;


&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;update_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;runtime_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Agrega session storage a un runtime existente.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;update_agent_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;agentRuntimeId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;runtime_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;filesystemConfigurations&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;sessionStorage&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;mountPath&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;/mnt/workspace&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;✅ Session Storage agregado al runtime &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;runtime_id&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;


&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;__name__&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;__main__&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;parser&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;argparse&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nc&quot;&gt;ArgumentParser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;parser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;add_argument&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;--create&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;action&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;store_true&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;parser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;add_argument&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;--update&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;metavar&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;RUNTIME_ID&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;args&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;parser&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;parse_args&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;args&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;create&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;nf&quot;&gt;create_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;elif&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;args&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;update&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;nf&quot;&gt;update_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;args&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;update&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Uso: python deploy.py --create | --update RUNTIME_ID&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Dos detalles que vale la pena conocer:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;networkConfiguration&lt;/code&gt; con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;networkMode: &quot;PUBLIC&quot;&lt;/code&gt; es necesario si tu agente necesita acceso a internet — para llamar a Bedrock, descargar paquetes npm o pip, etc. No es un parámetro obligatorio de la API si tu agente opera en VPC sin necesidad de salida a internet.&lt;/li&gt;
  &lt;li&gt;AWS agrega un sufijo aleatorio al nombre que diste — el ARN real del runtime tiene formato &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;coding_agent-XXXXXXXXXX&lt;/code&gt;. Consúltalo con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws bedrock-agentcore-control list-agent-runtimes&lt;/code&gt; después del deploy.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Si ya tienes un runtime existente, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;update_agent_runtime&lt;/code&gt; acepta el mismo parámetro &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;filesystemConfigurations&lt;/code&gt; para agregarlo sin recrear el runtime.&lt;/p&gt;

&lt;h3 id=&quot;el-ciclo-stopresume-en-acción&quot;&gt;El Ciclo Stop/Resume en Acción&lt;/h3&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# client.py
&lt;/span&gt;&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;botocore.config&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;REGION&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;us-west-2&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# AWS agrega sufijo automático al nombre dado en create_agent_runtime.
# Consulta el ARN exacto con: aws bedrock-agentcore-control list-agent-runtimes
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AGENT_ARN&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;os&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;environ&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;AGENT_ARN&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;arn:aws:bedrock-agentcore:us-west-2:TU_CUENTA:runtime/coding_agent-XXXXXXXXXX&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# Mismo sessionId en todas las invocaciones = mismo filesystem persistente.
# Mínimo 33 caracteres — AgentCore lo valida en el cliente.
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SESSION_ID&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;proyecto-api-rest-001-session-demo-01&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# read_timeout=300 es necesario: npm install y operaciones largas
# superan fácilmente el default de 60 segundos de boto3.
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;client&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;boto3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-agentcore&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;region_name&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;REGION&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;config&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;nc&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;read_timeout&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;300&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;


&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;invoke&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;conv_id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;conv-001&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;invoke_agent_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;agentRuntimeArn&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AGENT_ARN&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;runtimeSessionId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SESSION_ID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;payload&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;session_id&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;conv_id&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}).&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;encode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;b&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;join&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]))&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;


&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;stop_session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;⏹  Deteniendo sesión &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SESSION_ID&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;client&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;stop_runtime_session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;agentRuntimeArn&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;AGENT_ARN&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;runtimeSessionId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SESSION_ID&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# La documentación oficial recomienda explícitamente esperar que StopRuntimeSession
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# complete antes de retomar la sesión — garantiza que el flush al storage durable
&lt;/span&gt;    &lt;span class=&quot;c1&quot;&gt;# termine. En producción, implementa un poll del estado de sesión en lugar de un sleep fijo.
&lt;/span&gt;    &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;⏳ Esperando flush al storage durable...&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;time&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;sleep&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;15&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;✅ Sesión detenida. Filesystem persistido.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;


&lt;span class=&quot;c1&quot;&gt;# --- Primera invocación ---
&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;invoke&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Crea un proyecto Node.js en /mnt/workspace/api. &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Inicializa con npm (nombre: &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;rest-api&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;, versión &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;1.0.0&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;), &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;instala express y dotenv, y crea index.js con un &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;endpoint GET /health que retorne {status: &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;ok&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;, timestamp: Date.now()}.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# --- Detener la sesión ---
&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;stop_session&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# --- Segunda invocación con el mismo sessionId ---
# El agente retoma con filesystem y conversación intactos
&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;print&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;invoke&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Agrega un endpoint POST /echo que retorne el body recibido &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;como JSON. Revisa primero qué existe en el workspace.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;En mis pruebas, la segunda invocación retomó exactamente donde quedó: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;node_modules&lt;/code&gt; intacto, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;package.json&lt;/code&gt; con las dependencias ya definidas, y el historial de conversación que le permitió al agente entender qué había creado antes.&lt;/p&gt;

&lt;h2 id=&quot;lo-que-el-filesystem-soporta-y-lo-que-no&quot;&gt;Lo Que el Filesystem Soporta (y lo que no)&lt;/h2&gt;

&lt;p&gt;Session Storage implementa un filesystem Linux estándar en el mount path. Operaciones comunes que funcionan sin modificación:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nb&quot;&gt;ls&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;cat&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;mkdir&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;touch&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;mv&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;cp&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;rm
&lt;/span&gt;git init / git add / git commit
npm &lt;span class=&quot;nb&quot;&gt;install&lt;/span&gt; / pip &lt;span class=&quot;nb&quot;&gt;install&lt;/span&gt; / cargo build
&lt;span class=&quot;nb&quot;&gt;chmod&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;chown&lt;/span&gt;, &lt;span class=&quot;nb&quot;&gt;stat&lt;/span&gt;, readdir
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Las operaciones POSIX estándar funcionan. Hay cuatro excepciones documentadas que vale la pena conocer antes de diseñar tu agente:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Hard links&lt;/strong&gt; — No soportados. Usa symlinks si los necesitas. La mayoría de herramientas de desarrollo no los usan directamente.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Device files, FIFOs, UNIX sockets&lt;/strong&gt; — &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;mknod&lt;/code&gt; no está soportado. Afecta casos muy específicos (servidores Unix socket, etc.).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Extended attributes (xattr)&lt;/strong&gt; — Herramientas que dependen de metadatos xattr no funcionarán.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;fallocate&lt;/strong&gt; — Preallocación de archivos sparse no soportada. Herramientas que la usan explícitamente fallarán; las que simplemente escriben archivos, no.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;File locking entre sesiones&lt;/strong&gt; — Los advisory locks funcionan dentro de una sesión activa, pero no persisten entre stop/resume. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;git&lt;/code&gt; no se ve afectado porque no depende de locks persistentes.&lt;/p&gt;

&lt;p&gt;Un detalle de comportamiento: los permisos (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;chmod&lt;/code&gt;) se almacenan correctamente y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stat&lt;/code&gt; los reporta bien, pero el enforcement no aplica dentro de la sesión porque el agente corre como único usuario en el microVM. No afecta el comportamiento de herramientas estándar, pero es algo a considerar si tu agente crea archivos con permisos específicos esperando que se respeten.&lt;/p&gt;

&lt;h2 id=&quot;cuándo-usar-session-storage-y-cuándo-no&quot;&gt;Cuándo Usar Session Storage (y Cuándo No)&lt;/h2&gt;

&lt;p&gt;La pregunta que más me hicieron cuando lo compartí con el equipo: “¿esto reemplaza a EFS?”&lt;/p&gt;

&lt;p&gt;No exactamente. Aquí está la comparativa honesta:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Criterio&lt;/th&gt;
      &lt;th&gt;Session Storage&lt;/th&gt;
      &lt;th&gt;EFS propio&lt;/th&gt;
      &lt;th&gt;S3 manual&lt;/th&gt;
      &lt;th&gt;Sin persistencia&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Configuración&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;1 parámetro en el deploy&lt;/td&gt;
      &lt;td&gt;VPC + mount target + sg&lt;/td&gt;
      &lt;td&gt;Código de sync&lt;/td&gt;
      &lt;td&gt;Ninguna&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Aislamiento&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Por sesión, automático&lt;/td&gt;
      &lt;td&gt;Manual (tu lógica)&lt;/td&gt;
      &lt;td&gt;Manual (tu lógica)&lt;/td&gt;
      &lt;td&gt;N/A&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Límite de duración&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;14 días sin invocación&lt;/td&gt;
      &lt;td&gt;Mientras exista el EFS&lt;/td&gt;
      &lt;td&gt;Mientras exista el bucket&lt;/td&gt;
      &lt;td&gt;0 (ephemeral)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Efecto de deploy&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Resetea filesystem&lt;/td&gt;
      &lt;td&gt;No afecta&lt;/td&gt;
      &lt;td&gt;Depende de tu lógica&lt;/td&gt;
      &lt;td&gt;N/A&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Costo&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;Preview — pricing por confirmar&lt;/td&gt;
      &lt;td&gt;EFS + datos transferidos&lt;/td&gt;
      &lt;td&gt;S3 por operación&lt;/td&gt;
      &lt;td&gt;Ninguno&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;strong&gt;Multi-sesión compartido&lt;/strong&gt;&lt;/td&gt;
      &lt;td&gt;No (aislado por sesión)&lt;/td&gt;
      &lt;td&gt;Sí, posible&lt;/td&gt;
      &lt;td&gt;Sí, posible&lt;/td&gt;
      &lt;td&gt;N/A&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (agosto 2026)&lt;/strong&gt;: Session Storage &lt;strong&gt;sigue en public preview&lt;/strong&gt;, así que la fila de costo se mantiene tal cual. Pero las columnas “EFS propio” y “S3 manual” envejecieron: en &lt;strong&gt;mayo de 2026 AgentCore Runtime añadió Bring-Your-Own File System&lt;/strong&gt;, y hoy puedes adjuntar access points de Amazon S3 Files y Amazon EFS directamente al runtime. AgentCore los monta en cada sesión en la ruta que indiques, sin código de montaje, sin contenedores privilegiados y sin orquestar descargas — hasta cinco mounts combinados en un mismo runtime. Eso cambia la decisión: si necesitabas storage &lt;strong&gt;compartido entre sesiones o entre agentes&lt;/strong&gt;, ya no tienes que elegir entre Session Storage y armarte el EFS a mano; montas EFS de forma gestionada y listo. La regla práctica hoy: Session Storage para estado aislado por sesión, S3 Files para sincronización de ida y vuelta con un bucket, EFS para storage compartido de baja latencia. Está disponible en las quince regiones donde corre AgentCore Runtime. Ver &lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html&quot; target=&quot;_blank&quot;&gt;File system configurations&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;&lt;strong&gt;Usa Session Storage cuando:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;Tu agente trabaja con proyectos de código que se extienden en múltiples sesiones&lt;/li&gt;
  &lt;li&gt;Necesitas persistencia operacional sin overhead de configuración&lt;/li&gt;
  &lt;li&gt;Cada sesión es independiente y no necesita compartir storage con otras&lt;/li&gt;
  &lt;li&gt;Quieres que el estado del filesystem sobreviva reinicios sin escribir código de checkpoint&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Considera alternativas cuando:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
  &lt;li&gt;Múltiples sesiones del mismo agente necesitan acceso al mismo filesystem compartido (EFS)&lt;/li&gt;
  &lt;li&gt;Tu caso requiere más de 14 días de inactividad sin reset (EFS o S3)&lt;/li&gt;
  &lt;li&gt;Haces deploys frecuentes de tu agent runtime y el reset de filesystem es problemático&lt;/li&gt;
  &lt;li&gt;Tienes requisitos específicos de compliance sobre dónde se almacenan los datos&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;lo-que-aprendí-probándolo&quot;&gt;Lo Que Aprendí Probándolo&lt;/h2&gt;

&lt;p&gt;Algunas observaciones del mundo real que no están en la documentación oficial:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;system_prompt&lt;/code&gt; importa tanto como la configuración.&lt;/strong&gt; Session Storage es transparente para el runtime, pero el LLM necesita contexto para “notar” que hay trabajo previo. Sin indicarle que revise el workspace antes de actuar, el agente puede proponer empezar de nuevo aunque los archivos estén ahí.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;FileSessionManager&lt;/code&gt; de Strands es el complemento natural.&lt;/strong&gt; Guardar el historial de conversación en el mismo &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/mnt/workspace&lt;/code&gt; es elegante: un solo mecanismo de persistencia para estado operacional y contexto conversacional.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Espera explícita después del stop no es opcional.&lt;/strong&gt; La documentación oficial es explícita: &lt;em&gt;“always wait for [StopRuntimeSession] to complete before resuming the session”&lt;/em&gt;. En mis pruebas, retomar sin esperar resultó en errores 500 del runtime. Un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;time.sleep(15)&lt;/code&gt; mínimo funcionó de forma consistente, pero en producción implementa un poll del estado de sesión en lugar de un sleep fijo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;read_timeout&lt;/code&gt; de boto3 te va a morder.&lt;/strong&gt; El default es 60 segundos. Un coding agent que ejecuta &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;npm install&lt;/code&gt; o &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;pip install&lt;/code&gt; supera ese límite fácilmente y recibes un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ReadTimeoutError&lt;/code&gt; que parece un error del runtime pero es del cliente. Configura &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Config(read_timeout=300)&lt;/code&gt; en el cliente de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-agentcore&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;ARM64 es el único formato soportado.&lt;/strong&gt; &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker build&lt;/code&gt; normal en una máquina x86 produce una imagen amd64 que AgentCore rechaza con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Architecture incompatible&lt;/code&gt;. Usa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;docker buildx --platform linux/arm64&lt;/code&gt;. Si tienes problemas con la arquitectura resultante al hacer cross-compilation desde x86, agregar el driver explícito &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;--driver docker-container&lt;/code&gt; al crear el builder fue lo que resolvió el problema en mi caso.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;runtimeSessionId&lt;/code&gt; requiere mínimo 33 caracteres.&lt;/strong&gt; El código de ejemplo oficial lo documenta con un comentario inline: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;# Must be 33+ chars&lt;/code&gt;. Un ID corto fallará al invocar el agente.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;AWS agrega un sufijo aleatorio al nombre del runtime.&lt;/strong&gt; El ARN real tiene formato &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;coding_agent-XXXXXXXXXX&lt;/code&gt;. Consúltalo con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;aws bedrock-agentcore-control list-agent-runtimes&lt;/code&gt; después del deploy.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El efecto del deploy en filesystems activos.&lt;/strong&gt; Actualizar la versión del agent runtime resetea el filesystem de todas las sesiones activas. Si tienes sesiones de trabajo largo en vuelo, un deploy las interrumpe. Considera esto en tu estrategia de release.&lt;/p&gt;

&lt;h2 id=&quot;la-imagen-completa-las-tres-capas-de-estado-de-un-agente&quot;&gt;La Imagen Completa: Las Tres Capas de Estado de un Agente&lt;/h2&gt;

&lt;p&gt;Con este artículo, la serie ha cubierto las tres capas de estado que un agente de producción en AgentCore puede manejar:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/bedrock-policy.html&quot; target=&quot;_blank&quot;&gt;AgentCore Policy&lt;/a&gt;&lt;/strong&gt; — Lo que el agente &lt;em&gt;puede&lt;/em&gt; hacer. Límites determinísticos.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;&lt;a href=&quot;/agentcore-memory-episodic.html&quot; target=&quot;_blank&quot;&gt;AgentCore Memory Episódica&lt;/a&gt;&lt;/strong&gt; — Lo que el agente &lt;em&gt;aprendió&lt;/em&gt;. Experiencias y patrones.&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;AgentCore Session Storage&lt;/strong&gt; — Lo que el agente &lt;em&gt;construyó&lt;/em&gt;. Estado operacional del filesystem.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Ninguna reemplaza a la otra. Un coding agent de producción serio puede beneficiarse de las tres al mismo tiempo: Policy para limitar qué comandos puede ejecutar, Memory Episódica para aprender de patrones de código o errores pasados, y Session Storage para mantener el workspace entre sesiones.&lt;/p&gt;

&lt;p&gt;La combinación hace que “agente que trabaja en proyectos reales” sea un caso de uso viable, no solo una demo de re:Invent.&lt;/p&gt;

&lt;hr /&gt;

&lt;p&gt;¿Estás construyendo coding agents o agentes de análisis de larga duración en AWS? ¿Cuál ha sido tu mayor reto con la persistencia de estado? Me interesa saber qué están enfrentando — los comentarios están abiertos.&lt;/p&gt;

&lt;p&gt;¡Hasta el próximo artículo! 🚀&lt;/p&gt;

&lt;hr /&gt;

&lt;p&gt;&lt;em&gt;¿Te fue útil este artículo? Compártelo con tu equipo. Probablemente también tienen un agente que “olvida” todo cada vez que se reinicia.&lt;/em&gt;&lt;/p&gt;

&lt;hr /&gt;

&lt;h2 id=&quot;recursos-oficiales-&quot;&gt;Recursos Oficiales 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-persistent-filesystems.html&quot; target=&quot;_blank&quot;&gt;Documentación oficial: Session Storage en AgentCore Runtime&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html&quot; target=&quot;_blank&quot;&gt;API Reference: CreateAgentRuntime&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_UpdateAgentRuntime.html&quot; target=&quot;_blank&quot;&gt;API Reference: UpdateAgentRuntime&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://strandsagents.com/latest/&quot; target=&quot;_blank&quot;&gt;Strands Agents: FileSessionManager&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/bedrock-agentcore-limits.html#session-storage-limits&quot; target=&quot;_blank&quot;&gt;Límites de Session Storage&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
</description>
                <pubDate>Fri, 10 Apr 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/agentcore-session-storage.html</link>
                <guid isPermaLink="true">https://gerardo.dev/agentcore-session-storage.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>AgentCore</category>
                
                <category>Runtime</category>
                
                <category>GenAI</category>
                
                <category>Agents</category>
                
                <category>Strands</category>
                
                
            </item>
        
            <item>
                <title>Bedrock Structured Outputs: Del Ruego al Contrato</title>
                <description>&lt;p&gt;Tenía un sistema funcionando. Un agente que procesaba el RSS feed de AWS varias veces por día, filtraba las noticias relevantes con Claude y generaba posts para LinkedIn y X. Lo había construido, desplegado, y monitoreaba sus logs con cierta satisfacción.&lt;/p&gt;

&lt;p&gt;Y sin embargo, había algo que no me gustaba cada vez que abría el código: tres métodos cuyo único propósito era desconfiar del LLM.&lt;/p&gt;

&lt;p&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_extract_json_from_text&lt;/code&gt;. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_validate_analysis_structure&lt;/code&gt;. &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_create_fallback_analysis&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Juntos sumaban más de 130 líneas. Todo ese código existía para manejar una sola posibilidad: que el modelo respondiera algo distinto a lo que le había pedido. Que incluyera una disculpa antes del JSON. Que olvidara un campo. Que formateara mal el output.&lt;/p&gt;

&lt;p&gt;Cuando Amazon anunció Bedrock Structured Outputs, entendí inmediatamente qué era lo que había estado haciendo mal. No era un problema de prompting. Era un problema de arquitectura: había estado &lt;em&gt;pidiéndole&lt;/em&gt; al modelo que fuera consistente, cuando lo que necesitaba era &lt;em&gt;garantizarlo&lt;/em&gt;.&lt;/p&gt;

&lt;h2 id=&quot;el-sistema-agente-de-noticias-aws-️&quot;&gt;El Sistema: Agente de Noticias AWS 🗞️&lt;/h2&gt;

&lt;p&gt;Antes de entrar en materia, contexto del sistema. El agente procesa el RSS de AWS varias veces por día con tres responsabilidades:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;&lt;strong&gt;Analizar relevancia&lt;/strong&gt; de cada noticia (score 0-10 y metadatos para la audiencia técnica)&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Generar contenido social&lt;/strong&gt; — un post de LinkedIn y uno de X por noticia relevante&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Componer el newsletter&lt;/strong&gt; semanal, incluyendo subject y preview text del email&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Todo corre en Lambda, usa DynamoDB para estado, y Bedrock con el API &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;converse&lt;/code&gt; para las interacciones con Claude.&lt;/p&gt;

&lt;p&gt;El sistema funcionaba. El problema era la cantidad de código defensivo necesario para confiar en sus outputs.&lt;/p&gt;

&lt;h2 id=&quot;el-problema-pedir-vs-garantizar&quot;&gt;El Problema: Pedir vs. Garantizar&lt;/h2&gt;

&lt;p&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;content_analyzer.py&lt;/code&gt; tenía este system prompt:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Antes — instrucciones de formato en lenguaje natural
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;system_prompts&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Eres un experto analista de noticias de AWS...&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;FORMATO DE RESPUESTA OBLIGATORIO:&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Debes responder ÚNICAMENTE con un objeto JSON válido. &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;No incluyas explicaciones, comentarios o texto adicional.&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;ESTRUCTURA JSON REQUERIDA:&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;  &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;relevance&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: 7,&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;  &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;analysis&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: {&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;    &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;article&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: true,&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;    &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;keyPoints&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: [&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Punto clave 1&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;, &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Punto clave 2&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;    &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;emojis&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: [&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;🚀&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;, &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;☁️&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;    &lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;relevance&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: 7&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;  }&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;IMPORTANTE: Responde SOLO con el JSON. &lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;No agregues texto antes o después.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Ese bloque es una oración en lenguaje natural que le ruega al modelo que sea consistente. El modelo generalmente lo era. Pero “generalmente” no es suficiente para producción.&lt;/p&gt;

&lt;p&gt;La consecuencia directa era este código:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Antes — extracción defensiva de JSON
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;output_message&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;output&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;message&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# ¿El modelo puso texto antes del JSON? A buscar manualmente.
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;not&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;cleaned_output&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;startswith&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;start_idx&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;cleaned_output&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;find&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;end_idx&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;cleaned_output&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;rfind&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;start_idx&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;and&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;end_idx&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;cleaned_output&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;cleaned_output&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;start_idx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;end_idx&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;c1&quot;&gt;# Sin JSON → reintento
&lt;/span&gt;        &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;

&lt;span class=&quot;c1&quot;&gt;# ¿El JSON es parseable?
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;try&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;analysis&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;cleaned_output&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# ¿Tiene todos los campos?
&lt;/span&gt;    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;_validate_analysis_structure&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;analysis&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;news&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;news_id&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;analysis&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;else&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# reintento
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;except&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;JSONDecodeError&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# reintento
&lt;/span&gt;
&lt;span class=&quot;c1&quot;&gt;# Todos los intentos fallaron → fallback por palabras clave
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;_create_fallback_analysis&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;news&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Y encima de eso, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_validate_analysis_structure&lt;/code&gt; (45 líneas) verificando tipos y campos, y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_create_fallback_analysis&lt;/code&gt; (65 líneas) haciendo análisis por palabras clave cuando el modelo fallaba.&lt;/p&gt;

&lt;p&gt;En total: &lt;strong&gt;~130 líneas de código cuya única función era manejar la inconsistencia del modelo&lt;/strong&gt;.&lt;/p&gt;

&lt;h2 id=&quot;bedrock-structured-outputs-qué-es-y-cómo-funciona-&quot;&gt;Bedrock Structured Outputs: Qué Es y Cómo Funciona 🔧&lt;/h2&gt;

&lt;p&gt;Bedrock Structured Outputs es una feature que garantiza que la respuesta del modelo sea un JSON válido que cumple exactamente con un schema que tú defines (&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/structured-output.html&quot; target=&quot;_blank&quot;&gt;JSON Schema Draft 2020-12&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;La palabra importante es &lt;strong&gt;garantiza&lt;/strong&gt;. No “el modelo intentará”. No “usualmente produce”. Garantiza.&lt;/p&gt;

&lt;p&gt;La implementación es un parámetro adicional en el request al API &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;converse&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;bedrock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;converse&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;modelId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;BEDROCK_MODEL_ID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;messages&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;messages&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;system&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;system_prompts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;inferenceConfig&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;inference_config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;outputConfig&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;                          &lt;span class=&quot;c1&quot;&gt;# ← este es el cambio
&lt;/span&gt;        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;textFormat&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;json_schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;structure&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;jsonSchema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;MY_SCHEMA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;# schema serializado
&lt;/span&gt;                    &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;schema_name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Descripción del schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Bedrock compila el schema en una gramática y garantiza que la respuesta cumpla el contrato — no es validación post-generación, sino cumplimiento durante la generación.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🧠 &lt;strong&gt;Cómo funciona internamente&lt;/strong&gt;: Bedrock valida el schema contra 
JSON Schema Draft 2020-12, compila una gramática (puede tomar unos 
minutos la primera vez), y la cachea por 24 horas cifrada con claves 
AWS-managed. Requests subsiguientes con el mismo schema tienen latencia 
comparable a llamadas estándar.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h3 id=&quot;modelos-soportados&quot;&gt;Modelos Soportados&lt;/h3&gt;

&lt;p&gt;Un punto importante que me costó un rato en descubrir: &lt;strong&gt;Amazon Nova no soporta Structured Outputs&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Los modelos compatibles a marzo 2026 incluyen:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;Anthropic&lt;/strong&gt;: Claude Haiku 4.5, Sonnet 4.5, Opus 4.5, Opus 4.6&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Qwen&lt;/strong&gt;: Qwen3 series (235B, 32B, Coder)&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;DeepSeek&lt;/strong&gt;: DeepSeek-V3.1&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Google&lt;/strong&gt;: Gemma 3 (12B, 27B)&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;Mistral AI&lt;/strong&gt;: Mistral Large 3, Magistral Small&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;NVIDIA&lt;/strong&gt;: Nemotron Nano series&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;No soportados&lt;/strong&gt;: Amazon Nova (todas las versiones), Amazon Titan.&lt;/p&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (septiembre 2026)&lt;/strong&gt;: La lista de providers creció desde marzo. El &lt;a href=&quot;https://aws.amazon.com/blogs/machine-learning/structured-outputs-on-amazon-bedrock-schema-compliant-ai-responses/&quot; target=&quot;_blank&quot;&gt;blog oficial de Structured Outputs&lt;/a&gt; confirma disponibilidad general en todas las regiones comerciales para Anthropic, DeepSeek, Google, Mistral AI, NVIDIA, Qwen — y suma dos providers que no estaban en marzo: &lt;strong&gt;MiniMax&lt;/strong&gt; y &lt;strong&gt;Moonshot AI&lt;/strong&gt;, más soporte para modelos de &lt;strong&gt;OpenAI&lt;/strong&gt; en Bedrock. También se expandió a AWS GovCloud (US) en abril de 2026.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;blockquote class=&quot;q-left&quot;&gt;
  &lt;p&gt;🔄 &lt;strong&gt;Actualización (octubre 2026)&lt;/strong&gt;: El &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/10/claude-structured-outputs-bedrock/&quot; target=&quot;_blank&quot;&gt;20 de octubre AWS anunció&lt;/a&gt; structured outputs para &lt;strong&gt;todos los modelos Claude&lt;/strong&gt; en Bedrock: las familias Sonnet, Opus, Haiku, Fable y Mythos. Además de Converse, ahora funciona con InvokeModel, con la Anthropic Messages API en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-runtime&lt;/code&gt; y con la Messages API del endpoint &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-mantle&lt;/code&gt;. Lo detallo en la &lt;a href=&quot;#actualización-octubre-2026-invokemodel-mantle-y-strict-tool-use&quot;&gt;sección de actualización&lt;/a&gt; al final del artículo. El soporte exacto de endpoint y región varía por modelo: revisa su model card.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Mi sistema usaba &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;amazon.nova-2-lite&lt;/code&gt; para el análisis de relevancia — elegido originalmente por costo. Tuve que migrar a Claude Haiku 4.5 para usar la feature. En la práctica, el costo de Haiku 4.5 es comparable, y la calidad del análisis mejoró.&lt;/p&gt;

&lt;h2 id=&quot;la-migración-tres-transformaciones&quot;&gt;La Migración: Tres Transformaciones&lt;/h2&gt;

&lt;h3 id=&quot;1-análisis-de-relevancia--el-cambio-más-dramático&quot;&gt;1. Análisis de Relevancia — El Cambio Más Dramático&lt;/h3&gt;

&lt;p&gt;El schema define exactamente qué estructura debe devolver el modelo:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Schema de análisis — definido una vez, a nivel de módulo
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_ANALYSIS_SCHEMA&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;object&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;properties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;relevance&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;integer&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;analysis&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;object&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;properties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;article&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;   &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;boolean&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;keyPoints&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;array&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;items&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}},&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;emojis&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;array&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;items&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}},&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;relevance&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;integer&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;article&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;keyPoints&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;emojis&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;relevance&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;additionalProperties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# ← ningún campo extra posible
&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;relevance&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;analysis&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;additionalProperties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Con el schema definido, el método de análisis se simplifica radicalmente:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Después — sin parsing defensivo, sin fallbacks, sin validación manual
&lt;/span&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;_analyze_single_news_with_retry&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;news&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;system_prompts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;inference_config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;max_retries&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attempt&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;range&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;max_retries&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;try&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;n&quot;&gt;messages&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;role&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;user&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Título: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;news&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;title&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Descripción: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;news&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}]&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}]&lt;/span&gt;

            &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;bedrock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;converse&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;modelId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;BEDROCK_MODEL_ID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;messages&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;messages&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;system&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;system_prompts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;inferenceConfig&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;inference_config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;outputConfig&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;textFormat&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;json_schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;structure&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;jsonSchema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                                &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_ANALYSIS_SCHEMA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                                &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;news_analysis&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                                &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Análisis de relevancia de noticia AWS&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;
                            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
                        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

            &lt;span class=&quot;c1&quot;&gt;# El schema garantiza la estructura solo si la generación terminó:
&lt;/span&gt;            &lt;span class=&quot;c1&quot;&gt;# si se agotó maxTokens, el JSON llega truncado
&lt;/span&gt;            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;stopReason&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;max_tokens&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                &lt;span class=&quot;n&quot;&gt;logger&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;warning&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Respuesta truncada en intento &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;attempt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;

            &lt;span class=&quot;n&quot;&gt;output_message&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;output&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;message&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;

            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;not&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_message&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;or&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;not&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_message&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;strip&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;():&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;

            &lt;span class=&quot;c1&quot;&gt;# Con stopReason == &apos;end_turn&apos;, el JSON cumple el schema
&lt;/span&gt;            &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;output_message&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

        &lt;span class=&quot;k&quot;&gt;except&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;Exception&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;as&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# Solo errores de red o servicio, no de parsing
&lt;/span&gt;            &lt;span class=&quot;n&quot;&gt;logger&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;sa&quot;&gt;f&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Error en intento &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;attempt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;: &lt;/span&gt;&lt;span class=&quot;si&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;e&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;si&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;attempt&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;lt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;max_retries&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
                &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# Ya no hay fallback por palabras clave — si Bedrock falla, la noticia se omite
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El resultado: &lt;strong&gt;de ~90 líneas a ~30&lt;/strong&gt;. Y el system prompt también cambia — ya no necesita instrucciones de formato:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Después — solo criterios de negocio, sin instrucciones de formato JSON
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;system_prompts&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Eres un experto analista de noticias de AWS...&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;CRITERIOS DE RELEVANCIA (escala 0-10):&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;• 9-10: Bedrock, GenAI, servicios de IA, serverless core&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;• 7-8: RDS, Aurora, bases de datos, servicios de datos&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;CAMPOS A COMPLETAR:&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;• relevance: número entero del 0-10&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;• analysis.keyPoints: array de 2-3 strings con puntos clave&lt;/span&gt;&lt;span class=&quot;se&quot;&gt;\n&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;• analysis.emojis: array de 2-3 emojis relevantes&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;
            &lt;span class=&quot;c1&quot;&gt;# ← Sin mencionar JSON. Sin ejemplos de estructura.
&lt;/span&gt;            &lt;span class=&quot;c1&quot;&gt;# El schema en outputConfig ya define el contrato.
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Este cambio me pareció elegante: el prompt habla de negocio, el schema habla de estructura. Cada cosa en su lugar.&lt;/p&gt;

&lt;h3 id=&quot;2-generación-de-posts-sociales--de-2-llamadas-a-1&quot;&gt;2. Generación de Posts Sociales — De 2 Llamadas a 1&lt;/h3&gt;

&lt;p&gt;Antes, el sistema generaba el post de LinkedIn y el de X en llamadas separadas. La razón: sin structured outputs, mezclar dos outputs en un solo request aumentaba la probabilidad de que el modelo “se perdiera” en el formato.&lt;/p&gt;

&lt;p&gt;Con structured outputs, eso desaparece:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;c1&quot;&gt;# Schema para generación simultánea de ambos posts
&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_SOCIAL_CONTENT_SCHEMA&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;object&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;properties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;linkedin_post&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;X_post&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;  &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;linkedin_post&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;X_post&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;additionalProperties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;_generate_social_posts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;news&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Una sola llamada genera LinkedIn + X garantizados.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# ... construcción del prompt con contexto de la noticia ...
&lt;/span&gt;    
    &lt;span class=&quot;n&quot;&gt;response_text&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;_invoke_bedrock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_schema&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_SOCIAL_CONTENT_SCHEMA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;response_text&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;c1&quot;&gt;# → {&quot;linkedin_post&quot;: &quot;...&quot;, &quot;X_post&quot;: &quot;...&quot;}
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;El patrón que hace esto funcionar limpiamente es un &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_invoke_bedrock&lt;/code&gt; con schema opcional:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;_invoke_bedrock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_schema&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Invoca Bedrock. Con output_schema activa Structured Outputs.&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;converse_kwargs&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;modelId&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;SOCIAL_BEDROCK_MODEL_ID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;messages&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;role&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;user&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}]}],&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inferenceConfig&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;temperature&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;0.7&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;maxTokens&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;2000&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;output_schema&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;converse_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;outputConfig&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;textFormat&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;json_schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;structure&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;jsonSchema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;output_schema&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;structured_output&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                        &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Salida estructurada garantizada por Bedrock&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;
                    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;

    &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;bedrock&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;converse&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;**&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;converse_kwargs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;output&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;message&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;][&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Cuando &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;output_schema=None&lt;/code&gt;, el comportamiento es idéntico al anterior — útil para los casos donde el output es texto libre (como la generación de HTML para el newsletter).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Impacto en costos&lt;/strong&gt;: con ~90 ejecuciones/mes y ~10 noticias relevantes por ejecución, pasé de ~900 a ~450 llamadas mensuales para la generación de contenido social. La mitad.&lt;/p&gt;

&lt;h3 id=&quot;3-newsletter--funcionalidad-nueva-sin-código-extra&quot;&gt;3. Newsletter — Funcionalidad Nueva sin Código Extra&lt;/h3&gt;

&lt;p&gt;El &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;newsletter_generator.py&lt;/code&gt; tenía un método &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_generate_subject&lt;/code&gt; que devolvía el asunto del email como string. Bien.&lt;/p&gt;

&lt;p&gt;Pero había un campo que nunca había implementado: el &lt;strong&gt;preview text&lt;/strong&gt;, esos 80-100 caracteres que Gmail, Outlook y Apple Mail muestran bajo el asunto antes de abrir el correo. Una oportunidad de engagement desperdiciada.&lt;/p&gt;

&lt;p&gt;Agregar preview text antes hubiera requerido: una segunda llamada a Bedrock, o instrucciones más complejas en el prompt con el riesgo de que el modelo mezclara los dos campos.&lt;/p&gt;

&lt;p&gt;Con structured outputs fue directo:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;_SUBJECT_SCHEMA&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;object&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;properties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;subject&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;      &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# max 60 chars
&lt;/span&gt;        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;preview_text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;   &lt;span class=&quot;c1&quot;&gt;# 80-100 chars, complementa el subject
&lt;/span&gt;    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;subject&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;preview_text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;additionalProperties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Una llamada, dos campos garantizados. El newsletter ahora incluye &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;preview_text&lt;/code&gt; automáticamente — y el próximo paso es pasárselo a Mailchimp al crear la campaña para que aparezca en los clientes de email de los suscriptores.&lt;/p&gt;

&lt;h2 id=&quot;resultados-el-antes-y-el-después&quot;&gt;Resultados: El Antes y El Después&lt;/h2&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt; &lt;/th&gt;
      &lt;th&gt;Antes&lt;/th&gt;
      &lt;th&gt;Después&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Líneas de parsing defensivo&lt;/td&gt;
      &lt;td&gt;~130&lt;/td&gt;
      &lt;td&gt;1 (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;json.loads&lt;/code&gt;)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Llamadas Bedrock por noticia&lt;/td&gt;
      &lt;td&gt;2&lt;/td&gt;
      &lt;td&gt;1&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;JSONDecodeError&lt;/code&gt; posible&lt;/td&gt;
      &lt;td&gt;Sí&lt;/td&gt;
      &lt;td&gt;Solo si se trunca (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stopReason: max_tokens&lt;/code&gt;)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Métodos eliminados&lt;/td&gt;
      &lt;td&gt;—&lt;/td&gt;
      &lt;td&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_extract_json_from_text&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_validate_analysis_structure&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;_create_fallback_analysis&lt;/code&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Preview text en newsletter&lt;/td&gt;
      &lt;td&gt;No existía&lt;/td&gt;
      &lt;td&gt;Generado automáticamente&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Modelo de análisis&lt;/td&gt;
      &lt;td&gt;Nova 2 Lite&lt;/td&gt;
      &lt;td&gt;Claude Haiku 4.5&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;El cambio más importante no aparece en esa tabla: el &lt;strong&gt;modelo mental&lt;/strong&gt; con el que escribo prompts cambió. Ya no necesito pensar en cómo darle instrucciones al modelo para que sea consistente. Defino el contrato en código — JSON Schema — y el prompt puede enfocarse exclusivamente en el comportamiento de negocio.&lt;/p&gt;

&lt;h2 id=&quot;consideraciones-prácticas&quot;&gt;Consideraciones Prácticas&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;El schema no reemplaza el prompt, lo complementa.&lt;/strong&gt; El schema garantiza estructura; el prompt define comportamiento. Si el schema tiene &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;relevance&quot;: {&quot;type&quot;: &quot;integer&quot;}&lt;/code&gt; pero el prompt no explica qué escala usar, el modelo inventará una. Ambas piezas son necesarias.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;additionalProperties: False&lt;/code&gt; es importante.&lt;/strong&gt; Sin él, el modelo puede agregar campos extra que no esperabas. Con él, el contrato es exacto en ambas direcciones.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Incompatibilidad con Citations de Anthropic.&lt;/strong&gt; Si usas la feature de citations de Anthropic (para referenciar fragmentos de documentos), no puedes combinarla con Structured Outputs en el mismo request: Bedrock responde con un error 400. Elige uno u otro según el caso de uso.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Schema inválido → HTTP 400 inmediato.&lt;/strong&gt; Si el schema tiene errores de sintaxis, Bedrock retorna error en la llamada, no durante la generación. Útil para detectar problemas temprano.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Cache de 24 horas.&lt;/strong&gt; Bedrock guarda en cache la gramática compilada de cada schema por 24 horas (cifrado con claves AWS-managed). La primera vez que usas un schema la compilación puede tardar hasta unos minutos. Los requests siguientes con el mismo schema, desde la misma cuenta, tienen latencia comparable a una llamada estándar.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Revisa &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stopReason&lt;/code&gt; antes de parsear.&lt;/strong&gt; La garantía cubre una respuesta completa. Si la generación se corta por &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maxTokens&lt;/code&gt;, el JSON llega truncado y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;json.loads&lt;/code&gt; falla. Por eso el código de arriba descarta las respuestas con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stopReason == &apos;max_tokens&apos;&lt;/code&gt; — y si te pasa seguido, la solución es subir &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maxTokens&lt;/code&gt;, no reintentar.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;El schema no valida rangos ni longitudes.&lt;/strong&gt; &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;minimum&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maximum&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;multipleOf&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;minLength&lt;/code&gt; y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;maxLength&lt;/code&gt; no están soportados, igual que los schemas recursivos y los &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;$ref&lt;/code&gt; externos. En mi caso eso significa que la escala 0-10 de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;relevance&lt;/code&gt; y los “max 60 chars” del &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;subject&lt;/code&gt; no los impone el schema: viven en el prompt. Es la prueba más concreta de que el schema y el prompt se complementan.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Ojo con los inference profiles geográficos.&lt;/strong&gt; No todos los perfiles de cross-Region inference soportan structured outputs para todos los modelos. Por ejemplo, Claude Haiku 4.5 —el modelo que uso para el análisis— no lo soporta a través del perfil de India (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;in.anthropic&lt;/code&gt;). Revisa la &lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html&quot; target=&quot;_blank&quot;&gt;model card&lt;/a&gt; de tu modelo antes de elegir perfil.&lt;/p&gt;

&lt;h2 id=&quot;actualización-octubre-2026-invokemodel-mantle-y-strict-tool-use&quot;&gt;Actualización (octubre 2026): InvokeModel, Mantle y Strict Tool Use&lt;/h2&gt;

&lt;p&gt;Cuando escribí este artículo todo pasaba por Converse. Con el &lt;a href=&quot;https://aws.amazon.com/about-aws/whats-new/2026/10/claude-structured-outputs-bedrock/&quot; target=&quot;_blank&quot;&gt;anuncio de structured outputs para Claude&lt;/a&gt; hay dos cosas nuevas que vale la pena conocer.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;InvokeModel usa otro parámetro y otro formato.&lt;/strong&gt; Con InvokeModel envías el body nativo de Anthropic, y el schema va en &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;output_config.format&lt;/code&gt; como &lt;strong&gt;objeto&lt;/strong&gt;, no serializado como string:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;response&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;bedrock_runtime&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;invoke_model&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;modelId&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Config&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;BEDROCK_MODEL_ID&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;body&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;dumps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;anthropic_version&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;bedrock-2023-05-31&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;max_tokens&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;512&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;messages&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;role&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;user&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;prompt&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}],&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;output_config&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;format&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;json_schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;schema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;_ANALYSIS_SCHEMA&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# ← objeto, no json.dumps
&lt;/span&gt;        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;n&quot;&gt;body&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;response&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;body&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;].&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;read&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;())&lt;/span&gt;

&lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;body&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;stop_reason&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;end_turn&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;text&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;next&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;b&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;body&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;content&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;b&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;analysis&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nf&quot;&gt;loads&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;text&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Es una diferencia fácil de pasar por alto si migras entre APIs: en Converse, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;outputConfig.textFormat...jsonSchema.schema&lt;/code&gt; es un string JSON; en InvokeModel y en la Messages API de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bedrock-mantle&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;output_config.format.schema&lt;/code&gt; es el objeto directamente. Fíjate también en que la clave de parada es &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stop_reason&lt;/code&gt; en el body nativo y &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stopReason&lt;/code&gt; en Converse.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Strict tool use.&lt;/strong&gt; El segundo mecanismo no es un schema de respuesta sino un flag en la definición de la tool: con &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;&quot;strict&quot;: true&lt;/code&gt;, el nombre y los argumentos de cada tool call se validan contra el schema de entrada durante la generación. En Converse va dentro de &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;toolSpec&lt;/code&gt;:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;toolConfig&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;tools&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;
        &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;toolSpec&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;name&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;get_weather&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;description&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;Obtiene el clima actual de una ubicación&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;strict&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;True&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;  &lt;span class=&quot;c1&quot;&gt;# ← argumentos garantizados contra el schema
&lt;/span&gt;            &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;inputSchema&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;object&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;properties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;location&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
                    &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;unit&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;enum&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;celsius&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;fahrenheit&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]}&lt;/span&gt;
                &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;required&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;location&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;unit&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
                &lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;additionalProperties&lt;/span&gt;&lt;span class=&quot;sh&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;False&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;}}&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}]&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Mi agente de noticias no usa tools, así que no lo necesité. Pero para cualquier agente con function calling es el mismo argumento de este artículo aplicado a otra capa: en lugar de validar a mano los argumentos que el modelo le pasa a tu tool, los garantizas. Ambos mecanismos se pueden usar por separado o juntos en el mismo request.&lt;/p&gt;

&lt;h2 id=&quot;conclusión&quot;&gt;Conclusión&lt;/h2&gt;

&lt;p&gt;Hay una diferencia fundamental entre pedirle a un LLM que sea consistente y garantizar que lo sea. Durante meses escribí prompts cada vez más detallados, con ejemplos de estructura, con advertencias en mayúsculas. Y construí código defensivo para manejar los casos donde el modelo decidía no seguirlos.&lt;/p&gt;

&lt;p&gt;Bedrock Structured Outputs resuelve ese problema en la capa correcta. El schema vive en código, se versiona con el código, y se valida como código. El prompt puede hablar de negocio. Y el parsing defensivo desaparece porque ya no tiene razón de existir.&lt;/p&gt;

&lt;p&gt;La próxima vez que abras el archivo de un sistema que llama a Bedrock, pregúntate: ¿cuántas líneas de este código existen únicamente para desconfiar del modelo? Si la respuesta es más de diez, ya sabes qué hacer.&lt;/p&gt;

&lt;hr /&gt;
&lt;h2 id=&quot;recursos-&quot;&gt;Recursos 📚&lt;/h2&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/structured-output.html&quot; target=&quot;_blank&quot;&gt;Documentación oficial: Bedrock Structured Outputs&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-structured-outputs.html&quot; target=&quot;_blank&quot;&gt;Structured outputs para modelos Claude&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://docs.aws.amazon.com/bedrock/latest/userguide/model-cards.html&quot; target=&quot;_blank&quot;&gt;Model cards: soporte por modelo, endpoint y región&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href=&quot;https://json-schema.org/draft/2020-12/json-schema-core&quot; target=&quot;_blank&quot;&gt;JSON Schema Draft 2020-12&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;¿Ya tienes sistemas con parsing defensivo de JSON que podrían beneficiarse de esta migración? ¿O encontraste algún caso donde Structured Outputs no fue suficiente? Los comentarios están abiertos.&lt;/p&gt;
</description>
                <pubDate>Wed, 25 Mar 2026 08:00:00 -0600</pubDate>
                <link>https://gerardo.dev/bedrock-structured-outputs.html</link>
                <guid isPermaLink="true">https://gerardo.dev/bedrock-structured-outputs.html</guid>
                
                <category>AWS</category>
                
                <category>Bedrock</category>
                
                <category>Python</category>
                
                <category>Structured Outputs</category>
                
                <category>JSON Schema</category>
                
                <category>LLM</category>
                
                <category>Arquitectura</category>
                
                
            </item>
        
    </channel>
</rss>