Agente Python Strands

Genera un Agente Strands in Python per costruire agenti AI con strumenti, e opzionalmente distribuiscilo 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 agenti semplice che non ostacola il lavoro
• Pronto per la produzione: Osservabilità completa, tracciamento e opzioni di distribuzione scalabili
• 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à interattive 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 Strands Agent.

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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 invocare server MCP ospitati su Bedrock AgentCore Runtime
      • Dockerfile Punto d’ingresso per ospitare il tuo agente (escluso se computeType è impostato a 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 la distribuzione del tuo Strands Agent, vengono generati i seguenti file:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

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

    • Directoryagent-core

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

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

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

    • Directoryagent-core

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

Lavorare con il tuo Strands Agent

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 al tuo 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 hint di tipo delle funzioni
• Generazione dello schema JSON per le chiamate agli strumenti
• Gestione errori e formattazione delle risposte

Utilizzare Strumenti Predefiniti

Strands fornisce una collezione di strumenti predefiniti 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. Vedi 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)

Utilizzare Server MCP

Puoi aggiungere strumenti da server MCP al tuo agente Strands.

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

Puoi aggiornare il tuo 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, e secondo, concedere i permessi al nostro agente per invocare 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

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

Approfondimenti

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

Server FastAPI

Il generatore utilizza FastAPI per creare il server HTTP per il tuo Strands Agent. FastAPI fornisce un framework web moderno e veloce per costruire API con Python, con documentazione API automatica e validazione dei tipi.

Il server generato include:

• Configurazione dell’applicazione FastAPI con middleware CORS
• Middleware per la gestione degli errori
• Generazione dello schema OpenAPI
• Endpoint di controllo dello stato (/ping)
• Endpoint di invocazione dell’agente (/invocations)

Personalizzare Input e Output di Invocazione con Pydantic

L’endpoint di invocazione dell’agente utilizza modelli Pydantic per definire e validare gli schemi di richiesta e risposta. Puoi personalizzare questi modelli in main.py per adattarli ai requisiti del tuo agente.

Definire Modelli di Input

Il modello InvokeInput predefinito accetta un prompt e un ID di sessione.

from pydantic import BaseModel

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

Puoi estendere questo modello per includere qualsiasi campo aggiuntivo di cui il tuo agente ha bisogno.

Attenzione

Probabilmente vorrai astrarre parte o tutto l’ID di sessione dal chiamante se gli utenti devono invocare il tuo agente direttamente. Ad esempio, potresti usare l’ID utente autenticato come parte dell’ID di sessione.

Vale anche la pena notare che a seconda del tuo caso d’uso potresti dover implementare l’autorizzazione per le sessioni, ad esempio assicurandoti che gli utenti possano accedere solo alle proprie sessioni e non a quelle di altri utenti.

Definire Modelli di Output

Per le risposte in streaming, l’annotazione del tipo di ritorno sul tuo endpoint corrisponde al tipo di ogni valore prodotto dalla tua funzione generatore. Di default, l’agente produce stringhe contenenti il testo di risposta dell’agente mentre viene trasmesso in streaming da 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")

Puoi definire un modello Pydantic per produrre dati strutturati invece:

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")

Bedrock AgentCore Python SDK

Il generatore include una dipendenza sul Bedrock AgentCore Python SDK per le costanti PingStatus. Se desiderato, è semplice utilizzare BedrockAgentCoreApp invece di FastAPI, tuttavia nota che la type-safety viene persa.

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

Nota

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

Eseguire il tuo Strands Agent

Sviluppo Locale

Il generatore configura un target chiamato <your-agent-name>-serve, che avvia il tuo Strands Agent 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 Strands Agent utilizzando il Bedrock AgentCore Python SDK.

Distribuire il tuo Strands Agent 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 distribuire il tuo Strands Agent 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 invocare i modelli rilevanti 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:

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

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

Nota

Quando distribuisci 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 è necessario per costruire e distribuire il tuo Strands Agent. 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 costruire il tuo Strands Agent 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 Strands Agent, che:

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

Consiglio

L’immagine docker è costruita usando un tag (ad 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 Strands Agent.

Autenticazione

IAM

Di default, il tuo Strands Agent sarà protetto con autenticazione IAM, distribuiscilo semplicemente 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 invocare il tuo agente su Bedrock AgentCore Runtime usando il metodo grantInvoke, ad 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

# Agent
module "my_project_agent" {
  # Percorso relativo al modulo generato nel progetto common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Per concedere l’accesso a invocare il tuo 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 JWT con Cognito

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 agent. 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 agent 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 dovrai abilitare Transaction Search.

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