Agente de Strands de Python

Genera un Agente Strands en Python para construir agentes de IA con herramientas, y opcionalmente desplegarlo en Amazon Bedrock AgentCore Runtime.

¿Qué es Strands?

Strands es un framework Python ligero y listo para producción para construir agentes de IA. Características clave incluyen:

• Ligero y personalizable: Bucle de agente simple que no interfiere
• Listo para producción: Observabilidad completa, tracing y opciones de despliegue escalables
• Agnóstico a modelos y proveedores: Soporta múltiples modelos de distintos proveedores
• Herramientas comunitarias: Conjunto potente de herramientas contribuidas por la comunidad
• Soporte multi-agente: Técnicas avanzadas como equipos de agentes y agentes autónomos
• Modos de interacción flexibles: Soporte conversacional, streaming y no streaming

Uso

Generar un Agente Strands

Puedes generar un Agente Strands en Python de dos formas:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - py#strands-agent
5. Complete los parámetros requeridos
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent

yarn

yarn nx g @aws/nx-plugin:py#strands-agent

npm

npx nx g @aws/nx-plugin:py#strands-agent

bun

bunx nx g @aws/nx-plugin:py#strands-agent

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent --dry-run

yarn

yarn nx g @aws/nx-plugin:py#strands-agent --dry-run

npm

npx nx g @aws/nx-plugin:py#strands-agent --dry-run

bun

bunx nx g @aws/nx-plugin:py#strands-agent --dry-run

Requisito previo del proyecto

Primero usa el generador py#project para crear un proyecto donde añadir tu Agente Strands.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	El proyecto al que agregar el Strands Agent
computeType	string	BedrockAgentCoreRuntime	El tipo de cómputo para alojar tu Strands Agent.
name	string	-	El nombre de tu Strands Agent (predeterminado: agent)
auth	string	IAM	El método utilizado para autenticar con tu Strands Agent. Elige entre IAM (predeterminado) o Cognito.
iacProvider	string	Inherit	El proveedor de IaC preferido. Por defecto, esto se hereda de tu selección inicial.

Salida del Generador

El generador añadirá los siguientes archivos a tu proyecto Python existente:

• Directorioyour-project/

  • Directorioyour_module/

    • Directorioagent/ (o nombre personalizado si se especifica)

      • __init__.py Inicialización del paquete Python
      • init.py Configuración de aplicación FastAPI con middleware CORS y manejo de errores
      • agent.py Definición principal del agente con herramientas de ejemplo
      • main.py Punto de entrada para Bedrock AgentCore Runtime
      • Dockerfile Punto de entrada para alojar tu agente (excluido cuando computeType es None)
  • pyproject.toml Actualizado con dependencias de Strands
  • project.json Actualizado con objetivos de servicio del agente

Infraestructura

Despliegue serverless

Si seleccionaste None para computeType, el generador no proveerá infraestructura como código.

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el ts#project generator y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el terraform#project generator y por lo tanto configura los mismos objetivos de compilación.

Para desplegar tu Agente Strands, se generan los siguientes archivos:

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.ts Constructo CDK para desplegar tu agente
        • Dockerfile Archivo Docker usado por el constructo CDK

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.tf Módulo para desplegar tu agente
  • Directoriocore

    • Directorioagent-core

      • runtime.tf Módulo genérico para despliegue en Bedrock AgentCore Runtime

Trabajando con tu Agente Strands

Añadiendo Herramientas

Las herramientas son funciones que el agente de IA puede llamar para realizar acciones. Strands usa un enfoque basado en decoradores para definirlas.

Puedes añadir nuevas herramientas en el archivo agent.py:

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calcula la suma de una lista de números"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Obtiene información meteorológica de una ciudad"""
    # Tu integración de API del tiempo aquí
    return f"Weather in {city}: Soleado, 25°C"

# Añade herramientas al agente
agent = Agent(
    system_prompt="Eres un asistente útil con acceso a varias herramientas.",
    tools=[calculate_sum, get_weather],
)

El framework Strands maneja automáticamente:

• Validación de tipos basada en type hints
• Generación de esquema JSON para tool calling
• Manejo de errores y formato de respuestas

Usando Herramientas Preconstruidas

Strands provee herramientas preconstruidas a través del paquete strands-tools:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="Eres un asistente útil.",
    tools=[current_time, http_request, file_read],
)

Configuración de Modelos

Por defecto, Strands usa Claude 4 Sonnet, pero puedes personalizar el proveedor. Consulta la documentación de Strands sobre proveedores de modelos:

from strands import Agent
from strands.models import BedrockModel

# Crea un BedrockModel
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

Consumiendo Servidores MCP

Puedes añadir herramientas de servidores MCP a tu agente Strands.

Para consumir servidores MCP creados con los generadores py#mcp-server o ts#mcp-server puedes hacer uso del generador connection.

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.

Para otros servidores MCP, consulta la Documentación de Strands.

Más información

Para una guía detallada sobre cómo escribir agentes Strands, consulta la documentación de Strands.

Servidor FastAPI

El generador usa FastAPI para crear el servidor HTTP para tu Agente Strands. FastAPI proporciona un framework web moderno y rápido para construir APIs con Python, con documentación automática de API y validación de tipos.

El servidor generado incluye:

• Configuración de aplicación FastAPI con middleware CORS
• Middleware de manejo de errores
• Generación de esquema OpenAPI
• Endpoint de verificación de salud (/ping)
• Endpoint de invocación del agente (/invocations)

Personalizando Entradas y Salidas de Invocación con Pydantic

El endpoint de invocación del agente usa modelos Pydantic para definir y validar los esquemas de solicitud y respuesta. Puedes personalizar estos modelos en main.py para que coincidan con los requisitos de tu agente.

Definiendo Modelos de Entrada

El modelo InvokeInput por defecto acepta un prompt y un ID de sesión.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str
    session_id: str

Puedes extender este modelo para incluir cualquier campo adicional que tu agente necesite.

Organización del código

Probablemente querrás abstraer parte o todo el ID de sesión del llamador si los usuarios van a invocar tu agente directamente. Por ejemplo, puedes usar el ID de usuario autenticado como parte del ID de sesión.

También vale la pena señalar que dependiendo de tu caso de uso, puede que necesites implementar autorización para las sesiones, por ejemplo asegurándote de que los usuarios solo puedan acceder a sus propias sesiones y no a las de otros usuarios.

Definiendo Modelos de Salida

Para respuestas de streaming, el generador proporciona JsonStreamingResponse que serializa automáticamente modelos Pydantic al formato JSON Lines (application/jsonl). Este formato es compatible con la especificación de streaming de OpenAPI 3.2 y funciona perfectamente con el cliente TypeScript generado.

Por defecto, el agente produce objetos StreamChunk que contienen el texto de respuesta del agente:

class StreamChunk(BaseModel):
    content: str

Puedes personalizar el modelo StreamChunk según tus necesidades:

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

Limitación de streaming de FastAPI

Ten en cuenta que dado que FastAPI actualmente no soporta generar una especificación OpenAPI para respuestas de streaming, debemos establecer explícitamente el modelo de respuesta para cada operación de streaming, es decir:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

Existe una solicitud de característica abierta para soporte nativo en FastAPI.

SDK Python de Bedrock AgentCore

El generador incluye una dependencia del SDK Python de Bedrock AgentCore para las constantes PingStatus. Si lo deseas, es sencillo usar BedrockAgentCoreApp en lugar de FastAPI, sin embargo ten en cuenta que se pierde la seguridad de tipos.

Puedes encontrar detalles sobre las capacidades del SDK en la documentación.

Infraestructura como código

Como el generador provee infraestructura CDK/Terraform para desplegar tu agente, no necesitas usar el bedrock-agentcore-starter-toolkit mencionado en los docs.

Ejecutando tu Agente Strands

Desarrollo Local

El generador configura un target llamado <your-agent-name>-serve para iniciar tu agente localmente:

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

Este comando usa uv run para ejecutar tu agente con el SDK Python de Bedrock AgentCore.

Desplegando tu Agente Strands a Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se genera la infraestructura CDK o Terraform relevante que puedes usar para desplegar tu Strands Agent en Amazon Bedrock AgentCore Runtime.

CDK

Se genera una construcción CDK para tu agente, nombrada según el name que elegiste al ejecutar el generador, o <ProjectName>Agent por defecto.

Puedes usar esta construcción CDK en una aplicación CDK:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.addToRolePolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: [
          'arn:aws:bedrock:*:*:foundation-model/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

Constructo CDK Alpha

Esta construcción utiliza el módulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Se genera un módulo Terraform para ti, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>-agent por defecto.

Puedes usar este módulo terraform en un proyecto Terraform:

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

Docker requerido

Docker es necesario para construir y desplegar tu Strands Agent. Asegúrate de haber instalado e iniciado Docker para evitar errores como:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Autenticación

El generador proporciona una opción auth para configurar la autenticación de tu Strands Agent. Puedes elegir entre autenticación IAM (predeterminada) o Cognito al generar tu agente.

IAM

Por defecto, tu Strands Agent estará protegido usando autenticación IAM, simplemente despliégalo sin ningún argumento:

CDK

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Puedes otorgar acceso para invocar tu agente en Bedrock AgentCore Runtime usando el método grantInvokeAccess, por ejemplo:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Para otorgar acceso para invocar tu agente, necesitarás agregar una política como la siguiente, haciendo referencia a la salida module.my_project_agent.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Autenticación Cognito

Cuando seleccionas autenticación Cognito, el generador configura el agente para usar Cognito para la autenticación.

CDK

La construcción generada acepta una propiedad identity que configura la autenticación Cognito:

import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

La construcción UserIdentity puede generarse usando el generador ts#react-website#auth, o puedes crear tu propio UserPool y UserPoolClient de CDK.

Terraform

El módulo generado acepta las variables user_pool_id y user_pool_client_ids para la autenticación Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Proveedores OIDC personalizados

Si requieres autenticación JWT personalizada con un proveedor OIDC que no sea Cognito, puedes modificar directamente la construcción CDK o el módulo Terraform generado para tu agente. Ten en cuenta que el generador de conexión solo admitirá autenticación IAM o Cognito.

Targets de Bundle y Docker

Para construir tu agente para Bedrock AgentCore Runtime, se añade un target bundle que:

• Exporta dependencias Python a requirements.txt usando uv export
• Instala dependencias para la plataforma objetivo (aarch64-manylinux2014) con uv pip install

También se añade un target docker específico que:

• Construye una imagen Docker desde el Dockerfile que ejecuta tu agente según el contrato de runtime de AgentCore

Etiquetas de imagen Docker

La imagen Docker se construye con un tag (ej. my-scope-my-project-agent:latest), referenciado por tu infraestructura CDK/Terraform, permitiendo co-localizar el Dockerfile con tu proyecto.

Observabilidad

Tu agente se configura automáticamente con observabilidad usando AWS Distro for Open Telemetry (ADOT), mediante auto-instrumentación en tu Dockerfile.

Puedes encontrar trazas en CloudWatch seleccionando “GenAI Observability”. Para ver trazas, habilita Transaction Search.

Para más detalles, consulta la documentación de observabilidad de AgentCore.

Invocando tu Agente Strands

Invocar el Servidor Local

Para invocar un Agente ejecutándose localmente mediante el target <your-agent-name>-serve, puedes enviar una simple solicitud POST a /invocations en el puerto donde se ejecuta tu agente local. Por ejemplo, con curl:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -H "Content-Type: application/json"

Flag de streaming de Curl

El argumento -N dado a curl deshabilita el buffering del flujo de salida, para que puedas ver la respuesta de streaming en tiempo real.

Invocar el Agente Desplegado

Para invocar tu Agente desplegado en Bedrock AgentCore Runtime, puedes enviar una solicitud POST al endpoint del plano de datos de Bedrock AgentCore Runtime con tu ARN de runtime codificado en URL.

Puedes obtener el ARN de runtime desde tu infraestructura de la siguiente manera:

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

El ARN tendrá el siguiente formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Luego puedes codificar el ARN en URL reemplazando : con %3A y / con %2F.

Consola del navegador

Esto es sencillo en una consola de navegador o Node REPL usando el método integrado encodeURIComponent:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

La URL del plano de datos de Bedrock AgentCore Runtime para invocar el agente es la siguiente:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

La forma exacta de invocar esta URL depende del método de autenticación utilizado.

Autenticación IAM

Para autenticación IAM, la solicitud debe firmarse usando AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock
-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
-H 'Content-Type: application/json'

Haz clic aquí para más detalles sobre cómo configurar el comando acurl anterior

Autenticación JWT / Cognito

Para autenticación Cognito, pasa el Access Token de Cognito en el header Authorization:

curl -N -X POST 'https://bedrock
-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

Puedes obtener el access token usando el comando cognito-idp admin-initiate-auth del AWS CLI, por ejemplo:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text