Agente Python Strands

Genera un Agente Strands in Python per costruire agenti AI con strumenti, e opzionalmente distribuirlo su Amazon Bedrock AgentCore Runtime.

Cos’è Strands?

Strands è un framework Python leggero e pronto per la produzione per costruire agenti AI. Caratteristiche principali:

• Leggero e personalizzabile: Ciclo di agente semplice che non ostacola il lavoro
• Pronto per la produzione: Osservabilità completa, tracciamento e opzioni di deployment per scalare
• Agnostico su modelli e provider: Supporta molti modelli diversi da vari provider
• Strumenti della community: Set potente di strumenti contribuiti dalla community
• Supporto multi-agente: Tecniche avanzate come team di agenti e agenti autonomi
• Modalità di interazione flessibili: Supporto conversazionale, streaming e non-streaming

Utilizzo

Genera un Agente Strands

Puoi generare un Agente Strands in Python in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - py#strands-agent
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Consiglio

Prima utilizza il generatore py#project per creare un progetto a cui aggiungere il tuo Agente Strands.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	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

Output del Generatore

Il generatore aggiungerà i seguenti file al tuo progetto Python esistente:

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (o nome personalizzato se specificato)

      • __init__.py Inizializzazione pacchetto Python
      • agent.py Definizione principale dell’agente con strumenti di esempio
      • main.py Punto d’ingresso per Bedrock AgentCore Runtime
      • agentcore_mcp_client.py Factory client utile per richiamare server MCP ospitati su Bedrock AgentCore Runtime
      • Dockerfile Punto d’ingresso per hostare il tuo agente (escluso se computeType è impostato su None)
  • pyproject.toml Aggiornato con le dipendenze Strands
  • project.json Aggiornato con i target di servizio dell’agente

Infrastruttura

Nota

Se hai selezionato None per computeType, il generatore non produrrà alcuna infrastruttura as-code.

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Nota

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Nota

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

Per il deployment del tuo Agente Strands, vengono generati i seguenti file:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts Costrutto CDK per deployare l’agente
        • Dockerfile Dockerfile pass-through usato dal costrutto CDK
  • Directorycore

    • Directoryagent-core

      • runtime.ts Costrutto CDK generico per deploy su Bedrock AgentCore Runtime

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf Modulo per deployare l’agente
  • Directorycore

    • Directoryagent-core

      • runtime.tf Modulo generico per deploy su Bedrock AgentCore Runtime

Lavorare con il Tuo Agente Strands

Aggiungere Strumenti

Gli strumenti sono funzioni che l’agente AI può chiamare per eseguire azioni. Il framework Strands utilizza un approccio semplice basato su decoratori per definire gli strumenti.

Puoi aggiungere nuovi strumenti nel file agent.py:

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calcola la somma di una lista di numeri"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Ottieni informazioni meteo per una città"""
    # Integrazione con l'API meteo qui
    return f"Meteo a {city}: Soleggiato, 25°C"

# Aggiungi strumenti all'agente
agent = Agent(
    system_prompt="Sei un assistente utile con accesso a vari strumenti.",
    tools=[calculate_sum, get_weather],
)

Il framework Strands gestisce automaticamente:

• Validazione dei tipi basata sugli type hint delle funzioni
• Generazione dello schema JSON per le chiamate agli strumenti
• Gestione errori e formattazione delle risposte

Utilizzare Strumenti Precostruiti

Strands fornisce una collezione di strumenti precostruiti tramite il pacchetto strands-tools:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="Sei un assistente utile.",
    tools=[current_time, http_request, file_read],
)

Configurazione del Modello

Di default, gli agenti Strands usano Claude 4 Sonnet, ma puoi personalizzare il provider del modello. Consulta la documentazione Strands sui provider di modelli per le opzioni di configurazione:

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)

Consumare Server MCP

Puoi aggiungere strumenti da server MCP al tuo agente Strands.

Per consumare server MCP creati con i generatori py#mcp-server o ts#mcp-server (o altri hostati su Bedrock AgentCore Runtime), viene generata per te una factory client in agentcore_mcp_client.py.

Puoi aggiornare il metodo get_agent in agent.py per creare client MCP e aggiungere strumenti. L’esempio seguente mostra come farlo con autenticazione IAM (SigV4):

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Ottieni regione e credenziali
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],
        )

Consiglio

Se il tuo server MCP target usa autenticazione JWT, puoi usare il metodo AgentCoreMCPClient.with_jwt_auth per creare il client.

Con l’esempio di autenticazione IAM sopra, dobbiamo configurare due cose nella nostra infrastruttura. Primo, aggiungere la variabile d’ambiente che il nostro agente consuma per l’ARN del Runtime AgentCore del server MCP, secondo concedere al nostro agente i permessi per richiamare il server MCP. Questo può essere ottenuto come segue:

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

# Server 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}/*"
      ]
    }
  ]
}

Approfondimenti

Per una guida più dettagliata sulla scrittura di agenti Strands, consulta la documentazione Strands.

Bedrock AgentCore Python SDK

Il generatore configura il Bedrock AgentCore Python SDK per gestire il contratto HTTP sottostante che gli agenti su AgentCore devono implementare.

Puoi trovare maggiori dettagli sulle capacità dell’SDK nella documentazione qui.

Nota

Poiché il generatore produce infrastruttura CDK o Terraform che gestisce il deployment del tuo agente, non è necessario utilizzare il bedrock-agentcore-starter-toolkit menzionato nella documentazione per deployare l’agente.

Eseguire il Tuo Agente Strands

Sviluppo Locale

Il generatore configura un target chiamato <your-agent-name>-serve, che avvia il tuo Agente Strands localmente per sviluppo e test.

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

Questo comando usa uv run per eseguire il tuo Agente Strands utilizzando il Bedrock AgentCore Python SDK.

Deploy dell’Agente Strands su Bedrock AgentCore Runtime

Infrastruttura as-Code

Se hai selezionato BedrockAgentCoreRuntime per computeType, viene generata l’infrastruttura CDK o Terraform rilevante che puoi usare per deployare il tuo Agente Strands su Amazon Bedrock AgentCore Runtime.

CDK

Viene generato un costrutto CDK per te, nominato in base al name scelto durante l’esecuzione del generatore, o <ProjectName>Agent di default.

Puoi usare questo costrutto CDK in un’applicazione CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Aggiungi l'agente al tuo stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Concedi permessi per richiamare i modelli pertinenti in bedrock
    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // Puoi limitare il sotto a specifici modelli usati
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

Terraform

Viene generato un modulo Terraform per te, nominato in base al name scelto durante l’esecuzione del generatore, o <ProjectName>-agent di default.

Puoi usare questo modulo Terraform in un progetto Terraform:

# Agente
module "my_project_agent" {
  # Percorso relativo al modulo generato in common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Concedi permessi per richiamare i modelli pertinenti in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

Nota

Quando fai il deploy su Bedrock AgentCore Runtime, devi assicurarti che i modelli foundation appropriati siano abilitati nel tuo account AWS. Di default, gli agenti Strands usano Claude 4 Sonnet, ma questo può essere personalizzato come descritto sopra.

Per abilitare l’accesso ai modelli in Amazon Bedrock, segui le istruzioni qui.

Attenzione

Docker è richiesto per buildare e deployare il tuo Agente Strands. Assicurati di aver installato e avviato Docker per evitare errori come:

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

Target Bundle e Docker

Per buildare il tuo Agente Strands per Bedrock AgentCore Runtime, viene aggiunto un target bundle al tuo progetto, che:

• Esporta le dipendenze Python in un file requirements.txt usando uv export
• Installa le dipendenze per la piattaforma target (aarch64-manylinux2014) usando uv pip install

Viene anche aggiunto un target docker specifico per il tuo Agente Strands, che:

• Builda un’immagine docker dal Dockerfile che esegue il tuo agente, secondo il contratto runtime di AgentCore

Consiglio

L’immagine docker è buildata usando un tag (esempio my-scope-my-project-agent:latest), referenziato dalla tua infrastruttura CDK o Terraform, permettendo al tuo Dockerfile di essere co-locato con il progetto del tuo Agente Strands.

Autenticazione

IAM

Di default, il tuo Agente Strands sarà protetto usando autenticazione IAM, semplicemente deployalo senza argomenti:

CDK

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

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

Puoi concedere l’accesso per richiamare il tuo agente su Bedrock AgentCore Runtime usando il metodo grantInvoke, per esempio:

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" {
  # Percorso relativo al modulo generato in common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Per concedere l’accesso a richiamare l’agente, dovrai aggiungere una policy come la seguente, referenziando l’output 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}/*"
  ]
}

Autenticazione Cognito JWT

Quanto segue dimostra come configurare l’autenticazione Cognito per il tuo agente.

CDK

Per configurare l’autenticazione JWT, puoi passare la proprietà authorizerConfiguration al tuo costrutto agente. Ecco un esempio che configura un user pool e client Cognito per proteggere l’agente:

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

Per configurare l’autenticazione JWT, puoi modificare il tuo modulo agente per configurare la variabile customJWTAuthorizer come segue:

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

  # Sostituisci con i tuoi ID user pool e client o esponili come variabili
  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
}

Osservabilità

Il tuo agente è configurato automaticamente con osservabilità usando AWS Distro for Open Telemetry (ADOT), configurando auto-strumentazione nel tuo Dockerfile.

Puoi trovare le tracce nella Console AWS CloudWatch, selezionando “GenAI Observability” nel menu. Nota che per popolare le tracce devi abilitare Transaction Search.

Per maggiori dettagli, consulta la documentazione AgentCore sull’osservabilità.