View a markdown version of this page

Distribuzione diretta del codice per Node.js - Fondamento Amazon AgentCore
PrerequisitiFase 1: Configurazione del progetto e installazione delle dipendenzePassaggio 2: crea il codice del tuo agenteFase 3: Esegui il test localmentePassaggio 4: abilita l'osservabilità per il tuo agentePassaggio 5: esegui la distribuzione su Runtime e richiama AgentCorePassaggio 6: interrompere la sessione, l'aggiornamento o la puliziaNode.js-specific concetti per la distribuzione diretta del codice

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Distribuzione diretta del codice per Node.js

La distribuzione 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. L'agente deve comunque rispettare i requisiti di AgentCore Runtime: disporre di un .js file di ingresso che /invocations implementa gli endpoint dei server POST e GET. /ping

Puoi includere le dipendenze come fornite node_modules/ nel tuo ZIP o come singolo file fornito in 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

  • Node.jse 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 Supported language runtimes.

  • AWS Autorizzazioni: per creare e distribuire un agente, è necessario disporre delle autorizzazioni appropriate. Per ulteriori informazioni, consulta AgentCore Autorizzazioni di runtime.

  • Accesso ai modelli: Amazon Bedrock consente l'accesso ai modelli di base per impostazione predefinita. Per utilizzare un modello non di base, segui i passaggi di accesso al modello.

Fase 1: Configurazione del progetto e installazione delle 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 osservabilità di Amazon Bedrock AgentCore .

Passaggio 2: crea il codice del tuo agente

Crea il tuo punto di ingresso per l'agente. L'agente deve implementare il contratto AgentCore Runtime HTTP con un endpoint /ping GET health e un gestore /invocations POST.

Esempio
Strands Agents SDK

Installa l'SDK Strands Agents e le relative 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 per 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 il sorgente. .ts

HTTP (no framework)

Questo esempio utilizza il node:http modulo integrato senza dipendenze esterne.

Crea un file denominatoapp.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 Risoluzione dei problemi se la porta è già in uso.

Apri una finestra di terminale e avvia il tuo agente:

Esempio
Strands Agents SDK
node dist/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": "What time is it right now?"}'

Successo: dovresti vedere una risposta contenente l'ora corrente restituita dallo current_time strumento dell'agente. Nella finestra del terminale in cui è in esecuzione l'agente, digitate Ctrl+C per arrestare l'agente.

HTTP (no framework)
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!"}'

Successo: 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, digitate Ctrl+C per arrestare l'agente.

Passaggio 4: abilita l'osservabilità per il tuo agente

Amazon Bedrock AgentCore Observability 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 Abilitazione dell'osservabilità del runtime di Amazon Bedrock AgentCore . Per osservare il tuo agente, consulta Visualizzare i dati di osservabilità per i tuoi agenti Amazon Bedrock. AgentCore

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 applicando patch alle chiamate in fase di esecuzione. Node.js require() 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 con --module commonjs o usa esbuild with (che preserva le chiamate per i moduli integrati). --platform=node require() Node.js

Durante la distribuzione, includetelo node_modules/ nel vostro ZIP e usate il opentelemetry-instrument prefisso nel punto di ingresso (vedete il passaggio 5).

Passaggio 5: esegui la distribuzione su Runtime e richiama AgentCore

Nota

AgentCore Runtime non esegue i file TypeScript (.ts) in modo nativo. È necessario eseguire la transpile in prima della distribuzione TypeScript . JavaScript Per informazioni dettagliate, consulta Lavorare con TypeScript .

Crea un file .zip con il codice del tuo agente e le dipendenze. AgentCore Runtime supporta solo l'architettura del set di istruzioni arm64: assicuratevi che tutti i moduli (.nodefile) nativi siano compilati per arm64.

Esempio
Strands Agents SDK

Impacchettizza l'output compilato e le dipendenze vendute:

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 il sorgente. .ts

HTTP (no framework)

Poiché questo esempio non ha dipendenze esterne, è necessario solo il file del punto di ingresso:

zip deployment_package.zip app.js

Quando si crea l'agente, utilizzare"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 necessita dell'autorizzazione per leggere i file nel pacchetto di distribuzione. Nella notazione ottale delle autorizzazioni di Linux, AgentCore Runtime richiede 644 autorizzazioni per i file non eseguibili (rw-r—r--) e 755 autorizzazioni (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 chmod 644 <filepath> le autorizzazioni corrette, esegui il comando seguente,. Per modificare le autorizzazioni file in Windows, consulta Set, View, Change, or Remove Permissions on an Object 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 di 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 riportata per creare un bucket. Il TypeScript codice seguente caricherà l'archivio di file .zip su S3 e creerà un runtime Amazon Bedrock. AgentCore 

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 prefisso nel punto di ingresso: opentelemetry-instrument

entryPoint: ["opentelemetry-instrument", "dist/app.js"],

Per richiamare un agente su Amazon Bedrock AgentCore Runtime in modo programmatico, consulta Richiamare un agente a livello di codice. Richiama un agente a livello di codice

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: "<your-agent-runtime-id>",
    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 irreversibili, utilizza 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:<account-id>:runtime/<agent-runtime-id>",
    runtimeSessionId: "<your-session-id>",
    qualifier: "DEFAULT",
}));
console.log("Session stopped successfully!");

TypeScript Il 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: "<your-agent-runtime-id>",
}));
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 AgentCore Bedrock Runtime.

Argomenti

    AgentCore Runtime for accetta Node.js solo punti di .js ingresso. TypeScript files (.ts) non sono accettati direttamente: è necessario trasporli in JavaScript prima di impacchettarli. Ti consigliamo di usare esbuild 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 node_modules/ alla radice dello ZIP vengano trovate automaticamente: non è necessaria alcuna NODE_PATH configurazione.

    Quando specificate un punto di ingresso nella sottodirectory, assicuratevi che il percorso nella entryPoint configurazione corrisponda al percorso all'interno del file ZIP.

    Esistono due approcci alla creazione di pacchetti di dipendenze per gli Node.js agenti:

    Dipendenze fornite dal fornitore (le più semplici):

    Includi node_modules/ direttamente nel tuo ZIP insieme 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/

    Fornito in bundle con esbuild (lo ZIP più piccolo):

    Usa esbuild 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 compilazione, ma possono essere più ampie.

    AgentCore Runtime supporta solo l'architettura del set di istruzioni arm64. Se l'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 .so file del pacchetto .node di distribuzione leggendo le relative intestazioni ELF. Se un file binario viene compilato per un'architettura diversa (ad esempio x86_64 o macOS), la creazione dell'agente fallirà con Status. CREATE_FAILED

    Per installare moduli nativi compatibili con arm64:

    • Installa le dipendenze su una macchina arm64 (ad esempio un' AWS Graviton-based istanza Amazon 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ù diffusi (Express, Axios, Fastify, Hono, ws) sono puri JavaScript e non contengono moduli nativi.

    AgentCore Runtime non esegue direttamente TypeScript i file. È necessario compilare il codice TypeScript sorgente per JavaScript prima della distribuzione. Questo è lo stesso modello utilizzato da Lambda AWS .

    Utilizzo del TypeScript compilatore (tsc): 

    npm install -g typescript
npx tsc --init --target ES2022 --module commonjs --outDir ./dist
npx tsc

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

    Usando esbuild (consigliato per pacchetti più semplici): 

    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

    Se package.json include 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 con 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 causeranno il fallimento della creazione dell'agente:

    { "engines": { "node": "<18" } }
{ "engines": { "node": ">=14 <18" } }

    AgentCore Runtime controlla inoltre engines.node nel campo la presenza di dipendenze comuni nel tuo. 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.nodeincompatibilità, 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 nelle lingue supportate.