# Implementazione diretta del codice per Node.js L'implementazione diretta del codice ti consente di portare il tuo Node.js-based agente su Amazon Bedrock AgentCore Runtime semplicemente impacchettando il codice dell'agente e le sue dipendenze in un archivio di file.zip. Il tuo agente deve comunque rispettare [i requisiti di AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html): disporre di un `.js` file entrypoint che implementi gli `/invocations` endpoint del server POST e GET. `/ping` Puoi includere le dipendenze come indicato dal fornitore `node_modules/` nel tuo file ZIP o come singolo file raggruppato con esbuild. `.js` ## Prerequisiti Prima di iniziare, assicurati di disporre dei seguenti elementi: + ** AWS Account con credenziali configurate.** Per configurare le AWS credenziali, consulta [Configurazione e impostazioni dei file di credenziali nella CLI AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). + [**Node.js**](https://nodejs.org/)**e npm installato.** Ti consigliamo di installare la stessa versione principale che intendi distribuire su AgentCore Runtime (ad esempio, Node.js 22 per il `NODE_22` runtime). Per le versioni supportate, consulta [Runtime linguistici supportati](runtime-code-deploy-supported-runtimes.md). + ** AWS Autorizzazioni**: per creare e distribuire un agente, è necessario disporre delle autorizzazioni appropriate. [Per ulteriori informazioni, consulta AgentCore Autorizzazioni di runtime.](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) + **Accesso al modello**: Anthropic Claude Sonnet 4.0 [abilitato nella console](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) Amazon Bedrock. [Per informazioni sull'utilizzo di un modello diverso con gli Strands Agents, consulta la sezione Model *Provider nella documentazione dell'SDK di* Strands Agents.](https://strandsagents.com/latest/documentation/docs/) ## Fase 1: Configura il progetto e installa le dipendenze Inizializza il tuo progetto con i seguenti comandi: ``` mkdir agentcore_runtime_node_deploy cd agentcore_runtime_node_deploy npm init -y ``` Facoltativamente, esegui `npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation` per abilitare le tracce di [ AgentCore osservabilità di Amazon Bedrock](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html). ## Passaggio 2: crea il codice del tuo agente Crea il tuo punto di ingresso per l'agente. Il tuo agente deve implementare il contratto HTTP AgentCore Runtime con un endpoint sanitario `/ping` GET e un gestore `/invocations` POST. **Example** Installa l'[SDK di Strands Agents](https://strandsagents.com/latest/) e le sue dipendenze: ``` npm install @strands-agents/sdk express zod npm install -D @types/express @types/node typescript ``` Crea un file denominato: `src/app.ts` ``` import express, { Request, Response } from "express"; import { Agent, tool } from "@strands-agents/sdk"; import z from "zod"; const PORT = 8080; const app = express(); app.use(express.json()); const currentTime = tool({ name: "current_time", description: "Returns the current date and time", inputSchema: z.object({}), callback: () => { return new Date().toISOString(); }, }); const agent = new Agent({ tools: [currentTime], printer: false, }); app.get("/ping", (_req: Request, res: Response) => { res.json({ status: "Healthy" }); }); app.post("/invocations", async (req: Request, res: Response) => { const prompt = req.body?.prompt || "No prompt provided"; try { const result = await agent.invoke(prompt); res.json({ result: result.lastMessage }); } catch (error: unknown) { const message = error instanceof Error ? error.message : String(error); res.status(500).json({ error: message }); } }); app.listen(PORT, "0.0.0.0", () => { console.log("Strands agent listening on port " + PORT); }); ``` Compila il file TypeScript in JavaScript: ``` npx tsc --init --target ES2022 --module commonjs --outDir ./dist npx tsc ``` L'output compilato `dist/app.js` è quello che distribuisci. Quando crei l'agente, usa`"entryPoint": ["dist/app.js"]`: l' JavaScript output compilato, non la `.ts` fonte. Questo esempio utilizza il `node:http` modulo integrato senza dipendenze esterne. Crea un file denominato`app.js`: ``` const http = require("node:http"); const PORT = 8080; const server = http.createServer((req, res) => { if (req.url === "/ping" && req.method === "GET") { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ status: "Healthy" })); } else if (req.url === "/invocations" && req.method === "POST") { let body = ""; req.on("data", (chunk) => { body += chunk; }); req.on("end", () => { try { const input = JSON.parse(body); const prompt = input.prompt || input.command || "No prompt provided"; res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ result: "Hello from Node.js managed runtime! You said: " + prompt, runtime: "NODE_22", nodeVersion: process.version, timestamp: new Date().toISOString() })); } catch (e) { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ result: "Hello from Node.js managed runtime!", runtime: "NODE_22", nodeVersion: process.version, input: body, timestamp: new Date().toISOString() })); } }); } else { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ message: "Node.js managed runtime agent is running" })); } }); server.listen(PORT, "0.0.0.0", () => { console.log("Node.js agent listening on port " + PORT); }); ``` ## Fase 3: Esegui il test localmente Assicurati che la porta 8080 sia libera prima di iniziare. Vedi *Porta 8080 in uso (solo locale)* in [Problemi e soluzioni comuni](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues). Apri una finestra di terminale e avvia il tuo agente: **Example** ``` node dist/app.js ``` Apri un'altra finestra di terminale e richiama l'agente: ``` curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "What time is it right now?"}' ``` **Operazione riuscita:** dovrebbe apparire una risposta contenente l'ora corrente restituita dallo `current_time` strumento dell'agente. Nella finestra del terminale in cui è in esecuzione l'agente, immettete `Ctrl+C` per arrestarlo. ``` node app.js ``` Apri un'altra finestra del terminale e richiama l'agente: ``` curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "Hello!"}' ``` **Operazione riuscita:** dovresti vedere una risposta del tipo`{"result": "Hello from Node.js managed runtime! You said: Hello!","runtime":"NODE_22",…​}`. Nella finestra del terminale in cui è in esecuzione l'agente, immettete `Ctrl+C` per arrestarlo. ## Fase 4: Abilita l'osservabilità per il tuo agente [Amazon Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) ti aiuta a tracciare, eseguire il debug e monitorare gli agenti ospitati in Runtime. AgentCore Per prima cosa abilita CloudWatch Transaction Search seguendo le istruzioni in [Enabling Amazon Bedrock AgentCore runtime observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). Per osservare il tuo agente, consulta [Visualizzare i dati di osservabilità per i tuoi agenti Amazon Bedrock AgentCore ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html). Per abilitare la strumentazione automatica per il tuo Node.js agente, aggiungi il pacchetto ADOT: ``` npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation ``` **Importante** La strumentazione automatica ADOT funziona Node.js `require()` patchando le chiamate in fase di esecuzione. Ciò significa che è compatibile solo con l'output del modulo CommonJS. Se si compila TypeScript con `--module nodenext` o `--module esnext` (producendo `import` istruzioni ESM), la strumentazione ADOT fallisce silenziosamente e non viene emessa alcuna traccia. Per usare ADOT, compila `--module commonjs` o usa esbuild with (che conserva le chiamate ai moduli integrati). `--platform=node` `require()` Node.js Durante la distribuzione, includetelo `node_modules/` nel file ZIP e utilizzate il `opentelemetry-instrument` prefisso nel punto di ingresso (vedi Fase 5). ## Fase 5: Esegui la distribuzione su Runtime e richiama AgentCore **Nota** AgentCore Runtime non esegue i file TypeScript (`.ts`) in modo nativo. È necessario traspilare TypeScript to JavaScript prima della distribuzione. Per informazioni dettagliate, consulta [Lavorare con TypeScript](#concept-node-typescript) . Crea un file.zip con il codice dell'agente e le dipendenze. AgentCore Runtime supporta solo l'architettura del set di istruzioni **arm64**: assicurati che tutti i moduli (`.node`file) nativi siano compilati per arm64. **Example** Package dell'output compilato e delle dipendenze fornite dal fornitore: ``` npm install --production zip -r deployment_package.zip dist/ node_modules/ package.json ``` Quando crei l'agente, usa`"entryPoint": ["dist/app.js"]`: l' JavaScript output compilato, non la `.ts` fonte. Poiché questo esempio non ha dipendenze esterne, è necessario solo il file del punto di ingresso: ``` zip deployment_package.zip app.js ``` Quando crei l'agente, usa`"entryPoint": ["app.js"]`. **Nota** . La dimensione massima per un pacchetto di distribuzione.zip per AgentCore Runtime è 250 MB (compresso) e 750 MB (decompresso). Tieni presente che questo limite si applica alla dimensione combinata di tutti i file che carichi. Il AgentCore Runtime richiede l'autorizzazione per leggere i file nel pacchetto di distribuzione. Nella notazione ottale delle autorizzazioni Linux, AgentCore Runtime richiede 644 autorizzazioni per i file non eseguibili (rw-r—r--) e 755 permessi (rwxr-xr-x) per le directory e i file eseguibili. In Linux e macOS, utilizza il comando `chmod` per modificare le autorizzazioni file su file e directory nel pacchetto di implementazione. Ad esempio, per assegnare a un file non eseguibile le autorizzazioni corrette, esegui il comando seguente,. `chmod 644 ` Per modificare le autorizzazioni file in Windows, consulta [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) nella documentazione di Microsoft Windows. \+.. Se non concedi a AgentCore Runtime le autorizzazioni necessarie per accedere alle directory nel pacchetto di distribuzione, AgentCore Runtime imposta le autorizzazioni per tali directory su 755 (rwxr-xr-x). Un archivio ZIP contenente le dipendenze Linux **arm64** deve essere caricato su S3 come prerequisito per Create Agent Runtime. Il codice seguente richiede che il bucket S3 specificato esista già. Segui la AWS documentazione [qui](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket-s3.html) per creare un bucket. Il TypeScript codice seguente caricherà l'archivio di file.zip su S3 e creerà un runtime Amazon AgentCore Bedrock. ``` import { readFileSync } from "node:fs"; import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; import { BedrockAgentCoreControlClient, CreateAgentRuntimeCommand, } from "@aws-sdk/client-bedrock-agentcore-control"; const accountId = "your-aws-account-id"; const agentName = "nodejs_agent"; const region = "us-west-2"; const bucketName = `bedrock-agentcore-code-${accountId}-${region}`; const s3Client = new S3Client({ region }); console.log("Uploading deployment_package.zip to S3..."); await s3Client.send(new PutObjectCommand({ Bucket: bucketName, Key: `${agentName}/deployment_package.zip`, Body: readFileSync("deployment_package.zip"), ExpectedBucketOwner: accountId, })); console.log(`Upload completed. S3 location: s3://${bucketName}/${agentName}/deployment_package.zip`); const controlClient = new BedrockAgentCoreControlClient({ region }); const response = await controlClient.send(new CreateAgentRuntimeCommand({ agentRuntimeName: agentName, agentRuntimeArtifact: { codeConfiguration: { code: { s3: { bucket: bucketName, prefix: `${agentName}/deployment_package.zip`, }, }, runtime: "NODE_22", entryPoint: ["dist/app.js"], }, }, networkConfiguration: { networkMode: "PUBLIC" }, roleArn: `arn:aws:iam::${accountId}:role/AmazonBedrockAgentCoreSDKRuntime-${region}`, lifecycleConfiguration: { idleRuntimeSessionTimeout: 300, maxLifetime: 1800, }, })); console.log(`Agent Runtime created successfully!`); console.log(`Agent Runtime ARN: ${response.agentRuntimeArn}`); console.log(`Status: ${response.status}`); ``` Per abilitare la strumentazione automatica OTEL, includi `node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/` nel tuo ZIP e usa il `opentelemetry-instrument` prefisso nel punto di ingresso: ``` entryPoint: ["opentelemetry-instrument", "dist/app.js"], ``` [Per richiamare un agente sul AgentCore runtime di Amazon Bedrock a livello di codice, consulta: Richiamare un agente a livello di codice](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#invoke-programmatically) ## Passaggio 6: interrompere la sessione, l'aggiornamento o la pulizia Il TypeScript codice seguente aggiornerà un AgentCore Runtime. Carica il nuovo pacchetto di distribuzione su S3, quindi chiama`UpdateAgentRuntimeCommand`: ``` import { readFileSync } from "node:fs"; import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3"; import { BedrockAgentCoreControlClient, UpdateAgentRuntimeCommand, } from "@aws-sdk/client-bedrock-agentcore-control"; const accountId = "your-aws-account-id"; const agentName = "nodejs_agent"; const region = "us-west-2"; const bucketName = `bedrock-agentcore-code-${accountId}-${region}`; const s3Client = new S3Client({ region }); console.log("Uploading deployment_package.zip to S3..."); await s3Client.send(new PutObjectCommand({ Bucket: bucketName, Key: `${agentName}/deployment_package.zip`, Body: readFileSync("deployment_package.zip"), ExpectedBucketOwner: accountId, })); console.log("Upload completed successfully!"); const controlClient = new BedrockAgentCoreControlClient({ region }); const response = await controlClient.send(new UpdateAgentRuntimeCommand({ agentRuntimeId: "", agentRuntimeArtifact: { codeConfiguration: { code: { s3: { bucket: bucketName, prefix: `${agentName}/deployment_package.zip`, }, }, runtime: "NODE_22", entryPoint: ["dist/app.js"], }, }, networkConfiguration: { networkMode: "PUBLIC" }, roleArn: `arn:aws:iam::${accountId}:role/AmazonBedrockAgentCoreSDKRuntime-${region}`, })); console.log(`Agent Runtime updated successfully!`); console.log(`Agent Runtime ARN: ${response.agentRuntimeArn}`); console.log(`Status: ${response.status}`); ``` Per interrompere la sessione in esecuzione prima di quella configurabile `IdleRuntimeSessionTimeout` (impostazione predefinita a 15 minuti) e risparmiare su eventuali costi inutili, usa il codice seguente: ``` import { BedrockAgentCoreClient, StopRuntimeSessionCommand, } from "@aws-sdk/client-bedrock-agentcore"; const region = "us-west-2"; const dataClient = new BedrockAgentCoreClient({ region }); const response = await dataClient.send(new StopRuntimeSessionCommand({ agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2::runtime/", runtimeSessionId: "", qualifier: "DEFAULT", })); console.log("Session stopped successfully!"); ``` Il TypeScript codice seguente eliminerà un AgentCore runtime di Amazon Bedrock e il file di archivio.zip in S3. ``` import { S3Client, DeleteObjectCommand } from "@aws-sdk/client-s3"; import { BedrockAgentCoreControlClient, DeleteAgentRuntimeCommand, } from "@aws-sdk/client-bedrock-agentcore-control"; const accountId = "your-aws-account-id"; const agentName = "nodejs_agent"; const region = "us-west-2"; const bucketName = `bedrock-agentcore-code-${accountId}-${region}`; const controlClient = new BedrockAgentCoreControlClient({ region }); console.log("Deleting Agent from Amazon Bedrock AgentCore Runtime!"); const response = await controlClient.send(new DeleteAgentRuntimeCommand({ agentRuntimeId: "", })); console.log(`Agent Runtime deleted successfully!`); console.log(`Status: ${response.status}`); const s3Client = new S3Client({ region }); console.log("Deleting deployment archive from S3..."); await s3Client.send(new DeleteObjectCommand({ Bucket: bucketName, Key: `${agentName}/deployment_package.zip`, ExpectedBucketOwner: accountId, })); console.log("Archive deleted successfully from S3!"); ``` ## Node.js-specific concetti per la distribuzione diretta del codice Scopri Node.js-specific i concetti relativi all'utilizzo della distribuzione diretta del codice con Amazon Bedrock AgentCore Runtime. **Topics** ### Requisiti del punto di ingresso AgentCore Runtime for accetta Node.js solo punti di `.js` ingresso. TypeScript i file (`.ts`) non vengono accettati direttamente: è necessario trasporli JavaScript prima del confezionamento. Ti consigliamo di utilizzare [esbuild](https://esbuild.github.io/) per transpilare e raggruppare in un unico passaggio. Aggiungi esbuild come dipendenza di sviluppo con. `npm install -D esbuild` I punti di ingresso possono trovarsi nelle sottodirectory. Ad esempio, `src/app.js` o `dist/index.js` sono punti di ingresso validi. Node.js la risoluzione del modulo risale l'albero delle directory dalla posizione del punto di ingresso, in modo che le dipendenze presenti nella `node_modules/` radice del file ZIP vengano trovate automaticamente, senza bisogno di alcuna `NODE_PATH` configurazione. Quando specificate un punto di ingresso della sottodirectory, assicuratevi che il percorso nella `entryPoint` configurazione corrisponda al percorso all'interno del file ZIP. ### Opzioni di pacchettizzazione delle dipendenze Esistono due approcci per impacchettare le dipendenze per gli Node.js agenti: **Dipendenze fornite dal fornitore (le più semplici):** Includi `node_modules/` direttamente nel codice ZIP accanto al punto di ingresso: ``` npm install --production zip -r my-agent.zip app.js node_modules/ package.json ``` Questo produce uno ZIP con la seguente struttura: ``` my-agent.zip ├── app.js ├── package.json └── node_modules/ ``` **In bundle con esbuild (lo ZIP più piccolo):** Usa [esbuild](https://esbuild.github.io/) per raggruppare tutte le dipendenze in un unico file: ``` npx esbuild app.js --bundle --platform=node --target=node22 --outfile=bundle.js zip my-agent.zip bundle.js ``` Questo produce uno ZIP minimo: ``` my-agent.zip └── bundle.js ``` Entrambi gli approcci funzionano. Le distribuzioni in bundle sono in genere inferiori a 10 MB e vengono implementate più velocemente. Le implementazioni fornite dai fornitori sono più semplici e non richiedono una fase di creazione, ma possono essere più ampie. ### Moduli nativi e compatibilità con arm64 AgentCore Runtime supporta solo l'architettura del set di istruzioni **arm64**. Se il tuo agente utilizza pacchetti npm che includono moduli nativi (compilati `.node` o `.so` file), tali file binari devono essere compilati per Linux arm64. AgentCore Runtime convalida l'architettura di tutti i `.node` `.so` file del pacchetto di distribuzione leggendo le relative intestazioni ELF. Se viene compilato un file binario per un'architettura diversa (ad esempio x86\_64 o macOS), la creazione dell'agente avrà esito negativo e restituirà status. `CREATE_FAILED` Per installare moduli nativi compatibili con arm64: + Installa le dipendenze su una macchina arm64 (come un'istanza Amazon AWS Graviton-based EC2) + Usa npm e flag: `--arch` `--platform` ``` npm install --arch=arm64 --platform=linux ``` + Usa esbuild per raggruppare il tuo codice se il modulo nativo può essere evitato in fase di esecuzione I pacchetti npm più popolari (Express, Axios, Fastify, Hono, ws) sono puri JavaScript e non contengono moduli nativi. ### Lavorare con TypeScript AgentCore Runtime non esegue direttamente TypeScript i file. È necessario compilare il codice TypeScript sorgente in JavaScript prima della distribuzione. Questo è lo stesso modello usato da AWS Lambda. **Usando il TypeScript compilatore (tsc):** ``` npm install -g typescript npx tsc --init --target ES2022 --module commonjs --outDir ./dist npx tsc ``` Quindi impacchetta l'output compilato: ``` cd dist zip -r ../deployment_package.zip . ``` Quando crei l'agente, imposta il punto di ingresso sul `.js` file compilato (ad esempio, `app.js` o in `dist/app.js` base alla struttura ZIP). **Usare esbuild (consigliato per una confezione più semplice):** ``` npx esbuild app.ts --bundle --platform=node --target=node22 --outfile=app.js zip deployment_package.zip app.js ``` esbuild compila TypeScript e raggruppa le dipendenze in un unico passaggio, producendo un piccolo file autonomo. `.js` ### campo package.json engines Se `package.json` includi un `engines.node` campo, AgentCore Runtime verifica che l'intervallo specificato sia compatibile con la Node.js versione selezionata (ad esempio, Node.js 22 quando si utilizza il runtime). `NODE_22` Se l'intervallo esclude quella versione, la creazione dell'agente avrà esito negativo e riporterà lo status. `CREATE_FAILED` Ad esempio, le seguenti `engines` dichiarazioni sono compatibili con Node.js 22: ``` { "engines": { "node": ">=18" } } { "engines": { "node": ">=14 <18 || >=20" } } { "engines": { "node": "22" } } ``` Le seguenti dichiarazioni sono incompatibili e impediranno la creazione dell'agente: ``` { "engines": { "node": "<18" } } { "engines": { "node": ">=14 <18" } } ``` AgentCore Runtime verifica inoltre la presenza di dipendenze comuni `engines.node` nel campo. `node_modules/` Se una di queste dichiara un intervallo di versioni che esclude la Node.js versione di runtime di destinazione, la creazione dell'agente avrà esito negativo. Se riscontri un'`engines.node`incompatibilità, aggiorna il pacchetto a una versione che supporti la versione di destinazione Node.js o rimuovi il `engines` campo dal tuo. `package.json` Per Node.js le versioni supportate, consulta [Runtime linguistici supportati](runtime-code-deploy-supported-runtimes.md).