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

Prerequisito del progetto

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	-	Il progetto a cui aggiungere lo Strands Agent
computeType	string	BedrockAgentCoreRuntime	Il tipo di compute per ospitare il tuo Strands Agent.
name	string	-	Il nome del tuo Strands Agent (predefinito: agent)
auth	string	IAM	Il metodo utilizzato per autenticarsi con il tuo Strands Agent. Scegli tra IAM (predefinito) o Cognito.
iacProvider	string	Inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

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
      • init.py Configurazione applicazione FastAPI con middleware CORS e gestione errori
      • agent.py Definizione principale dell’agente con strumenti di esempio
      • main.py Punto d’ingresso per 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

Deploy serverless

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

Progetto generato

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

Progetto generato

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

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 puoi utilizzare il generatore connection.

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 - connection
5. Compila i parametri richiesti
6. Clicca su Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Consulta la guida del generatore connection per dettagli su come viene configurata la connessione.

Per altri server MCP, consulta la Documentazione Strands.

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.

Organizzazione del codice

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, il generatore fornisce JsonStreamingResponse che serializza automaticamente i modelli Pydantic in formato JSON Lines (application/jsonl). Questo formato è compatibile con la specifica di streaming di OpenAPI 3.2 e funziona perfettamente con il client TypeScript generato.

Di default, l’agente produce oggetti StreamChunk contenenti il testo di risposta dell’agente:

class StreamChunk(BaseModel):
    content: str

Puoi personalizzare il modello StreamChunk per adattarlo alle tue esigenze:

from pydantic import BaseModel

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

Limitazione streaming FastAPI

Nota che poiché FastAPI attualmente non supporta la generazione di una specifica OpenAPI per le risposte in streaming, dobbiamo impostare esplicitamente il modello di risposta per ogni operazione di streaming, cioè:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

Esiste una richiesta di funzionalità aperta per il supporto nativo in FastAPI.

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.

Infrastructure as Code

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

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

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

Infrastructure as Code

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

CDK

Viene generato un costrutto CDK per il tuo agent, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>Agent per impostazione predefinita.

Puoi utilizzare questo costrutto CDK in un’applicazione CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.addToRolePolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: [
          'arn:aws:bedrock:*:*:foundation-model/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

Costrutto CDK Alpha

Questo costrutto utilizza il modulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Viene generato un modulo Terraform per te, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>-agent per impostazione predefinita.

Puoi utilizzare questo modulo terraform in un progetto Terraform:

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

Docker richiesto

Docker è richiesto per compilare 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.

Autenticazione

Il generatore fornisce un’opzione auth per configurare l’autenticazione per il tuo Strands Agent. Puoi scegliere tra l’autenticazione IAM (predefinita) o Cognito durante la generazione del tuo agent.

IAM

Per impostazione predefinita, il tuo Strands Agent sarà protetto utilizzando l’autenticazione IAM, semplicemente distribuiscilo senza alcun argomento:

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 agent su Bedrock AgentCore Runtime utilizzando il metodo grantInvokeAccess, 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.grantInvokeAccess(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Per concedere l’accesso per invocare il tuo agent, dovrai aggiungere una policy come la seguente, facendo riferimento all’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

Quando selezioni l’autenticazione Cognito, il generatore configura l’agent per utilizzare Cognito per l’autenticazione.

CDK

Il costrutto generato accetta una prop identity che configura l’autenticazione Cognito:

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

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

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

Il costrutto UserIdentity può essere generato utilizzando il generatore ts#react-website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.

Terraform

Il modulo generato accetta le variabili user_pool_id e user_pool_client_ids per l’autenticazione Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Provider OIDC personalizzati

Se hai bisogno di autenticazione JWT personalizzata con un provider OIDC non-Cognito, puoi modificare direttamente il costrutto CDK o il modulo Terraform generato per il tuo agent. Nota che il generatore di connessioni supporterà solo l’autenticazione IAM o Cognito.

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

Tag immagine Docker

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.

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à.

Invocare il tuo Strands Agent

Invocare il Server Locale

Per invocare un Agente in esecuzione localmente tramite il target <your-agent-name>-serve, puoi inviare una semplice richiesta POST a /invocations sulla porta su cui il tuo agente locale è in esecuzione. Ad esempio, con curl:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -H "Content-Type: application/json"

Flag di streaming Curl

L’argomento -N dato a curl disabilita il buffering dello stream di output, così puoi vedere la risposta in streaming in tempo reale.

Invocare l’Agente Distribuito

Per invocare il tuo Agent distribuito su Bedrock AgentCore Runtime, puoi inviare una richiesta POST all’endpoint dataplane di Bedrock AgentCore Runtime con il tuo ARN runtime codificato in URL.

Puoi ottenere l’ARN runtime dalla tua infrastruttura come segue:

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

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

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

L’ARN avrà il seguente formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Puoi quindi codificare in URL l’ARN sostituendo : con %3A e / con %2F.

Console del browser

Questo è semplice in una console del browser o in un REPL Node utilizzando il metodo integrato encodeURIComponent:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

L’URL dataplane di Bedrock AgentCore Runtime per invocare l’agent è il seguente:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

Il modo esatto per invocare questo URL dipende dal metodo di autenticazione utilizzato.

Autenticazione IAM

Per l’Autenticazione IAM, la richiesta deve essere firmata usando AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock
-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
-H 'Content-Type: application/json'

Clicca qui per maggiori dettagli sulla configurazione del comando acurl sopra

Autenticazione JWT / Cognito

Per l’Autenticazione Cognito, passa il Token di Accesso Cognito nell’header Authorization:

curl -N -X POST 'https://bedrock
-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

Puoi ottenere il token di accesso usando il comando cognito-idp admin-initiate-auth dell’AWS CLI, ad esempio:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text