Agente de Contenido con Strands y Bedrock

¿Qué es?

Un sistema de tres agentes de IA que automatiza el ciclo de vida completo de contenido en una base de conocimiento bilingüe (español/inglés). Los agentes corren en GitHub Actions, usan Strands Agents como framework de orquestación y Claude Sonnet 4 en Amazon Bedrock como modelo de lenguaje.

El sistema implementa un bucle de retroalimentación continuo: un agente QA audita el contenido y abre issues → un agente de corrección aplica fixes quirúrgicos → un agente de contenido genera upgrades completos → un humano revisa y aprueba los PRs.

Arquitectura del sistema

Los tres agentes

QA Agent — auditor determinístico

El agente QA (agents/qa_agent.py) ejecuta verificaciones estructurales sin LLM y opcionalmente una revisión profunda con Claude. No modifica archivos — solo abre issues.

Verificaciones estructurales (sin LLM, sin costo):

• Conteo de palabras (700+ para conceptos evergreen)
• Conteo de referencias (5+) y diversidad de tiers (2+)
• Cross-references (3+) y cross-refs rotos
• Secciones requeridas (¿Por qué importa?)
• Accesibilidad en diagramas mermaid (accTitle, accDescr)
• Encabezados en inglés dentro de archivos en español
• Links externos que deberían ser internos (/concepts/slug)
• Stubs placeholder en archivos .en.mdx

Revisión profunda (--deep, usa Bedrock):

• Texto de relleno (frases genéricas intercambiables)
• Afirmaciones sin fuente (estadísticas, precios, fechas)
• Secciones débiles que repiten la definición
• «¿Por qué importa?» genérico sin tradeoffs específicos
• Pseudocódigo en lugar de ejemplos ejecutables
• Tablas comparativas con categorías abstractas

# Ejecución local
python -m agents.qa_agent --dry-run --status evergreen    # auditoría sin crear issues
python -m agents.qa_agent --deep --slug serverless        # revisión LLM de un concepto
python -m agents.qa_agent --discover                      # matriz JSON para CI
python -m agents.qa_agent --single git                    # auditar uno + crear issue

QA Fix Agent — correcciones quirúrgicas

El agente de corrección (agents/qa_fix_agent.py) procesa issues QA con cambios mínimos. No reescribe contenido — solo corrige lo que el issue describe.

Estrategias de corrección por tipo de hallazgo:

python -m agents.qa_fix_agent --issue 175       # corregir un issue QA
python -m agents.qa_fix_agent --batch 5         # corregir 5 issues
python -m agents.qa_fix_agent --dry-run         # probar sin LLM

Content Agent — upgrades completos

El agente de contenido (agents/content_agent.py) genera reescrituras completas para llevar contenido de seed/growing a evergreen. Procesa issues upgrade: y qa:.

python -m agents.content_agent --issue 143      # procesar un issue
python -m agents.content_agent --batch 3        # procesar 3 issues
python -m agents.content_agent --dry-run        # probar sin LLM

Herramientas compartidas

Los tres agentes comparten cuatro herramientas definidas con el decorador @tool de Strands:

from strands import Agent, tool
from strands.models import BedrockModel
 
@tool
def verify_url(url: str) -> str:
    """Verifica que una URL retorne HTTP 200."""
    r = httpx.head(url, follow_redirects=True, timeout=10)
    return f"{url} → HTTP {r.status_code}"
 
@tool
def read_file(path: str) -> str:
    """Lee un archivo del repositorio."""
    with open(os.path.join(os.environ["REPO_ROOT"], path)) as f:
        return f.read()
 
@tool
def write_file(path: str, content: str) -> str:
    """Escribe contenido a un archivo."""
    with open(os.path.join(os.environ["REPO_ROOT"], path), "w") as f:
        f.write(content)
    return f"Written: {path}"
 
@tool
def list_concept_files() -> str:
    """Lista conceptos existentes para cross-references."""
    # retorna slugs disponibles para el array concepts: del frontmatter

Patrón diamante en GitHub Actions

Los tres workflows usan el mismo patrón de ejecución — un «diamante» que descubre trabajo, lo distribuye en paralelo y consolida resultados:

Plan — descubre qué procesar (issues abiertos o conceptos con hallazgos), genera una matriz JSON.

Matrix — cada item se procesa en un job aislado. Si uno falla, los demás continúan (fail-fast: false).

Summary — descarga artefactos de todos los jobs, escribe un resumen en el job summary de GitHub.

Gestión de límites de tasa

Los workflows que usan LLM (content agent, QA fix agent) serializan los jobs de la matriz (max-parallel: 1) para evitar throttling de Bedrock. El QA agent estructural — que no usa LLM — mantiene paralelismo alto (max-parallel: 5). El QA agent en modo deep serializa a 1.

# content-agent.yml — serializado para evitar throttling
strategy:
  fail-fast: false
  max-parallel: 1
  matrix: ${{ fromJson(needs.plan.outputs.matrix) }}
 
# content-qa.yml — dinámico según modo
strategy:
  fail-fast: false
  max-parallel: ${{ inputs.deep == true && 1 || 5 }}
  matrix: ${{ fromJson(needs.plan.outputs.matrix) }}

Como respaldo, los agentes incluyen un retry con backoff corto (1 intento, 10 segundos) que falla rápido para no consumir minutos de CI innecesariamente.

Timeouts ajustados

Autenticación sin secrets estáticos

La autenticación usa OIDC — GitHub Actions obtiene un token JWT efímero que intercambia por credenciales temporales de AWS:

resource "aws_iam_role" "content_agent" {
  name = "jonmatum-content-agent"
 
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Federated = aws_iam_openid_connect_provider.github.arn }
      Action    = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
        }
        StringLike = {
          "token.actions.githubusercontent.com:sub" = "repo:jonmatum/jonmatum.com:*"
        }
      }
    }]
  })
}
 
resource "aws_iam_role_policy" "bedrock_invoke" {
  role = aws_iam_role.content_agent.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-sonnet-4-*",
        "arn:aws:bedrock:*:*:inference-profile/us.anthropic.claude-sonnet-4-*"
      ]
    }]
  })
}

Sin API keys almacenadas, sin rotación de credenciales, sin riesgo de filtración. El rol solo permite InvokeModel en Bedrock.

Resultados medidos

Datos de las ejecuciones del sistema:

Lecciones aprendidas

• OIDC elimina la gestión de credenciales: la integración GitHub Actions → AWS con OIDC se configura en 20 líneas de Terraform. Sin rotación, sin filtración.
• El system prompt es el control de calidad: las reglas del AGENTS.md se inyectan como system prompt — el agente sigue estructura, idioma y estándares sin lógica adicional.
• Validación post-generación es obligatoria: sin pnpm validate + pnpm lint:content después de escribir, el agente genera frontmatter con campos faltantes o contenido que no pasa el linter.
• Serializar evita throttling: max-parallel: 1 en workflows con LLM elimina el problema de rate limits de Bedrock sin gastar minutos de CI en retries.
• Agentes especializados superan a uno genérico: separar auditoría (determinística, sin costo), corrección (quirúrgica, barata) y upgrade (completo, más caro) permite optimizar costo y calidad por tipo de tarea.
• MDX y angle brackets no se mezclan: <50% o <10 en contenido MDX se parsea como JSX. Los agentes deben usar prosa: «menos de 50%», «más de 10».
• El modelo de herramientas de Strands simplifica la integración: definir @tool con docstrings genera automáticamente el esquema para el modelo — sin JSON Schema manual.

¿Por qué importa?

Este sistema demuestra que un conjunto de agentes especializados con herramientas simples (lectura/escritura de archivos, verificación HTTP) puede mantener una base de conocimiento de forma autónoma. El patrón es replicable: cualquier repositorio con contenido estructurado y reglas de calidad documentadas puede implementar el mismo bucle — auditar, corregir, mejorar, revisar. El humano pasa de escritor a editor: revisa PRs en lugar de escribir contenido desde cero.

Referencias

• Strands Agents — Amazon Bedrock — Strands, 2025. Integración de Strands con Bedrock.
• Strands Agents — Custom Tools — Strands, 2025. Definición de herramientas personalizadas con @tool.
• Amazon Bedrock Documentation — AWS, 2025. Documentación oficial del servicio.
• GitHub OIDC with AWS — GitHub, 2025. Configuración de OIDC para GitHub Actions con AWS.
• Terraform AWS IAM OIDC Provider — HashiCorp, 2025. Recurso Terraform para OIDC.
• GitHub Actions — Using a matrix for your jobs — GitHub, 2025. Documentación de estrategia matrix en workflows.