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:

• Ligero y personalizable: Bucle de agente simple que no interfiere
• Listo para producción: Observabilidad completa, tracing y opciones de despliegue escalable
• 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	CDK	The preferred IaC provider

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 Fábrica de clientes ú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 pasado al 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 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:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    tools=[calculate_sum, get_weather],
)

El framework Strands maneja automáticamente:

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

Usando Herramientas Preconstruidas

Strands provee herramientas preconstruidas en el paquete strands-tools:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=[current_time, http_request, file_read],
)

Configuración de Modelos

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

from strands import Agent
from strands.models import BedrockModel

# Create a 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.

Para consumir servidores MCP creados con los generadores py#mcp-server o ts#mcp-server, se genera una fábrica de clientes en agentcore_mcp_client.py.

Actualiza el método get_agent en agent.py para crear clientes MCP y añadir herramientas. Ejemplo 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

# Obtain the region an credentials
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, usa AgentCoreMCPClient.with_jwt_auth en su lugar.

Para el ejemplo anterior con IAM, debemos configurar dos aspectos en la infraestructura:

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

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

# Agent
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 agentes Strands, consulta la documentación oficial.

SDK Python de Bedrock AgentCore

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

Detalles del SDK en la documentación.

Nota

El generador provee infraestructura CDK/Terraform para despliegue, no necesitas usar bedrock-agentcore-starter-toolkit.

Ejecutando tu Agente Strands

Desarrollo Local

El generador configura un target <your-agent-name>-serve para iniciar el 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 con el SDK Python de Bedrock AgentCore.

Despliegue en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se genera infraestructura CDK/Terraform relevante.

CDK

Constructo CDK generado (nombre basado en name o <ProjectName>Agent):

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

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

    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

Terraform

Módulo Terraform generado (nombre basado en name o <ProjectName>-agent):

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

Asegura tener habilitados los modelos base en tu cuenta AWS. Para activarlos, sigue estas instrucciones.

Precaución

Necesitas Docker instalado. Errores como:

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

indican problemas con Docker.

Targets Bundle y Docker

El target bundle:

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

Target docker:

• Construye una imagen desde el Dockerfile según el contrato de runtime

Consejo

La imagen usa un tag (ej. my-scope-my-project-agent:latest) referenciado por tu infraestructura.

Autenticación

IAM

Configuración por defecto:

CDK

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

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

Otorgar acceso con 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

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

Política de acceso ejemplo:

{
  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

Ejemplo de configuración:

CDK

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

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

Configuración automática con AWS Distro for Open Telemetry en el Dockerfile.

Los traces se encuentran en CloudWatch > “GenAI Observability”. Habilita Transaction Search.

Más detalles en documentación de AgentCore.