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:

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (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

• Directorypackages/common/constructs

  • Directorysrc

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

      • …
    • Directorycore/ 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

• Directorypackages/common/terraform

  • Directorysrc

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

      • …
    • Directorycore/ 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

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

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

    • Directoryagent-core

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

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

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

    • Directoryagent-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.

SDK Python de Bedrock AgentCore

El generador configura el SDK Python de Bedrock AgentCore para manejar el contrato HTTP requerido por AgentCore.

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',
        ],
        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" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  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" {
  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
  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.