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

Consejo

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	-	The project to add the Strands Agent to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your Strands Agent.
name	string	-	The name of your Strands Agent (default: agent)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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
      • agent.py Definición principal del agente con herramientas de ejemplo
      • main.py Punto de entrada para Bedrock AgentCore Runtime
      • agentcore_mcp_client.py Factory de cliente útil para invocar servidores MCP alojados en 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

Nota

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

Nota

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

Nota

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
  • Directoriocore

    • Directorioagent-core

      • runtime.ts Constructo CDK genérico para despliegue en Bedrock AgentCore Runtime

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.tf Módulo Terraform 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 (u otros alojados en Bedrock AgentCore Runtime), se genera un factory de cliente en agentcore_mcp_client.py.

Puedes actualizar tu método get_agent en agent.py para crear clientes MCP y añadir herramientas. Este ejemplo muestra cómo hacerlo con autenticación IAM (SigV4):

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Obtiene región y credenciales
region = os.environ["AWS_REGION"]
boto_session = boto3.Session(region_name=region)
credentials = boto_session.get_credentials()

@contextmanager
def get_agent(session_id: str):
    mcp_client = AgentCoreMCPClient.with_iam_auth(
        agent_runtime_arn=os.environ["MCP_AGENTCORE_RUNTIME_ARN"],
        credentials=credentials,
        region=region,
        session_id=session_id,
    )

    with mcp_client:
        mcp_tools = mcp_client.list_tools_sync()

        yield Agent(
            system_prompt="..."
            tools=[*mcp_tools],
        )

Consejo

Si tu servidor MCP usa autenticación JWT, puedes usar el método AgentCoreMCPClient.with_jwt_auth en su lugar.

Con el ejemplo de autenticación IAM anterior, necesitamos configurar dos cosas en nuestra infraestructura: añadir la variable de entorno para el ARN del AgentCore Runtime del servidor MCP, y otorgar permisos de invocación. Esto se logra así:

CDK

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

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

    const agent = new MyProjectAgent(this, 'MyProjectAgent', {
      environment: {
        MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });

    mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# Servidor MCP
module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

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

  env = {
    MCP_AGENTCORE_RUNTIME_ARN = module.my_project_mcp_server.agent_core_runtime_arn
  }

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

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.

Precaución

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, la anotación de tipo de retorno en tu endpoint corresponde al tipo de cada valor producido por tu función generadora. Por defecto, el agente produce strings que contienen el texto de respuesta del agente mientras se transmite desde Strands:

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> str:
    """Entry point for agent invocation"""
    return StreamingResponse(handle_invoke(input), media_type="text/event-stream")

Puedes definir un modelo Pydantic para producir datos estructurados en su lugar:

from pydantic import BaseModel

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

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> StreamChunk:
    return StreamingResponse(handle_invoke(input), media_type="application/json")

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 su documentación.

Nota

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 run your-project:agent-serve

yarn

yarn nx run your-project:agent-serve

npm

npx nx run your-project:agent-serve

bun

bunx nx run your-project:agent-serve

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

Desplegando a Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se genera infraestructura CDK/Terraform relevante para desplegar tu agente en Amazon Bedrock AgentCore Runtime.

CDK

Se genera un constructo CDK nombrado según el parámetro name usado al generar, o <ProjectName>Agent por defecto.

Puedes usarlo en una aplicación CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Añade el agente a tu stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Otorga permisos para invocar modelos de Bedrock
    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // Puedes limitar esto a los modelos específicos que uses
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

Terraform

Se genera un módulo Terraform nombrado según el parámetro name, o <ProjectName>-agent por defecto.

Puedes usarlo en un proyecto Terraform:

# Agente
module "my_project_agent" {
  # Ruta relativa al módulo generado en el proyecto common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Otorga permisos para invocar modelos de Bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

Nota

Al desplegar en Bedrock AgentCore Runtime, asegúrate de habilitar los modelos necesarios en tu cuenta AWS. Por defecto Strands usa Claude 4 Sonnet, pero esto es configurable.

Para habilitar modelos en Amazon Bedrock, sigue estas instrucciones.

Precaución

Se requiere Docker para construir y desplegar tu agente. Asegúrate de tener Docker instalado para evitar errores como:

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

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

Consejo

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.

Autenticación

IAM

Por defecto, tu agente usará autenticación IAM. Despliégalo sin argumentos:

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 usando grantInvoke:

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.agentCoreRuntime.grantInvoke(lambdaFunction);
  }
}

Terraform

# Agente
module "my_project_agent" {
  # Ruta relativa al módulo generado en el proyecto common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Para otorgar acceso, añade una política que referencia 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 JWT

El siguiente ejemplo muestra cómo configurar autenticación Cognito:

CDK

Para JWT, pasa authorizerConfiguration a tu constructo. Ejemplo configurando Cognito:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

Terraform

Edita tu módulo para configurar customJWTAuthorizer:

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # Reemplaza con tus IDs de user pool y client o expón como variables
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

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.