Tu primer agente en Python con Strands Agents

En el capítulo anterior nos quedamos en la teoría: qué es un agente, sus tres ingredientes, el enfoque model-driven. En este capítulo esa teoría se convierte en algo que ocurre directamente en tu máquina. Al terminarlo serás capaz de seis cosas:

1. Entender el proyecto que construiremos juntos a lo largo del libro.
2. Montar un proyecto Python aislado con una herramienta llamada uv e instalar el SDK de Strands Agents.
3. Crear las credenciales de AWS desde cero por la ruta más fácil que existe hoy: la Bedrock API key.
4. Saber si un modelo está disponible en una región concreta cuando trabajamos con Bedrock.
5. Crear tu primer agente: el hola mundo de Strands Agents.
6. Tener claro que, aunque en este capítulo trabajamos con Amazon Bedrock, Strands funciona con prácticamente cualquier LLM: OpenAI, Gemini, modelos locales con Ollama, etc.

El proyecto: un asistente de entrenamiento de gimnasio

A lo largo del libro construiremos, capítulo a capítulo, un único proyecto: un asistente virtual para el seguimiento de tu entrenamiento y tu rutina de gimnasio, pensado para cualquier persona que entrene. Este agente será tu compañero de entrenamiento: podrá atender a quien le escribe, buscarlo en el sistema y consultar sus rutinas, sus entrenamientos y su progreso.

Una de sus funcionalidades más particulares serán las acciones delicadas con aprobación humana: por ejemplo, borrar tu historial de entrenamientos, pero no de cualquier manera, sino con tu visto bueno previo antes de tocar los datos, porque eso es lo que hace un sistema real. El agente pedirá permiso, se detendrá, y solo cuando des el okay ejecutará la acción.

El asistente además tendrá memoria —si le escribiste ayer, hoy debe recordarlo y mantener la conversación— y podrá delegar en agentes especialistas: por ejemplo, escalar del agente de seguimiento del día a día a otro experto en planificar tu siguiente rutina, todos trabajando en equipo. El objetivo final es dejarlo listo para producción.

En este capítulo ponemos los cimientos: todas las dependencias y credenciales que el agente necesita para funcionar.

Las dos dependencias del SDK

Trabajaremos con dos paquetes principales:

El único prerrequisito para trabajar con Strands Agents es tener Python 3.10 o superior. Y no hay que preocuparse por esa instalación, porque uv la resuelve automáticamente.

uv: la forma moderna de gestionar proyectos Python

uv es un gestor de proyectos y de paquetes en Python creado por la gente de Astral, los mismos creadores de Ruff. Está escrito en Rust, lo que lo hace muy rápido: comparado con herramientas equivalentes como pip o venv, corre entre 10 y 100 veces más rápido.

La documentación oficial de Strands utiliza pip, y si prefieres trabajar con pip te funcionará igual. Pero uv es la forma moderna de interactuar con Python —crear proyectos, sincronizar dependencias, gestionar versiones— y es la que usaremos en este libro.

Para instalarlo:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Para verificar que se instaló correctamente, abre una terminal nueva y ejecuta:

uv --version

Consejo: si el comando no se reconoce justo después de instalar, cierra la terminal y abre una nueva para que se actualice el PATH.

Inicializar el proyecto

Crea una carpeta para el proyecto —por ejemplo agente-gimnasio—, ábrela en tu editor y, desde una terminal dentro de ella, inicializa el proyecto:

uv init

Esto le dice a uv: “inicialízame un proyecto Python en la carpeta actual”. Genera varios archivos: un .gitignore, un archivo con la versión de Python, un main.py genérico y un pyproject.toml con el nombre del proyecto, la versión, la descripción y las dependencias.

A continuación fijamos la versión de Python con la que trabajará el proyecto:

uv python pin 3.12

Con esto le decimos al proyecto: “vas a trabajar con Python 3.12”. Si uv se queja porque el requires-python del pyproject.toml exige una versión superior, baja ese valor en el archivo y vuelve a ejecutar el comando. ¿Y si no tienes Python 3.12 instalado? No pasa nada: uv lo instala automáticamente por ti.

Ahora las dependencias. Instalar un paquete con uv es tan sencillo como uv add y el nombre:

uv add strands-agents
uv add strands-agents-tools

Con el primer uv add, uv crea además el entorno virtual automáticamente: otro dolor de cabeza que nos ahorramos. Ambas dependencias quedan registradas en el pyproject.toml; si más adelante le pasas este proyecto a un compañero, le bastará con ejecutar uv sync para instalar todo sin más.

¿Qué es Amazon Bedrock?

Ya hemos mencionado de pasada que el agente puede usar Bedrock u otros LLMs; toca presentarlo formalmente. Amazon Bedrock es un servicio de AWS que permite crear aplicaciones de IA generativa sin administrar la infraestructura ni los modelos directamente. En lugar de desplegar tu propio modelo, accedes a múltiples modelos mediante una sola API.

Puedes verlo como una plataforma unificada: una única interfaz para trabajar con modelos de distintos proveedores, ya sea Amazon Nova, Anthropic con Claude, Meta con Llama, Mistral, etc. Con este enfoque puedes crear chatbots y asistentes virtuales, generar texto, imágenes, audio o vídeo, resumir documentos y responder sobre tus datos (RAG), construir agentes que interactúan con sistemas y APIs, o ajustar modelos con tus propios datos.

Credenciales: la Bedrock API key

Para acceder a Bedrock necesitas una forma de autenticarte contra AWS. Antes esto requería bastantes pasos: entrar en IAM, crear un usuario, asignarle políticas, generar un access key y un secret key, configurar el CLI… un proceso largo donde uno puede equivocarse en cinco sitios distintos. Ese camino sigue existiendo, pero nosotros usaremos la ruta que AWS recomienda hoy para empezar con Bedrock: la Bedrock API key.

Es simplemente una clave que autentica tus llamadas a Bedrock: una sola clave, una sola variable de entorno, y se acabó la complejidad. Lo mejor es que, al crearla, AWS adjunta automáticamente al usuario la política AmazonBedrockLimitedAccess, que ya trae los permisos para invocar los modelos.

Para crearla:

1. Inicia sesión en la consola de AWS (si no tienes cuenta, créala primero desde la propia página de acceso).
2. En el buscador de la consola, escribe Bedrock y entra en el servicio.
3. En el menú, haz clic en API keys. Verás dos opciones:
   • Short-term: claves que duran como máximo 12 horas, recomendadas para producción.
   • Long-term: pensadas para explorar y aprender — nuestro caso.
4. Haz clic en Generate long-term API keys, elige el plazo de expiración (hasta 365 días) y genera la clave.

Mucho cuidado con esta clave. Cualquier persona que la tenga puede generar solicitudes a tu nombre, y el coste de esas consultas se factura a tu cuenta. Cópiala y guárdala en un lugar seguro.

La propia consola te muestra el comando para exportarla como variable de entorno según tu sistema:

# macOS / Linux
export AWS_BEARER_TOKEN_BEDROCK="tu-api-key"

# Windows (PowerShell)
$env:AWS_BEARER_TOKEN_BEDROCK="tu-api-key"

Esa variable de entorno será utilizada cada vez que el agente quiera comunicarse con Bedrock.

Habilitar los modelos de Anthropic

Antes de ejecutar el primer agente quedan dos gestiones:

• Formulario de caso de uso. Para usar modelos de Anthropic (Claude, que es lo que Strands usa por defecto), AWS pide rellenar una única vez por cuenta un formulario: el nombre de tu empresa o proyecto, una URL (si no tienes, sirve tu GitHub o tu LinkedIn), la industria y una descripción breve del caso de uso. Llegas a él desde Model catalog en la consola de Bedrock.
• Método de pago validado. Los modelos se sirven a través del marketplace de AWS, así que la cuenta necesita un método de pago configurado.

No te agobies con esto último: recuerda que Strands es agnóstico al proveedor. Bedrock es el default, pero no una obligación — puedes trabajar perfectamente con Gemini, que tiene un free tier, o con modelos locales tipo Ollama, que son gratis y ni siquiera necesitan acceso a internet. Presentamos Bedrock porque, cuando quieras llevar tu proyecto a nivel productivo bajo una única interfaz, es la mejor forma de hacerlo, con AWS encargándose de toda la infraestructura.

Verificar el acceso: modelos disponibles por región

Buena noticia: para verificar las credenciales no hay que instalar nada adicional. Al instalar strands-agents, entre sus dependencias llegó boto3, el SDK oficial de AWS para Python — literalmente la librería que Strands usa por debajo para hablar con Bedrock. Puedes comprobarlo en las dependencias de tu proyecto.

Sustituye el contenido de main.py por este script de verificación:

import boto3

cliente = boto3.client("bedrock", region_name="us-east-2")

respuesta = cliente.list_foundation_models(byProvider="anthropic")

for modelo in respuesta["modelSummaries"]:
    print(
        modelo["modelId"],
        "| streaming:", modelo.get("responseStreamingSupported"),
    )

El script crea un cliente que se comunica con Bedrock en una región concreta y lista los modelos de Anthropic disponibles en ella. Esto importa porque hay modelos que no están disponibles en todas las regiones, y conviene validarlo para que el agente no falle al intentar comunicarse con uno inexistente.

Ejecútalo con:

uv run main.py

Si la API key funciona, verás el listado de modelos con su soporte de streaming. Fíjate en los IDs que aparecen: son los identificadores exactos que usaremos en el código. Pero no te los aprendas ni los copies de ningún otro sitio — este script es tu fuente de verdad sobre qué modelos tienes disponibles en cada región.

Hola mundo: tu primer agente

Con el entorno creado, las dependencias instaladas y las credenciales verificadas, llega el corazón del capítulo. Borra el contenido de main.py y escribe:

from strands import Agent

agente = Agent()
agente("Explícame en una sola frase qué es Amazon Bedrock.")

Consejo: si tu editor no resuelve el import de strands, recarga la ventana (en VS Code: Ctrl+Shift+P → Reload Window) para que detecte el entorno que creó uv.

Ejecuta:

uv run main.py

El agente responde: Amazon Bedrock es un servicio de AWS que permite acceder y utilizar modelos de inteligencia artificial generativa… Y ya está: este es el agente más simple que vas a ver, pero en estructura y en definición, esto es un agente.

¿Qué modelo acaba de responder?

Buena pregunta, porque no le pasamos ninguno. El agente respondió con sus valores por defecto. Para comprobarlos:

from strands import Agent

agente = Agent()
print(agente.model.config)

La salida muestra que el comportamiento por defecto de Strands es comunicarse con Amazon Bedrock usando un modelo Claude Sonnet — ese es el ID de modelo que está utilizando el agente sin que se lo digamos. Comentar la llamada al agente mientras inspeccionas la configuración, por cierto, evita gastar créditos en consultas que no necesitas.

Elegir el modelo explícitamente: BedrockModel

Si quieres ser más específico, basta con un par de modificaciones:

from strands import Agent
from strands.models import BedrockModel

modelo = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",  # usa un ID de tu listado
    region_name="us-east-2",
    temperature=0.3,
)

agente = Agent(model=modelo)
agente("Explícame en una sola frase qué es Amazon Bedrock.")

Tres argumentos:

• model_id: el modelo con el que quieres trabajar, sacado del listado que obtuviste con el script de verificación. Muy importante: los modelos están ligados a una región; si usas uno que no está disponible en la región elegida, obtendrás un error.
• region_name: la región donde quieres trabajar (aquí, us-east-2).
• temperature: controla cómo de creativo será el modelo al responder. Lo veremos en detalle más adelante; de momento lo fijamos en 0.3.

Al ejecutar de nuevo con uv run main.py, el agente responde igual que antes, pero ahora usando Claude Haiku 4.5 — bastante más económico que trabajar con un Sonnet.

Strands no está casado con Bedrock

Para cerrar, algo que debe quedar clarísimo: usamos Bedrock en este libro porque es el default del SDK y porque al final desplegaremos en AWS, pero el diseño de Strands es agnóstico al proveedor. La regla es una sola:

Cualquier modelo que soporte tool use y streaming puede ser el cerebro de tu agente — Gemini, GPT, Claude, etc.

Compruébalo tú mismo: cambia de proveedor y observa que las piezas de tu lado no se mueven — toda la lógica interna de conversación con los distintos LLMs queda abstraída por el SDK.

Cambiar de proveedor se reduce a cuatro pasos: añadir la dependencia del proveedor, importar la clase de modelo específica, crear la instancia del modelo y pasársela al agente. Exactamente el mismo procedimiento que acabamos de hacer con BedrockModel.

Resumen

• El proyecto del libro es un asistente virtual de entrenamiento de gimnasio: seguimiento de rutinas y progreso, acciones delicadas con aprobación humana, memoria y delegación en agentes especialistas, hasta llegar a producción.
• strands-agents es el paquete obligatorio (el motor); strands-agents-tools añade herramientas de la comunidad. El prerrequisito es Python 3.10+.
• uv gestiona el proyecto: uv init, uv python pin, uv add, uv run y uv sync, entre 10 y 100 veces más rápido que pip/venv, con entorno virtual automático.
• La Bedrock API key es la ruta fácil de autenticación: una clave, una variable de entorno (AWS_BEARER_TOKEN_BEDROCK) y la política AmazonBedrockLimitedAccess adjuntada automáticamente.
• Los modelos de Bedrock están ligados a una región: el script de verificación con boto3 es tu fuente de verdad.
• Un agente mínimo son tres líneas: importar Agent, instanciarlo e invocarlo. Con BedrockModel eliges modelo, región y temperatura.
• Strands es agnóstico al proveedor: cualquier modelo con tool use y streaming puede ser el cerebro.

En el siguiente capítulo crearemos nuestra primera herramienta: la pieza que dará manos a este agente.

Autoevaluación

Antes de continuar, comprueba que los conceptos clave han quedado claros.