Agente Python Strands

Genera un Agente Strands in Python per costruire agenti AI con strumenti, e opzionalmente distribuiscilo su Amazon Bedrock AgentCore Runtime. Per impostazione predefinita, il generatore utilizza FastAPI per esporre un server HTTP. In alternativa, puoi scegliere il protocollo Agent-to-Agent (A2A) per l’interoperabilità con altri agenti compatibili A2A, o il protocollo AG-UI per l’integrazione diretta con il frontend tramite CopilotKit.

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.
protocol	string	HTTP	Il protocollo server per il tuo Strands Agent. HTTP espone un server HTTP FastAPI. A2A espone un server con protocollo Agent-to-Agent. AG-UI espone un server con protocollo Agent-User Interaction per l'integrazione diretta con il frontend.
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. I file generati dipendono dal protocol scelto:

Protocollo HTTP (predefinito)

• 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 FastAPI 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

Protocollo A2A

Quando protocol è impostato su A2A, il punto d’ingresso utilizza lo Strands A2A Server invece di FastAPI:

• 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 server A2A
      • 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

Protocollo AG-UI

Quando protocol è impostato su AG-UI, il punto d’ingresso utilizza l’integrazione ag-ui-strands, che espone il tuo agente tramite il protocollo AG-UI per l’integrazione diretta con il frontend tramite CopilotKit:

• 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 server AG-UI usando ag-ui-strands
      • Dockerfile Punto d’ingresso per ospitare il tuo agente (escluso se computeType è impostato a None)
  • pyproject.toml Aggiornato con le dipendenze Strands e AG-UI
  • project.json Aggiornato con i target di servizio dell’agente

Connetti a un sito web React

Gli agenti AG-UI possono essere connessi a un frontend React utilizzando il generatore connection, che configurerà i componenti CopilotKit per un’esperienza di chat ricca.

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

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.

Protocollo

Il protocollo del server del tuo agente determina come comunica. Tutte le opzioni sono servite da FastAPI — il punto d’ingresso è diverso:

• HTTP (predefinito): Un server FastAPI standard con un endpoint personalizzato /invocations, CORS e streaming. Ideale per integrazioni client personalizzate.
• A2A: Lo Strands A2A Server montato su un’app FastAPI. Ideale quando il tuo agente deve essere individuabile e invocabile da altri agenti compatibili A2A.
• AG-UI: L’integrazione ag-ui-strands, che espone il protocollo AG-UI tramite SSE. Ideale per l’integrazione diretta con il frontend tramite CopilotKit in un sito web React.

Tutti i protocolli espongono /ping per il contratto di controllo dello stato del runtime AgentCore. Gli agenti A2A ascoltano sulla porta 9000; gli agenti HTTP e AG-UI ascoltano sulla porta 8080. Il Dockerfile e l’infrastruttura generati sono configurati per te.

Server FastAPI (protocollo HTTP)

Il server HTTP 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 messaggio.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

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

L’ID di sessione viene estratto dall’header HTTP x-amzn-bedrock-agentcore-runtime-session-id, coerentemente con il contratto di sessione di Bedrock AgentCore Runtime. Se l’header non viene fornito, viene generato un UUID casuale come fallback.

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.

Server A2A (protocollo A2A)

Quando protocol=A2A, il main.py generato monta A2AServer.to_fastapi_app() su un’app FastAPI padre che espone anche /ping. Quando distribuito su AgentCore, il punto d’ingresso risolve l’ARN pubblico del runtime da AppConfig e lo pubblicizza nella scheda dell’agente.

La maggior parte degli utenti non avrà bisogno di modificare questo file — modifica agent.py per cambiare strumenti o il prompt di sistema. Il server A2A popola la scheda dell’agente (/.well-known/agent-card.json) dal name e dalla description del costruttore Agent.

Server AG-UI (protocollo AG-UI)

Quando protocol=AG-UI, il main.py generato avvolge il tuo Strands Agent in un ag_ui_strands.StrandsAgent e crea un’app FastAPI tramite create_strands_app(). L’app risultante espone un singolo endpoint POST che trasmette eventi AG-UI tramite Server-Sent Events (SSE), oltre a /ping per il controllo dello stato del runtime AgentCore.

La maggior parte degli utenti non avrà bisogno di modificare questo file — modifica agent.py per cambiare strumenti o il prompt di sistema.

Connessione a un sito web React

Gli agenti AG-UI sono progettati per essere consumati direttamente da un frontend. Utilizza il generatore connection per collegare il tuo sito web React all’agente con un provider CopilotKit e un client AG-UI HttpAgent.

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) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

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

Permessi per i Modelli Bedrock

Il costrutto agent generato concede per impostazione predefinita il permesso di invocare tutti i modelli fondazionali e i profili di inferenza Bedrock (bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream su arn:aws:bedrock:*:*:foundation-model/* e arn:aws:bedrock:*:*:inference-profile/*).

Potresti voler limitare questo ai modelli specifici utilizzati dal tuo agent. Puoi trovare il modello predefinito utilizzato dagli agent Strands nella documentazione Strands; consulta la guida ai provider di modelli Strands per configurare un modello diverso.

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-manylinux_2_28) usando uv pip install

Viene anche aggiunto un target docker specifico per il tuo Strands Agent, che copia il Dockerfile e gli artefatti bundle in una directory di contesto docker. Questo co-localizza il Dockerfile con l’output costruito, permettendo a CDK di costruire l’immagine Docker direttamente usando AgentRuntimeArtifact.fromAsset.

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 '{"message": "what is 3 + 5?"}' \
  -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 '{"message": "what is 3 + 5?"}' \
-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 '{"message": "what is 3 + 5?"}' \
  -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

Browser / Sito Web React

Per invocare il tuo Strands Agent da un sito web React, puoi utilizzare il generatore connection, che configura automaticamente un client con l’autenticazione corretta (IAM o Cognito).

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.

Invocare un Agente A2A come Strumento

Per delegare lavoro da questo agente a un agente A2A remoto (sia TypeScript che Python), utilizza il generatore connection. Fornisce un client autenticato con SigV4 per l’agente target e trasforma tramite AST il file agent.py di questo agente per registrare l’agente A2A remoto come delegato decorato con @tool.

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.