Strands agent + Agent Core AWS

Source: Dev.to

Tabla de Contenidos

• Requisitos Previos
• Instalación del Toolkit
• Crear el Agente
• Configurar y Desplegar
• Monitorear el Despliegue
• Probar Memoria y Code Interpreter
• Ver Trazas y Logs
• Limpieza de Recursos
• Solución de Problemas

Requisitos Previos

Antes de comenzar, asegúrate de tener:

1. Permisos de AWS

   • Usuarios root o con roles privilegiados (AdministratorAccess) pueden omitir este paso.
   • Otros usuarios deben adjuntar la política del starter toolkit y la política administrada AmazonBedrockAgentCoreFullAccess.

2. AWS CLI

   • Versión 2.0 o posterior.
   • Configura con aws configure.

3. Acceso al Modelo Amazon Bedrock

   • Habilita Claude 3.7 Sonnet en la región deseada:
     AWS Management Console → Amazon Bedrock → Model access.

4. Python

   • Python 3.10 o más reciente.

5. Consistencia de Región AWS
   ⚠️ IMPORTANTE: Usa la misma región para:

   • La región predeterminada en aws configure.
   • La región donde habilitaste el acceso al modelo de Amazon Bedrock.

Instalación del Toolkit

Paso 1: Crear Entorno Virtual

# Crear entorno virtual
python -m venv .venv

# Activar entorno virtual
# macOS/Linux:
source .venv/bin/activate

# Windows:
# .venv\Scripts\activate

Paso 2: Instalar Paquetes Requeridos

# Instalar paquetes (versión 0.1.21 o posterior)
pip install "bedrock-agentcore-starter-toolkit>=0.1.21" strands-agents boto3

Crear el Agente

Paso 1: Crear el Archivo del Agente

Crea un archivo llamado agentcore_starter_strands.py con el código del agente.
Características del agente:

• Integración con AgentCore Memory (corto y largo plazo).
• Herramienta de cálculo con Code Interpreter.
• Gestión de sesiones.
• Sistema de prompts personalizable.

Paso 2: Crear Archivo de Requisitos

# requirements.txt
strands-agents
bedrock-agentcore

Configurar y Desplegar

Paso 1: Configurar el Agente

agentcore configure -e agentcore_starter_strands.py

Responde a los prompts interactivos:

• Execution Role: Presiona Enter para crear automáticamente un rol con los permisos requeridos.
• ECR Repository: Presiona Enter para crear un repositorio o proporciona un URI existente.
• Requirements File: Confirma el archivo requirements.txt.
• OAuth Configuration: Escribe no.
• Request Header Allowlist: Escribe no.
• Memory Configuration:
  • Si existen memorias, elige una o presiona Enter para crear una nueva.
  • Al crear una nueva, habilita la extracción de memoria a largo plazo escribiendo yes.
  • La memoria a corto plazo está siempre habilitada por defecto.

Paso 2: Desplegar en AgentCore

agentcore launch

Este comando:

• Aprovisiona recursos de memoria (STM + LTM).
• Construye la imagen Docker con dependencias.
• Hace push al repositorio ECR.
• Despliega el runtime de AgentCore con X‑Ray habilitado.
• Configura CloudWatch Transaction Search automáticamente.
• Activa el endpoint con recolección de trazas.

Salida esperada:

✅ Memory created: bedrock_agentcore_memory_ci_agent_memory-abc123
Observability is enabled, configuring Transaction Search...
✅ Transaction Search configured: resource_policy, trace_destination, indexing_rule
🔍 GenAI Observability Dashboard:
   https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#gen-ai-observability/agent-core
✅ Container deployed to Bedrock AgentCore
Agent ARN: arn:aws:bedrock-agentcore:us-west-2:123456789:runtime/starter_agent-xyz

Paso 3: Verificar Configuración (si hay errores)

# Revisar configuración desplegada
cat .bedrock_agentcore.yaml

# Verificar estado de aprovisionamiento de recursos
agentcore status

Monitorear el Despliegue

Verificar Estado del Agente

agentcore status

Información mostrada: Memory ID, estado (CREATING → ACTIVE), tipo (STM+LTM), ARN del agente, URL del dashboard de observabilidad y ruta de logs del runtime.

Esperar hasta que la Memoria esté Activa

⏱️ El aprovisionamiento suele tardar 2‑3 min.

# Repetir cada 30 s hasta que el estado sea ACTIVE
agentcore status

Probar Memoria y Code Interpreter

Memoria a Corto Plazo (STM)

# Primera invocación – almacenar información
agentcore invoke '{"prompt": "Mi nombre es Juan"}'

# Segunda invocación en la misma sesión – recuperar información
agentcore invoke '{"prompt": "¿Cuál es mi nombre?"}'

Respuesta esperada: “Tu nombre es Juan.”

Memoria a Largo Plazo (LTM)

⏱️ AgentCore ejecuta extracciones en segundo plano; espera 10‑30 s después de almacenar hechos.

# Sesión 1: almacenar hechos
agentcore invoke '{"prompt": "Mi email es usuario@ejemplo.com y soy un usuario de AgentCore"}'

# Esperar a que la extracción finalice
sleep 20

# Sesión 2: nueva sesión diferente recupera los hechos extraídos
SESSION_ID=$(python -c "import uuid; print(uuid.uuid4())")
agentcore invoke '{"prompt": "¿Qué sabes sobre mí?"}' --session-id $SESSION_ID

Respuesta esperada:

• “Tu dirección de email es usuario@ejemplo.com.”
• “Pareces ser un usuario de AgentCore.”

Code Interpreter

# Almacenar datos
agentcore invoke '{"prompt": "Mi dataset tiene valores: 23, 45, 67, 89, 12, 34, 56."}'

# Crear visualización
agentcore invoke '{"prompt": "Crea una visualización de gráfico de barras basada en texto que muestre la distribución de valores en mi dataset con etiquetas apropiadas"}'

Resultado esperado: El agente genera código matplotlib que produce un gráfico de barras.

Ver Trazas y Logs

Acceder al Dashboard de Amazon CloudWatch

El dashboard GenAI Observability muestra:

• Trazas end‑to‑end de solicitudes.
• Seguimiento de la ejecución del agente.
• Operaciones de recuperación de memoria.
• Ejecuciones del Code Interpreter.
• Pasos de razonamiento del agente.
• Desglose de latencia por componente.

Obtén la URL del dashboard desde agentcore status o accede directamente:

https://console.aws.amazon.com/cloudwatch/home

Limpieza de Recursos

Cuando ya no necesites el agente, elimina los recursos creados para evitar cargos:

# Eliminar la memoria y el runtime
agentcore delete --all

# Opcional: eliminar el repositorio ECR
aws ecr delete-repository --repository-name  --force

Solución de Problemas

• Error de permisos: Verifica que tu usuario tenga la política AmazonBedrockAgentCoreFullAccess y que el rol de ejecución tenga los permisos necesarios.
• Memoria no se activa: Revisa los logs con agentcore logs y confirma que la región configurada coincide con la del modelo.
• Fallos al lanzar el contenedor: Asegúrate de que Docker está instalado y que tu cuenta tiene cuota suficiente en ECR.
• Code Interpreter no genera código: Comprueba que la política AWSLambdaBasicExecutionRole (o equivalente) está adjunta al rol de ejecución.

---

Fin de la guía.