Voraussetzungen Schritt 1: Projekt einrichten und Abhängigkeiten installieren Schritt 2: Erstellen Sie Ihren Agentencode Schritt 3: Lokal testen Schritt 4: Aktivieren Sie Observability für Ihren Agenten Schritt 5: In AgentCore Runtime bereitstellen und aufrufen Schritt 6: Sitzung beenden, aktualisieren oder bereinigen Node.js-specific Konzepte für die direkte Codebereitstellung

Direkte Codebereitstellung für Node.js

Die direkte Codebereitstellung ermöglicht es Ihnen, Ihren Node.js-based Agenten zu Amazon Bedrock AgentCore Runtime zu bringen, indem Sie den Agentencode und seine Abhängigkeiten einfach in einem ZIP-Dateiarchiv verpacken. Ihr Agent muss weiterhin die AgentCore Runtime-Anforderungen erfüllen: Er muss über eine .js Einstiegsdatei verfügen, die /invocations POST- und /ping GET-Serverendpunkte implementiert.

Sie können Abhängigkeiten entweder so node_modules/ in Ihre ZIP-Datei aufnehmen, wie sie vom Anbieter bereitgestellt werden, oder als einzelne Datei, die im Esbuild-Paket enthalten ist. .js

Voraussetzungen

Stellen Sie vor Beginn sicher, dass Sie über Folgendes verfügen:

AWS Konto mit konfigurierten Anmeldeinformationen. Informationen zur Konfiguration Ihrer AWS Anmeldeinformationen finden Sie unter Konfiguration und Einstellungen für Anmeldeinformationsdateien in der AWS CLI.
Node.jsund npm ist installiert. Wir empfehlen, dieselbe Hauptversion zu installieren, die Sie auf AgentCore Runtime bereitstellen möchten (z. B. Node.js 22 für die NODE_22 Runtime). Informationen zu unterstützten Versionen finden Sie unter Unterstützte Sprachlaufzeiten.
AWS Berechtigungen: Um einen Agenten zu erstellen und bereitzustellen, benötigen Sie die entsprechenden Berechtigungen. Weitere Informationen finden Sie unter AgentCore Laufzeitberechtigungen.
Modellzugriff: Anthropic Claude Sonnet 4.0 ist in der Amazon Bedrock-Konsole aktiviert. Informationen zur Verwendung eines anderen Modells mit den Strands Agents finden Sie im Abschnitt Model Providers in der Strands Agents SDK-Dokumentation.

Schritt 1: Projekt einrichten und Abhängigkeiten installieren

Initialisieren Sie Ihr Projekt mit den folgenden Befehlen:


mkdir agentcore_runtime_node_deploy
cd agentcore_runtime_node_deploy
npm init -y

Führen Sie optional aus, npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation um Amazon Bedrock AgentCore Observability Traces zu aktivieren.

Schritt 2: Erstellen Sie Ihren Agentencode

Erstellen Sie Ihren Agenten-Einstiegspunkt. Ihr Agent muss den AgentCore Runtime-HTTP-Vertrag mit einem /ping GET-Integritätsendpunkt und einem /invocations POST-Handler implementieren.

Beispiel

Strands Agents SDK

Installieren Sie das Strands Agents SDK und seine Abhängigkeiten:


npm install @strands-agents/sdk express zod
npm install -D @types/express @types/node typescript

Erstellen Sie eine Datei mit dem Namensrc/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);
});

Kompilieren Sie die TypeScript zu JavaScript:


npx tsc --init --target ES2022 --module commonjs --outDir ./dist
npx tsc

Die kompilierte Ausgabe in dist/app.js ist das, was Sie bereitstellen. Verwenden Sie beim Erstellen des Agenten "entryPoint": ["dist/app.js"] — die kompilierte JavaScript Ausgabe, nicht die .ts Quelle.

HTTP (no framework)

In diesem Beispiel wird das integrierte node:http Modul ohne externe Abhängigkeiten verwendet.

Erstellen Sie eine Datei mit dem Namenapp.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);
});

Schritt 3: Lokal testen

Stellen Sie vor dem Start sicher, dass Port 8080 frei ist. Weitere Informationen finden Sie unter Verwendeter Port 8080 (nur lokal) unter Häufig auftretende Probleme und Lösungen.

Öffnen Sie ein Terminalfenster und starten Sie Ihren Agenten:

Beispiel

Schritt 4: Aktivieren Sie Observability für Ihren Agenten

Amazon Bedrock AgentCore Observability hilft Ihnen dabei, Agenten, die Sie in Runtime hosten, zu verfolgen, zu debuggen und zu überwachen. AgentCore Aktivieren Sie zunächst die CloudWatch Transaktionssuche, indem Sie den Anweisungen unter Amazon Bedrock AgentCore Runtime Observability aktivieren folgen. Informationen zur Beobachtung Ihres Agenten finden Sie unter Beobachtbarkeitsdaten für Ihre Amazon AgentCore Bedrock-Agenten anzeigen.

Um die automatische Instrumentierung für Ihren Node.js Agenten zu aktivieren, fügen Sie das ADOT-Paket hinzu:


npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation

Wichtig

Die automatische ADOT-Instrumentierung funktioniert, indem Node.js require() Aufrufe zur Laufzeit gepatcht werden. Das bedeutet, dass es nur mit der CommonJS-Modulausgabe kompatibel ist. Wenn Sie TypeScript mit --module nodenext oder kompilieren --module esnext (was import ESM-Anweisungen erzeugt), schlägt die ADOT-Instrumentierung stillschweigend fehl und es werden keine Spuren ausgegeben. Um ADOT zu verwenden, kompilieren Sie mit --module commonjs oder verwenden Sie esbuild with --platform=node (wodurch Aufrufe für integrierte Module beibehalten werdenrequire()). Node.js

Fügen Sie es bei der Bereitstellung node_modules/ in Ihre ZIP-Datei ein und verwenden Sie das opentelemetry-instrument Präfix in Ihrem Einstiegspunkt (siehe Schritt 5).

Schritt 5: In AgentCore Runtime bereitstellen und aufrufen

Anmerkung

AgentCore Runtime führt Dateien TypeScript (.ts) nicht nativ aus. Sie müssen JavaScript vor der Bereitstellung TypeScript auf transpilieren. Details dazu finden Sie unter Arbeitet mit TypeScript .

Erstellen Sie eine ZIP-Datei mit Ihrem Agentencode und den Abhängigkeiten. AgentCore Runtime unterstützt nur die arm64-Befehlssatzarchitektur. Stellen Sie sicher, dass alle systemeigenen Module (.nodeDateien) für arm64 kompiliert sind.

Beispiel

Anmerkung

. Die maximale Größe für ein ZIP-Bereitstellungspaket für AgentCore Runtime beträgt 250 MB (komprimiert) und 750 MB (entpackt). Beachten Sie, dass dieses Limit für die Gesamtgröße aller hochgeladenen Dateien gilt. Die AgentCore Runtime benötigt die Berechtigung, die Dateien in Ihrem Bereitstellungspaket zu lesen. In der Oktalschreibweise der Linux-Berechtigungen benötigt AgentCore Runtime 644 Berechtigungen für nicht ausführbare Dateien (rw-r—r--) und 755 Berechtigungen (rwxr-xr-x) für Verzeichnisse und ausführbare Dateien. Verwenden Sie unter Linux und MacOS den chmod-Befehl, um Dateiberechtigungen für Dateien und Verzeichnisse in Ihrem Bereitstellungspaket zu ändern. Um beispielsweise einer nicht ausführbaren Datei die richtigen Berechtigungen zu erteilen, führen Sie den folgenden Befehl aus:. chmod 644 <filepath> Informationen zum Ändern von Dateiberechtigungen in Windows finden Sie unter Festlegen, Anzeigen, Ändern oder Entfernen von Berechtigungen für ein Objekt in der Microsoft-Windows-Dokumentation. +.. Wenn Sie AgentCore Runtime nicht die erforderlichen Berechtigungen für den Zugriff auf Verzeichnisse in Ihrem Bereitstellungspaket gewähren, setzt AgentCore Runtime die Berechtigungen für diese Verzeichnisse auf 755 (rwxr-xr-x).

Als Voraussetzung für Create Agent Runtime muss ein ZIP-Archiv mit Linux-Arm64-Abhängigkeiten auf S3 hochgeladen werden. Für den folgenden Code muss der angegebene S3-Bucket bereits vorhanden sein. Bitte folgen Sie der AWS Dokumentation hier, um einen Bucket zu erstellen. Der folgende TypeScript Code lädt das ZIP-Dateiarchiv auf S3 hoch und erstellt eine Amazon Bedrock AgentCore Runtime.


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

Um die automatische OTEL-Instrumentierung zu aktivieren, fügen Sie es node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ in Ihre Postleitzahl ein und verwenden Sie das opentelemetry-instrument Präfix im Einstiegspunkt:


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

Informationen zum programmgesteuerten Aufrufen eines Agenten auf Amazon Bedrock AgentCore Runtime finden Sie unter: Programmgesteuert einen Agenten aufrufen

Schritt 6: Sitzung beenden, aktualisieren oder bereinigen

TypeScript Der folgende Code aktualisiert eine AgentCore Runtime. Laden Sie das neue Bereitstellungspaket auf S3 hoch und rufen Sie dannUpdateAgentRuntimeCommand:


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

Verwenden Sie den folgenden Code, um die laufende Sitzung vor der konfigurierbaren Sitzung IdleRuntimeSessionTimeout (standardmäßig 15 Minuten) zu beenden und mögliche Kosten zu vermeiden:


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 Der folgende Code löscht eine Amazon AgentCore Bedrock-Laufzeit und die ZIP-Archivdatei 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 Konzepte für die direkte Codebereitstellung

Erfahren Sie mehr über Node.js-specific Konzepte bei der direkten Codebereitstellung mit Amazon Bedrock AgentCore Runtime.

Themen

AgentCore Runtime for akzeptiert Node.js nur .js Einstiegspunkte. TypeScript Dateien (.ts) werden nicht direkt akzeptiert — Sie müssen sie JavaScript vor dem Verpacken transpilieren. Wir empfehlen, esbuild zu verwenden, um in einem einzigen Schritt zu transpilieren und zu bündeln. Fügen Sie esbuild als Entwicklungsabhängigkeit hinzu mit. npm install -D esbuild

Einstiegspunkte können sich in Unterverzeichnissen befinden. Zum Beispiel src/app.js oder dist/index.js sind gültige Einstiegspunkte. Node.js Die Modulauflösung durchläuft den Verzeichnisbaum vom Standort des Einstiegspunkts aus, sodass Abhängigkeiten node_modules/ im Stammverzeichnis Ihrer ZIP-Datei automatisch gefunden werden — es ist keine NODE_PATH Konfiguration erforderlich.

Wenn Sie einen Einstiegspunkt für ein Unterverzeichnis angeben, stellen Sie sicher, dass der Pfad in Ihrer entryPoint Konfiguration mit dem Pfad in der ZIP-Datei übereinstimmt.

Es gibt zwei Möglichkeiten, Abhängigkeiten für Node.js Agenten zu verpacken:

Abhängigkeiten vom Anbieter (am einfachsten):

Fügen Sie neben Ihrem Einstiegspunkt node_modules/ direkt in Ihre Postleitzahl ein:


npm install --production
zip -r my-agent.zip app.js node_modules/ package.json

Dadurch entsteht eine ZIP-Datei mit der folgenden Struktur:

my-agent.zip
├── app.js
├── package.json
└── node_modules/

Im Lieferumfang von esbuild (kleinste ZIP-Datei) enthalten:

Verwenden Sie esbuild, um alle Abhängigkeiten in einer einzigen Datei zu bündeln:


npx esbuild app.js --bundle --platform=node --target=node22 --outfile=bundle.js
zip my-agent.zip bundle.js

Dies erzeugt eine minimale ZIP-Datei:

my-agent.zip
└── bundle.js

Beide Ansätze funktionieren. Gebündelte Bereitstellungen haben in der Regel weniger als 10 MB und können schneller bereitgestellt werden. Bereitstellungen von Anbietern sind einfacher und erfordern keinen Build-Schritt, können aber umfangreicher sein.

AgentCore Runtime unterstützt nur die arm64-Befehlssatzarchitektur. Wenn Ihr Agent npm-Pakete verwendet, die native Module (kompiliert .node oder .so Dateien) enthalten, müssen diese Binärdateien für Linux arm64 kompiliert werden.

AgentCore Runtime validiert die Architektur aller .node .so AND-Dateien in Ihrem Bereitstellungspaket, indem sie deren ELF-Header liest. Wenn eine Binärdatei für eine andere Architektur kompiliert wurde (z. B. x86_64 oder macOS), schlägt Ihre Agentenerstellung mit Status fehl. CREATE_FAILED

So installieren Sie arm64-kompatible native Module:

Installieren Sie Abhängigkeiten auf einem arm64-Computer (z. B. einer AWS Graviton-based Amazon EC2 EC2-Instance)
Verwenden Sie NPMs --arch und Flags: --platform
```
npm install --arch=arm64 --platform=linux
```
Verwenden Sie esbuild, um Ihren Code zu bündeln, wenn das native Modul zur Laufzeit vermieden werden kann

Die beliebtesten npm-Pakete (Express, Axios, Fastify, Hono, ws) sind reine Pakete JavaScript und enthalten keine nativen Module.

AgentCore Runtime führt TypeScript Dateien nicht direkt aus. Sie müssen Ihren TypeScript Quellcode JavaScript vor der Bereitstellung kompilieren. Dies ist das gleiche Muster, das von AWS Lambda verwendet wird.

Mit dem TypeScript Compiler (tsc):


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

Verpacken Sie dann die kompilierte Ausgabe:


cd dist
zip -r ../deployment_package.zip .

Wenn Sie den Agenten erstellen, legen Sie den Einstiegspunkt auf die kompilierte .js Datei fest (z. B. app.js oder dist/app.js abhängig von Ihrer ZIP-Struktur).

Verwendung von esbuild (empfohlen für einfachere Paketierungen):


npx esbuild app.ts --bundle --platform=node --target=node22 --outfile=app.js
zip deployment_package.zip app.js

esbuild kompiliert TypeScript und bündelt Abhängigkeiten in einem einzigen Schritt und erzeugt so eine kleine, eigenständige Datei. .js

Wenn Sie ein package.json engines.node Feld angeben, überprüft AgentCore Runtime, ob der angegebene Bereich mit der von Ihnen ausgewählten Node.js Version kompatibel ist (z. B. Node.js 22, wenn Sie die Runtime verwenden). NODE_22 Wenn der Bereich diese Version ausschließt, schlägt Ihre Agentenerstellung mit Status fehl. CREATE_FAILED

Die folgenden engines Deklarationen sind beispielsweise mit Node.js 22 kompatibel:


{ "engines": { "node": ">=18" } }
{ "engines": { "node": ">=14 <18 || >=20" } }
{ "engines": { "node": "22" } }

Die folgenden Deklarationen sind nicht kompatibel und führen dazu, dass die Agentenerstellung fehlschlägt:


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

AgentCore Runtime überprüft das engines.node Feld auch auf allgemeine Abhängigkeiten in Ihremnode_modules/. Wenn eine dieser Optionen einen Node.js Versionsbereich deklariert, der die Ziel-Laufzeitversion ausschließt, schlägt die Agentenerstellung fehl.

Wenn Sie auf eine engines.node Inkompatibilität stoßen, aktualisieren Sie das Paket auf eine Version, die Ihre Node.js Zielversion unterstützt, oder entfernen Sie das engines Feld aus Ihrer. package.json Informationen zu unterstützten Node.js Versionen finden Sie unter Unterstützte Sprachlaufzeiten.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Direkte Codebereitstellung für Python

Unterstützte Laufzeiten und veraltete Versionen