Salta ai contenuti
@aws/nx-plugin
Blog

Agente TypeScript Strands

Filter this guidePick generator option values to hide sections that don't apply.

Genera un TypeScript Agent per la creazione di agenti AI con strumenti e, facoltativamente, distribuiscilo su Amazon Bedrock AgentCore Runtime. Per impostazione predefinita, il generatore utilizza tRPC su WebSocket per sfruttare il supporto di streaming bidirezionale di AgentCore per una comunicazione in tempo reale e type-safe. In alternativa, puoi scegliere il protocollo Agent-to-Agent (A2A) per l’interoperabilità con altri agenti compatibili con A2A, o il protocollo AG-UI per l’integrazione diretta con il frontend tramite CopilotKit.

Cos’è Strands?

Sezione intitolata “Cos’è Strands?”

Strands è un framework leggero per la creazione di agenti AI. Le caratteristiche principali includono:

  • Leggero e personalizzabile: Un semplice ciclo di agente che non ti ostacola
  • Pronto per la produzione: Completa osservabilità, tracciamento e opzioni di distribuzione per la scalabilità
  • Agnostico rispetto a modello e provider: Supporta molti modelli diversi da vari provider
  • Strumenti guidati dalla community: Potente set 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

Sezione intitolata “Utilizzo”

Generare uno Agent

Sezione intitolata “Generare uno Agent”

Puoi generare un TypeScript Agent in due modi:

  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 - ts#agent
  5. Compila i parametri richiesti
    • Clicca su Generate

    Opzioni

    Sezione intitolata “Opzioni”
    ParametroTipoPredefinitoDescrizione
    project Obbligatoriostring-Il progetto a cui aggiungere lo Agent
    framework strandsstrandsL'SDK dell'agente da utilizzare.
    name string-Il nome del tuo Agent (predefinito: agent)
    auth iam | cognitoiamIl metodo utilizzato per autenticare con il tuo Agent. Applicabile solo quando infra è impostato (ignorato quando infra è none).
    protocol http | a2a | ag-uihttpIl protocollo del server per il tuo Agent. HTTP espone un server tRPC/WebSocket. A2A espone un server con protocollo Agent-to-Agent. AG-UI espone un server con protocollo AG-UI per l'integrazione diretta del frontend con CopilotKit.
    iac inherit | cdk | terraforminheritIl provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
    infra agentcore | noneagentcoreIl tipo di infrastruttura per ospitare il tuo Agent.
    preferInstallDependencies booleantrueSe preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

    Output del Generatore

    Sezione intitolata “Output del Generatore”

    Il generatore aggiungerà i seguenti file al tuo progetto TypeScript esistente. I file generati dipendono dal protocol scelto:

    protocol = http

    Protocollo HTTP (predefinito)

    Sezione intitolata “Protocollo HTTP (predefinito)”
    • Directoryyour-project/
      • Directorysrc/
        • Directoryagent/ (o nome personalizzato se specificato)
          • index.ts Punto di ingresso per Bedrock AgentCore Runtime (server tRPC/WebSocket)
          • init.ts Inizializzazione tRPC
          • router.ts Router tRPC con procedure dell’agente
          • agent.ts Definizione principale dell’agente con strumenti di esempio
          • client.ts Client fornito per invocare il tuo agente
          • agent-core-trpc-client.ts Factory del client per connettersi agli agenti su AgentCore Runtime
          • Dockerfile Punto di ingresso per l’hosting del tuo agente (escluso quando infra è impostato su None)
      • package.json Aggiornato con le dipendenze di Strands
      • project.json Aggiornato con i target di serve dell’agente
    protocol = a2a

    Protocollo A2A

    Sezione intitolata “Protocollo A2A”

    Il punto di ingresso utilizza il Strands A2A Express Server invece di tRPC:

    • Directoryyour-project/
      • Directorysrc/
        • Directoryagent/ (o nome personalizzato se specificato)
          • index.ts Punto di ingresso del server A2A Express
          • agent.ts Definizione principale dell’agente con strumenti di esempio
          • Dockerfile Punto di ingresso per l’hosting del tuo agente (escluso quando infra è impostato su None)
      • package.json Aggiornato con le dipendenze di Strands ed Express
      • project.json Aggiornato con i target di serve dell’agente
    protocol = ag-ui

    Protocollo AG-UI

    Sezione intitolata “Protocollo AG-UI”

    Il punto di ingresso utilizza @ag-ui/aws-strands per esporre l’agente tramite il protocollo AG-UI (SSE su POST), compatibile con CopilotKit:

    • Directoryyour-project/
      • Directorysrc/
        • Directoryagent/ (o nome personalizzato se specificato)
          • index.ts Punto di ingresso del server AG-UI (Express + SSE)
          • agent.ts Definizione principale dell’agente con strumenti di esempio
          • Dockerfile Punto di ingresso per l’hosting del tuo agente (escluso quando infra è impostato su None)
      • package.json Aggiornato con le dipendenze di Strands e AG-UI
      • project.json Aggiornato con i target di serve dell’agente

    Infrastruttura

    Sezione intitolata “Infrastruttura”
    infra = agentcore

    Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac 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:

    • 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

    Per distribuire il tuo Agent, vengono generati i seguenti file:

    • Directorypackages/common/constructs/src
      • Directoryapp
        • Directoryagents
          • Directory<project-name>
            • <project-name>.ts Costrutto CDK per distribuire il tuo agente
    infra = none

    Se hai selezionato None per infra, non vengono generati costrutti CDK o moduli Terraform — lo Agent può essere eseguito solo localmente. L’opzione auth viene ignorata in questa modalità poiché non esiste un endpoint ospitato da autenticare.

    Architecture

    Sezione intitolata “Architecture”

    Quando viene distribuito su Bedrock AgentCore Runtime, l’agent viene compilato in un’immagine container, caricato su Amazon ECR ed eseguito in AgentCore Runtime. I client invocano l’endpoint del piano dati di AgentCore Runtime, che inoltra le richieste al tuo agent. L’agent chiama Amazon Bedrock per l’inferenza del modello e può invocare strumenti, server MCP o API downstream.

    ClientECRAgent(AgentCore Runtime)Bedrock(Model Inference)CloudWatch(Logs, Metrics) Containerimage InvokeModel

    Lavorare con il Tuo Agent

    Sezione intitolata “Lavorare con il Tuo Agent”

    Protocollo

    Sezione intitolata “Protocollo”

    Il protocollo del server del tuo agente determina come comunica. Puoi scegliere tra:

    • HTTP (predefinito): Utilizza tRPC su WebSocket per una comunicazione in tempo reale e type-safe. Ideale per integrazioni client personalizzate e controllo granulare sull’API dell’agente.
    • A2A: Utilizza il protocollo Agent-to-Agent (A2A) per la comunicazione inter-agente standardizzata. Ideale quando il tuo agente deve essere rilevabile e invocabile da altri agenti compatibili con A2A.
    • AG-UI: Utilizza il protocollo AG-UI (SSE su POST) tramite @ag-ui/aws-strands per l’integrazione diretta con il frontend tramite CopilotKit. Ideale quando desideri un’interfaccia utente di chat ricca con streaming, visualizzazione delle chiamate agli strumenti e gestione dello stato.

    Il protocollo è impostato nell’infrastruttura CDK/Terraform e il codice dell’applicazione viene generato di conseguenza.

    protocol = http

    tRPC su WebSocket (protocollo HTTP)

    Sezione intitolata “tRPC su WebSocket (protocollo HTTP)”

    Il TypeScript Agent utilizza tRPC su WebSocket, sfruttando il supporto di streaming bidirezionale di AgentCore per abilitare la comunicazione in tempo reale e type-safe tra i client e il tuo agente.

    Poiché tRPC supporta le procedure Query, Mutation e Subscription su WebSocket, puoi definire un numero qualsiasi di procedure. Per impostazione predefinita, viene definita per te una singola procedura di subscription denominata invoke in router.ts.

    Aggiungere Strumenti

    Sezione intitolata “Aggiungere Strumenti”

    Gli strumenti sono funzioni che l’agente AI può chiamare per eseguire azioni. Puoi aggiungere nuovi strumenti nel file agent.ts:

    import { Agent, tool } from '@strands-agents/sdk';
    import { z } from 'zod';
    

    const letterCounter = tool({
      name: 'letter_counter',
      description: 'Count occurrences of a specific letter in a word',
      inputSchema: z.object({
        word: z.string().describe('The input word to search in'),
        letter: z.string().length(1).describe('The specific letter to count'),
      }),
      callback: (input) => {
        const { word, letter } = input;
        const count = word.toLowerCase().split(letter.toLowerCase()).length - 1;
        return `The letter '${letter}' appears ${count} time(s) in '${word}'`;
      },
    });
    

    // Add tools to your agent
    export const getAgent = async (sessionId: string) => {
      return new Agent({
        systemPrompt: 'You are a helpful assistant with access to various tools.',
        tools: [letterCounter],
      });
    };

    Il framework Strands gestisce automaticamente:

    • Validazione dell’input utilizzando schemi Zod
    • Generazione dello schema JSON per la chiamata degli strumenti
    • Gestione degli errori e formattazione delle risposte

    Configurazione del Modello

    Sezione intitolata “Configurazione del Modello”

    Per impostazione predefinita, gli agenti Strands utilizzano Claude 4 Sonnet, ma puoi facilmente passare da un provider di modelli all’altro:

    import { Agent } from '@strands-agents/sdk';
    import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
    import { OpenAIModel } from '@strands-agents/sdk/models/openai';
    

    // Use Bedrock
    const bedrockModel = new BedrockModel({
      modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
    });
    let agent = new Agent({ model: bedrockModel });
    let response = await agent.invoke('What can you help me with?');
    

    // Alternatively, use OpenAI by just switching model provider
    const openaiModel = new OpenAIModel({
      apiKey: process.env.OPENAI_API_KEY,
      modelId: 'gpt-4o',
    });
    agent = new Agent({ model: openaiModel });
    response = await agent.invoke('What can you help me with?');

    Consulta la documentazione di Strands sui provider di modelli per ulteriori opzioni di configurazione.

    Consumare Server MCP

    Sezione intitolata “Consumare Server MCP”

    Puoi aggiungere strumenti dai server MCP al tuo agente Strands.

    Per consumare i Server MCP che hai creato utilizzando i generatori py#mcp-server o ts#mcp-server puoi utilizzare il generatore connection.

    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
      • Clicca su Generate

      Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

      Per altri server MCP, consulta la Documentazione di Strands.

      Altro

      Sezione intitolata “Altro”

      Per una guida più approfondita sulla scrittura di agenti Strands, fai riferimento alla documentazione di Strands.

      protocol = a2a

      Server A2A (protocollo A2A)

      Sezione intitolata “Server A2A (protocollo A2A)”

      L’index.ts generato monta il Strands A2A Express Server su un’app Express in modo che l’agente generato esponga gli endpoint del protocollo A2A insieme a un health check /ping. Quando distribuito su AgentCore, il punto di 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.ts per cambiare gli strumenti o il prompt di sistema. Gli agenti A2A ascoltano sulla porta 9000 (contro 8080 per HTTP), per cui il Dockerfile e l’infrastruttura generati sono già configurati.

      protocol = ag-ui

      Server AG-UI (protocollo AG-UI)

      Sezione intitolata “Server AG-UI (protocollo AG-UI)”

      L’index.ts generato avvolge il tuo Strands Agent in uno @ag-ui/aws-strands StrandsAgent e crea un’app Express tramite createStrandsApp(). 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.

      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.

      La maggior parte degli utenti non avrà bisogno di modificare index.ts — modifica agent.ts per cambiare gli strumenti o il prompt di sistema. Gli agenti AG-UI ascoltano sulla porta 8080 (come HTTP), per cui il Dockerfile e l’infrastruttura generati sono già configurati.

      Eseguire il Tuo Agent

      Sezione intitolata “Eseguire il Tuo Agent”

      Sviluppo Locale

      Sezione intitolata “Sviluppo Locale”

      Per eseguire il tuo Agent (e tutto ciò che è connesso ad esso) localmente, usa il target dev del progetto:

      Terminal window
      pnpm nx dev your-project

      Se hai aggiunto più componenti al tuo progetto (agenti, server MCP, ecc.), questo li avvia tutti. Per eseguire solo questo agente, usa il suo target <your-agent-name>-dev:

      Terminal window
      pnpm nx agent-dev your-project

      Questo utilizza tsx --watch per riavviare automaticamente il server quando i file cambiano. L’agente sarà disponibile su http://localhost:8081 (o la porta assegnata se hai più agenti).

      Chatta con il Tuo Agente

      Sezione intitolata “Chatta con il Tuo Agente”

      Il generatore configura un target Nx <your-agent-name>-chat che ti porta in una chat interattiva da terminale con il tuo agente.

      Il target chat funziona in modo autonomo. Per impostazione predefinita si connette al tuo agente in esecuzione locale, quindi avvia prima il target <your-agent-name>-dev dell’agente (in un terminale separato):

      Terminal window
      pnpm nx agent-dev your-project

      Quindi, in un altro terminale, avvia la chat:

      Terminal window
      pnpm nx run your-project:agent-chat

      Il generatore emette un scripts/<your-agent-name>/chat.ts per ogni protocollo. Puoi personalizzarlo mentre evolvi la forma di input dell’agente. Si connette all’agente locale per impostazione predefinita, o al tuo agente distribuito quando è impostato RUNTIME_CONFIG_APP_ID (vedi Chatta con il tuo agente distribuito di seguito).

      infra = agentcore

      Chat with your deployed agent

      Sezione intitolata “Chat with your deployed agent”

      Per chattare con il tuo agente distribuito su Bedrock AgentCore, imposta la variabile d’ambiente RUNTIME_CONFIG_APP_ID sull’id dell’applicazione AppConfig della distribuzione (output come RuntimeConfigApplicationId dallo stack distribuito). Lo script di chat risolve l’ARN del runtime del tuo agente dalla configurazione del runtime e si connette all’endpoint distribuito:

      Per gli agenti autenticati con IAM, le richieste sono firmate con SigV4 utilizzando le tue credenziali AWS predefinite. Assicurati che l’ambiente abbia credenziali AWS con il permesso di invocare il runtime:

      Terminal window
      RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat
      infra = agentcore

      Distribuire il Tuo Agent su Bedrock AgentCore Runtime

      Sezione intitolata “Distribuire il Tuo Agent su Bedrock AgentCore Runtime”

      Infrastructure as Code

      Sezione intitolata “Infrastructure as Code”

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

      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');
        }
      }

      Autenticazione

      Sezione intitolata “Autenticazione”

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

      IAM

      Sezione intitolata “IAM”

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

      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);
        }
      }

      Autenticazione Cognito

      Sezione intitolata “Autenticazione Cognito”

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

      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#website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.

      Target Bundle

      Sezione intitolata “Target Bundle”

      Il generatore configura automaticamente un target bundle che utilizza Rolldown per creare un pacchetto di distribuzione:

      Terminal window
      pnpm nx bundle <project-name>

      La configurazione di Rolldown si trova in rolldown.config.ts, con un’entry per bundle da generare. Rolldown gestisce la creazione di più bundle in parallelo se definiti.

      Il target bundle utilizza index.ts come punto di ingresso per il server WebSocket da ospitare su Bedrock AgentCore Runtime.

      Target Docker

      Sezione intitolata “Target Docker”

      Il generatore configura un target <your-agent-name>-docker che copia il Dockerfile dalla directory sorgente del tuo agente nella directory di output del bundle. Questo co-localizza il Dockerfile con gli artefatti in bundle, consentendo a CDK di costruire l’immagine Docker direttamente utilizzando AgentRuntimeArtifact.fromAsset.

      Viene generato anche un target docker che prepara il contesto docker per tutti gli agenti se ne hai definiti più di uno.

      Scansione delle Immagini

      Sezione intitolata “Scansione delle Immagini”

      L’immagine Docker creata per questo progetto può essere scansionata alla ricerca di vulnerabilità utilizzando Trivy, eseguito dall’immagine Trivy ospitata su ECR.

      Un target trivy viene aggiunto al progetto che scansiona l’immagine creata e termina con codice di uscita non-zero se viene trovata qualsiasi vulnerabilità di gravità HIGH o CRITICAL. Il Dockerfile generato utilizza un’immagine base senza vulnerabilità risolvibili note di queste gravità al momento della generazione e aggiorna gli strumenti inclusi (come npm) per mantenerla tale.

      La scansione utilizza lo stesso motore di container della build dell’immagine (docker o finch), quindi non sono necessari strumenti aggiuntivi. Poiché la scansione viene rieseguita solo quando l’immagine cambia, un’immagine non modificata non viene scansionata nuovamente. Lo script root trivy fornito scansiona ogni immagine nel workspace:

      Terminal window
      pnpm trivy

      Soppressione dei Risultati di Trivy

      Sezione intitolata “Soppressione dei Risultati di Trivy”

      Potrebbero esserci casi in cui si desidera sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e si è valutato il rischio come accettabile.

      Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella radice del progetto (cioè accanto al file project.json):

      .trivyignore
      # node-tar arbitrary file write - not exploitable in our usage
      CVE-2024-XXXXX

      Per maggiori dettagli sul filtraggio dei risultati, consulta la documentazione sul filtraggio di Trivy.

      Osservabilità

      Sezione intitolata “Osservabilità”

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

      Puoi trovare le tracce nella Console AWS di CloudWatch, selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate dovrai abilitare Transaction Search.

      Per maggiori dettagli, fai riferimento alla documentazione di AgentCore sull’osservabilità.

      Invocare il Tuo Agent

      Sezione intitolata “Invocare il Tuo Agent”

      La comunicazione dell’agente viene trasmessa tramite tRPC su WebSocket. Pertanto, si consiglia di utilizzare la factory del client type-safe generata in client.ts.

      protocol = http

      Invocare il Server Locale

      Sezione intitolata “Invocare il Server Locale”

      Puoi invocare un agente in esecuzione localmente utilizzando il metodo factory .local dalla factory del client.

      Puoi, ad esempio, creare un file denominato scripts/test.ts nel tuo workspace che importa il client:

      scripts/test.ts
      import { AgentClient } from '../packages/<project>/src/agent/client.js';
      

      const client = AgentClient.local({ url: 'http://localhost:8081/ws' });
      

      client.invoke.subscribe({ message: 'what is 1 plus 1?' }, { onData: console.log });

      Invocare l’Agente Distribuito

      Sezione intitolata “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:

      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,
          });
        }
      }

      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.

      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.

      NodeJS

      Sezione intitolata “NodeJS”

      Il file client.ts generato include una factory del client type-safe che può essere utilizzata per invocare il tuo agente distribuito.

      Autenticazione IAM
      Sezione intitolata “Autenticazione IAM”

      Puoi invocare il tuo agente distribuito passando il suo ARN al metodo factory withIamAuth:

      import { AgentClient } from './agent/client.js';
      

      const client = AgentClient.withIamAuth({
        agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
      });
      

      client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
        onData: (message) => console.log(message),
        onError: (error) => console.error(error),
        onComplete: () => console.log('Done'),
      });

      Browser / Sito Web React

      Sezione intitolata “Browser / Sito Web React”

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

      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
        • Clicca su Generate

        Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

        protocol = a2a

        Invocare un Agente A2A come Strumento

        Sezione intitolata “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 di destinazione e trasforma tramite AST l’agent.ts di questo agente per registrare l’agente A2A remoto come tool di Strands.

        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
          • Clicca su Generate

          Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

          protocol = ag-ui

          Invocare un Agente AG-UI

          Sezione intitolata “Invocare un Agente AG-UI”

          Per invocare il tuo agente AG-UI da un sito web React, utilizza il generatore connection, che configura un client CopilotKit configurato per il tuo agente distribuito con l’autenticazione corretta (IAM o Cognito).

          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
            • Clicca su Generate

            Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

            Proteggere il Tuo Agente

            Sezione intitolata “Proteggere il Tuo Agente”

            Gli agent agiscono su input non attendibili e possono eseguire azioni reali attraverso i loro strumenti, quindi vale la pena considerare la sicurezza fin dall’inizio. Le seguenti pratiche si applicano all’agent generato.

            Tratta input e output del modello come non attendibili

            Sezione intitolata “Tratta input e output del modello come non attendibili”

            I prompt possono contenere istruzioni avversarie (prompt injection) e l’output del modello è non deterministico — nessuno dei due dovrebbe essere considerato attendibile nella logica sensibile alla sicurezza:

            • Definisci schemi di input rigorosi per i tuoi strumenti, come nello strumento di esempio generato. Vincola i valori a ciò di cui lo strumento ha effettivamente bisogno (enum, limiti di lunghezza, intervalli numerici) piuttosto che accettare stringhe in formato libero.
            • Non passare mai l’output del modello direttamente in comandi shell, query SQL, valutazione di codice o HTML renderizzato senza validazione o codifica.
            • Applica controlli di autorizzazione nei tuoi strumenti e servizi downstream — non fare affidamento sul prompt di sistema per impedire al modello di utilizzare in modo improprio uno strumento a cui ha accesso.

            Le guide Prompt Engineering e IA Responsabile di Strands spiegano come scrivere prompt di sistema robusti e attenti alla sicurezza.

            Limita rigorosamente i permessi degli strumenti

            Sezione intitolata “Limita rigorosamente i permessi degli strumenti”

            Concedi al ruolo IAM dell’agent solo i permessi di cui i suoi strumenti hanno bisogno. I costrutti CDK e i moduli Terraform forniti espongono metodi grant* e policy con ambito limitato per questo scopo — ad esempio concedendo a un agent l’accesso per invocare un’API specifica piuttosto che allegare policy gestite ampie. Quando uno strumento agisce per conto di un utente, preferisci autorizzare l’azione utilizzando l’identità dell’utente chiamante (passata attraverso il contesto della richiesta) rispetto ai permessi ambientali propri dell’agent.

            Fornisci un interruttore di emergenza

            Sezione intitolata “Fornisci un interruttore di emergenza”

            Poiché il comportamento del modello può cambiare in modi inaspettati, pianifica la possibilità di disabilitare o sostituire rapidamente il modello senza una modifica al codice:

            • Leggi l’ID del modello dalla configurazione (ad esempio una variabile d’ambiente MODEL_ID) in modo che gli operatori possano cambiare o ripristinare un modello diverso aggiornando la configurazione.
            • Proteggi l’agent dietro un feature flag in modo che la sua funzionalità AI possa essere disabilitata completamente. Quando disabilitato, restituisci un messaggio generico piuttosto che un errore e assicurati che il resto della tua applicazione si degradi in modo elegante.

            Documenta come attivare questi controlli nel tuo manuale operativo.

            Proteggi i dati sensibili

            Sezione intitolata “Proteggi i dati sensibili”
            • Evita di registrare nei log prompt e completamenti, che potrebbero contenere dati utente. L’hook di logging degli errori del modello dell’agent generato registra solo i metadati degli errori, non il contenuto della conversazione — mantieni questa proprietà quando aggiungi il tuo logging.
            • Restituisci messaggi di errore generici agli utenti; registra gli errori dettagliati lato server.
            • Isola lo stato della conversazione tra utenti e sessioni e autorizza l’accesso a qualsiasi dato di sessione persistente.
            • Redigi le informazioni personalmente identificabili (PII) da prompt e output — sia con un filtro per informazioni sensibili di Bedrock Guardrail (sotto) sia, per gli agent Strands, con gli approcci nella guida PII Redaction.

            Amazon Bedrock Guardrails

            Sezione intitolata “Amazon Bedrock Guardrails”

            Amazon Bedrock Guardrails fornisce filtri di contenuto configurabili, argomenti negati e filtri per informazioni sensibili (PII) che vengono valutati sull’input e output del modello. Puoi allegare un guardrail al modello utilizzato dall’agent generato:

            agent.ts
            import { Agent } from '@strands-agents/sdk';
            import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
            

            const model = new BedrockModel({
              modelId: process.env.MODEL_ID,
              guardrailConfig: {
                guardrailIdentifier: process.env.GUARDRAIL_ID!,
                guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
              },
            });
            

            const agent = new Agent({ model, /* ... */ });

            Consulta la guida Guardrails di Strands per maggiori dettagli.

            Connessioni

            Sezione intitolata “Connessioni”

            Usa il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

            Strands AgentsTypeScript
            React to TypeScript AgentChiama un TypeScript Agent da un sito React
            CopilotKit
            React to AG-UI AgentChiama un Agent che espone il protocollo AG-UI da un sito React tramite CopilotKit
            Strands AgentsTypeScriptModel Context Protocol
            TypeScript Agent to MCPCollega un TypeScript Agent a un server MCP
            Strands AgentsTypeScriptAgent2Agent
            TypeScript Agent to A2A AgentCollega un TypeScript Agent a un agente A2A remoto
            Strands AgentsPythonAgent2Agent
            Python Agent to A2A AgentCollega un Python Agent a un agente A2A remoto
            Strands AgentsTypeScriptAmazon Aurora
            TypeScript Agent to Relational DatabaseCollega un TypeScript Agent a un database relazionale Aurora
            Strands AgentsTypeScriptAmazon DynamoDB
            TypeScript Agent to TypeScript DynamoDBCollega un TypeScript Agent a una tabella DynamoDB
            Strands AgentsTypeScriptAmazon Bedrock AgentCore Gateway
            TypeScript Agent to AgentCore GatewayCollega un TypeScript Agent a un AgentCore Gateway