TypeScript Agent

Genera un Strands Agent TypeScript per costruire agenti AI con strumenti, e opzionalmente 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 A2A, o il protocollo AG-UI per l’integrazione diretta con il frontend tramite CopilotKit.

Cos’è Strands?

Strands è un framework leggero per costruire agenti AI. Le caratteristiche principali includono:

Leggero e personalizzabile: Ciclo dell’agente semplice che non ti ostacola
Pronto per la produzione: Osservabilità completa, tracciamento e opzioni di distribuzione per la scalabilità
Agnostico rispetto a modelli 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

Genera un Agent

Puoi generare un TypeScript Agent in due modi:

CLI
VSCode

pnpm nx g @aws/nx-plugin:ts#agent

yarn nx g @aws/nx-plugin:ts#agent

npx nx g @aws/nx-plugin:ts#agent

bunx nx g @aws/nx-plugin:ts#agent

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm nx g @aws/nx-plugin:ts#agent --dry-run

yarn nx g @aws/nx-plugin:ts#agent --dry-run

npx nx g @aws/nx-plugin:ts#agent --dry-run

bunx nx g @aws/nx-plugin:ts#agent --dry-run

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - ts#agent
Compila i parametri richiesti
Clicca su Generate

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	string	-	Il progetto a cui aggiungere lo Agent
framework	strands	strands	L'SDK dell'agente da utilizzare.
name	string	-	Il nome del tuo Agent (predefinito: agent)
auth	iam \| cognito	iam	Il metodo utilizzato per autenticare con il tuo Agent. Applicabile solo quando infra è impostato (ignorato quando infra è none).
protocol	http \| a2a \| ag-ui	http	Il 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 \| terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
infra	agentcore \| none	agentcore	Il tipo di infrastruttura per ospitare il tuo Agent.
session	s3 \| in-memory	s3	Lo storage utilizzato per persistere la sessione del tuo Agent.
preferInstallDependencies	boolean	true	Se 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

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

Protocollo HTTP (predefinito)

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts Entry point for Bedrock AgentCore Runtime (tRPC/WebSocket server)
    init.ts tRPC initialization
    router.ts tRPC router with agent procedures
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    client.ts Vended client for invoking your agent
    agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands dependencies
- project.json Updated with agent serve targets

Protocollo A2A

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

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts A2A Express server entry point
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands and Express dependencies
- project.json Updated with agent serve targets

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/ (or custom name if specified)
    index.ts AG-UI server entry point (Express + SSE)
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands and AG-UI dependencies
- project.json Updated with agent serve targets

Infrastruttura

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

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

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ Constructs for infrastructure specific to a project/generator
    …
  - Directorycore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Directorycore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

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

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<project-name>
    <project-name>.ts CDK construct for deploying your agent

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

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 data plane 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.

Con infra: none, non viene generata alcuna infrastruttura AWS. L’agent viene eseguito come processo locale e chiama Amazon Bedrock per l’inferenza del modello.

Lavorare con il Tuo Agent

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 standardizzata tra agenti. Ideale quando il tuo agente deve essere individuabile e invocabile da altri agenti compatibili 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 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.

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 una singola procedura di subscription denominata invoke in router.ts.

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 () => {
  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 agli strumenti
Gestione degli errori e formattazione delle risposte

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 Strands sui provider di modelli per ulteriori opzioni di configurazione.

Consumare Server MCP

Puoi aggiungere strumenti dai server MCP al tuo agente Strands.

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

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
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 Strands.

Altro

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

Server A2A (protocollo A2A)

Il file 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 controllo di salute /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 (rispetto a 8080 per HTTP), per cui il Dockerfile e l’infrastruttura generati sono già configurati.

Server AG-UI (protocollo AG-UI)

Il file index.ts generato avvolge il tuo Agent Strands 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 di salute 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

Sviluppo Locale

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

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx 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, utilizza il suo target <your-agent-name>-dev:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx 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 sulla porta assegnata se hai più agenti).

Chattare con il Tuo Agent

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 localmente, quindi avvia prima il target <your-agent-name>-dev dell’agente (in un terminale separato):

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Quindi, in un altro terminale, avvia la chat:

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

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

Chattare con il tuo agente distribuito

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:

IAM
Cognito

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:

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Per gli agenti autenticati con Cognito, fornisci un token di accesso Cognito tramite la variabile d’ambiente AGENT_ACCESS_TOKEN, che viene inviato come bearer token:

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Puoi ottenere un token di accesso utilizzando 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> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Distribuire il Tuo Agent su Bedrock AgentCore Runtime

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.

CDK
Terraform

Viene generato un costrutto CDK per il tuo agent, denominato in base al name che hai scelto quando hai eseguito il 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');
  }
}

Viene generato un modulo Terraform per te, denominato in base al name che hai scelto quando hai eseguito il generatore, o <ProjectName>-agent per impostazione predefinita.

Passa gli output del modulo condiviso runtime_config_appconfig nel modulo agent:

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Docker è richiesto per compilare e distribuire il tuo 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 Agent. Puoi scegliere tra autenticazione IAM (predefinita) o Cognito quando generi il tuo agent.

IAM

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

CDK
Terraform

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, per esempio:

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

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

    agent.grantInvokeAccess(lambdaFunction);
  }
}

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

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
Terraform

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.

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"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

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

Target Bundle

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

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

La configurazione di Rolldown si trova in rolldown.config.ts, con una voce per ogni 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

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 del 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

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

Un target trivy viene aggiunto al tuo progetto che scansiona l’immagine costruita ed esce con codice diverso da 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 container della tua build dell’immagine (docker o finch), quindi non sono richiesti 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:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Soppressione dei Risultati di Trivy

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

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

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

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 CloudWatch, selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate dovrai abilitare Transaction Search.

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

Gestione delle Sessioni

L’opzione session controlla come il tuo agente persiste lo stato della conversazione (cronologia dei messaggi, stato degli strumenti, ecc.) tra le invocazioni, utilizzando il SessionManager dell’SDK Strands:

s3 (predefinito): L’infrastruttura CDK/Terraform fornisce un bucket S3 dedicato per i dati di sessione, crittografato con una chiave KMS dedicata e con tutto l’accesso pubblico bloccato; i log di accesso al server vengono consegnati a un gruppo di log CloudWatch Logs tramite la stessa chiave. Al ruolo IAM dell’agente viene concesso l’accesso in lettura/scrittura/elenco/eliminazione al bucket e l’accesso decrypt/generate-data-key alla chiave, e il nome del bucket viene registrato insieme all’ARN dell’agente nella configurazione del runtime AppConfig.
in-memory: Non viene fornito alcun bucket. Lo stato della conversazione viene mantenuto solo in memoria per la durata del processo in esecuzione e non sopravvive ai riavvii o allo scale-in.

Questo è implementato nel file session.ts generato, che esporta una funzione getSessionManager() che risolve un SessionManager per la sessione corrente.

L’ID di sessione stesso proviene dalla sessione AgentCore Runtime (propagato tramite l’header x-amzn-bedrock-agentcore-runtime-session-id per A2A/AG-UI, o il contesto della connessione WebSocket per HTTP/tRPC) ed è associato a un contesto basato su AsyncLocalStorage in modo che getCurrentSessionId() possa risolverlo ovunque nella richiesta — inclusi eventuali client MCP o A2A downstream collegati tramite il generatore connection, in modo che l’intera catena di chiamate condivida una sessione coerente.

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.

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:

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

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

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

Esegui con tsx come modo rapido per testare il tuo agente.

pnpm tsx scripts/test.ts

yarn tsx scripts/test.ts

npx tsx scripts/test.ts

bunx tsx scripts/test.ts

Invocare l’Agent Distribuito

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

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

CDK
Terraform

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

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

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 l’ARN in URL sostituendo : con %3A e / con %2F.

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

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

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

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

La tua infrastruttura può anche restituire direttamente l’URL di invocazione completo, con la codifica dell’ARN gestita per te:

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

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

NodeJS

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

IAM
Cognito

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({ prompt: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Autenticazione JWT / Cognito

Utilizza il metodo factory withJwtAuth per autenticarti con il token di accesso JWT / Cognito.

const client = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => `<access-token>`,
});

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

L’accessTokenProvider deve restituire il token utilizzato per autenticare la richiesta. Puoi, ad esempio, ottenere un token all’interno di questo metodo per garantire che le credenziali aggiornate vengano riutilizzate quando tRPC riavvia una connessione WebSocket. Quanto segue dimostra l’utilizzo dell’SDK AWS per ottenere il token da Cognito:

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";

const cognito = new CognitoIdentityProvider();

const jwtClient = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => {
    const response = await cognito.adminInitiateAuth({
      UserPoolId: '<user-pool-id>',
      ClientId: '<user-pool-client-id>',
      AuthFlow: 'ADMIN_NO_SRP_AUTH',
      AuthParameters: {
        USERNAME: '<username>',
        PASSWORD: '<password>',
      },
    });
    return response.AuthenticationResult!.AccessToken!;
  },
});

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

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

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

Invocare un Agent A2A come Strumento

Per delegare il 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 il file agent.ts di questo agente per registrare l’agente A2A remoto come tool Strands.

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

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

Invocare un Agent 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).

CLI
VSCode

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
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 Agent

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.

Trattare 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 nell’esempio di strumento 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 Responsible AI di Strands coprono la scrittura di prompt di sistema robusti e attenti alla sicurezza.

Limitare 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 dell’agent stesso.

Fornire un kill switch

Poiché il comportamento del modello può cambiare in modi inaspettati, pianifica la possibilità di disabilitare o sostituire rapidamente il modello senza una modifica del 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 runbook operativo.

Proteggere i dati sensibili

Evita di registrare 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 persistito.
Redigi le informazioni personalmente identificabili (PII) da prompt e output — sia con un filtro per informazioni sensibili di Bedrock Guardrail (sotto) o, per gli agent Strands, gli approcci nella guida PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails forniscono 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:

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 Strands sui Guardrails per maggiori dettagli.

Connessioni

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

React to TypeScript AgentCall a TypeScript Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent

Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent

TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database

TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table

TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target