View a markdown version of this page

Déploiement direct de code pour Node.js - Substrat rocheux d'Amazon AgentCore

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Déploiement direct de code pour Node.js

Avec le déploiement direct du code, vous pouvez empaqueter votre Node.js le code de l'agent et ses dépendances dans une archive de fichiers .zip et déployez-le sur AgentCore Durée d'exécution. Votre agent doit toujours suivre AgentCore Exigences en matière d'exécution : disposer d'un point d'entrée .js fichier qui implémente /invocations POST et /ping Points de terminaison du serveur GET.

Vous pouvez inclure des dépendances soit en tant que fournisseur node_modules/ dans votre ZIP ou en tant que single groupé avec esbuild .js dossier.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

Étape 1 : Configuration du projet et installation des dépendances

Initialisez votre projet à l'aide des commandes suivantes :

mkdir agentcore_runtime_node_deploy cd agentcore_runtime_node_deploy npm init -y

Si vous le souhaitez, exécutez npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation pour activer Base rocheuse de l'Amazonie AgentCore traces d'observabilité.

Étape 2 : Créez votre code d'agent

Créez le point d'entrée de votre agent. Votre agent doit mettre en œuvre le AgentCore Contrat HTTP d'exécution avec un /ping GET Health Endpoint et /invocations gestionnaire POST.

Exemple
Strands Agents SDK

Installez le Kit de développement logiciel Strands Agents et ses dépendances :

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

Créez un fichier nommé 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); });

Compilez le TypeScript pour JavaScript:

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

La sortie compilée dans dist/app.js est ce que vous déployez. Lors de la création de l'agent, utilisez "entryPoint": ["dist/app.js"] — le compilé JavaScript sortie, pas .ts source.

HTTP (no framework)

Cet exemple utilise la fonction intégrée node:http module sans dépendances externes.

Créez un fichier nommé 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); });

Étape 3 : Testez localement

Assurez-vous que le port 8080 est libre avant de démarrer.

Ouvrez une fenêtre de terminal et démarrez votre agent :

Exemple
Strands Agents SDK
node dist/app.js

Ouvrez une autre fenêtre de terminal et appelez l'agent :

curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "What time is it right now?"}'

Succès : Vous devriez voir une réponse contenant l'heure actuelle renvoyée par l'agent current_time outil. Dans la fenêtre du terminal qui exécute l'agent, entrez Ctrl+C pour arrêter l'agent.

HTTP (no framework)
node app.js

Ouvrez une autre fenêtre de terminal et appelez l'agent :

curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "Hello!"}'

Succès : Vous devriez voir une réponse comme {"result": "Hello from Node.js managed runtime! You said: Hello!","runtime":"NODE_22",…​} . Dans la fenêtre du terminal qui exécute l'agent, entrez Ctrl+C pour arrêter l'agent.

Étape 4 : Activez l'observabilité pour votre agent

Base rocheuse de l'Amazonie AgentCore Observabilité vous permet de suivre, de déboguer et de surveiller les agents que vous hébergez dans AgentCore Durée d'exécution. Activez d'abord CloudWatch Recherchez des transactions en suivant les instructions sur Activation d'Amazon Bedrock AgentCore observabilité de l'exécution . Pour observer votre agent, consultez Afficher les données d'observabilité de votre Amazon Bedrock AgentCore agents.

Pour activer l'instrumentation automatique pour votre Node.js agent, ajoutez le package ADOT :

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

L'auto-instrumentation ADOT fonctionne par application de patchs Node.js require() appels au moment de l'exécution. Cela signifie qu'il n'est compatible qu'avec la sortie du module CommonJS. Si vous compilez TypeScript avec --module nodenext ou --module esnext (production d'ESM) import instructions), l'instrumentation ADOT échoue silencieusement et aucune trace n'est émise. Pour utiliser ADOT, compilez avec --module commonjs ou utilisez esbuild avec --platform=node (qui conserve require() appels pour Node.js modules intégrés).

Lors du déploiement, incluez node_modules/ dans votre ZIP et utilisez opentelemetry-instrument préfixe dans votre point d'entrée (voir Étape 5).

Étape 5 : Déploiement sur AgentCore Exécuter et invoquer

Note

AgentCore Le runtime ne s'exécute pas TypeScript (.ts) fichiers en mode natif. Vous devez transpiler TypeScript pour JavaScript avant le déploiement. Pour plus d'informations, consultez Travailler avec TypeScript .

Créez un fichier .zip contenant le code de votre agent et ses dépendances. AgentCore Runtime ne prend en charge que bras 64 architecture du jeu d'instructions — assurez-vous que tous les modules sont natifs (.node fichiers) sont compilés pour arm64.

Exemple
Strands Agents SDK

Package de la sortie compilée et des dépendances fournisseurs :

npm install --production zip -r deployment_package.zip dist/ node_modules/ package.json

Lors de la création de l'agent, utilisez "entryPoint": ["dist/app.js"] — le compilé JavaScript sortie, pas .ts source.

HTTP (no framework)

Comme cet exemple ne comporte aucune dépendance externe, seul le fichier du point d'entrée est nécessaire :

zip deployment_package.zip app.js

Lors de la création de l'agent, utilisez "entryPoint": ["app.js"] .

Note
  1. Taille maximale d'un package de déploiement .zip pour AgentCore Le temps d'exécution est de 250 Mo (compressé) et 750 Mo (décompressé). Cette limite s'applique à la taille combinée de tous les fichiers que vous chargez.

  2. Le AgentCore Runtime a besoin d'une autorisation pour lire les fichiers de votre package de déploiement. Dans la notation octale des autorisations Linux, AgentCore L'exécution a besoin de 644 autorisations pour les fichiers non exécutables (rw-r—r--) et de 755 autorisations (rwxr-xr-x) pour les répertoires et les fichiers exécutables.

  3. Sous Linux et macOS, utilisez la commande chmod pour modifier les autorisations de fichiers sur les fichiers et les répertoires de votre package de déploiement. Par exemple, pour attribuer les autorisations appropriées à un fichier non exécutable, exécutez la commande suivante, chmod 644 <filepath> . Pour modifier les autorisations relatives aux fichiers dans Windows, voir Définir, afficher, modifier ou supprimer des autorisations sur un objet dans la documentation Microsoft Windows.

    1. Si vous n'accordez pas AgentCore Exécutez les autorisations dont il a besoin pour accéder aux répertoires de votre package de déploiement, AgentCore Runtime définit les autorisations pour ces répertoires sur 755 (rwxr-xr-x).

Une archive ZIP contenant Linux bras 64 les dépendances doivent être téléchargées vers S3 comme condition préalable à Create Agent Runtime. Le code ci-dessous nécessite que le compartiment S3 spécifié existe déjà. Pour créer un bucket, voir Création d'un seau à usage général dans le guide de l'utilisateur d'Amazon S3. Ce qui suit TypeScript le code téléchargera l'archive du fichier .zip sur S3 et créera un Amazon Bedrock AgentCore exécution.

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

Pour activer l'auto-instrumentation OTEL, incluez node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ dans votre ZIP et utilisez opentelemetry-instrument préfixe au point d'entrée :

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

Pour appeler un agent sur Amazon Bedrock AgentCore Exécutez par programmation, voir Invoquer un AgentCore Agent d'exécution avec AWS SDK.

Étape 6 : arrêt de la session, mise à jour ou nettoyage

Suivant TypeScript le code mettra à jour un AgentCore Durée d'exécution. Téléchargez le nouveau package de déploiement sur S3, puis appelez 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}`);

Pour arrêter la session en cours avant la configuration IdleRuntimeSessionTimeout (15 minutes par défaut) et pour économiser sur d'éventuels coûts exorbitants, utilisez le code suivant :

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!");

Suivant TypeScript le code supprimera un Amazon Bedrock AgentCore runtime et le fichier d'archive .zip dans 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 concepts pour le déploiement direct de code

En savoir plus sur Node.js-specific concepts relatifs à l'utilisation du déploiement direct de code avec Amazon Bedrock AgentCore Durée d'exécution.

Rubriques

    AgentCore Durée d'exécution pour Node.js accepte uniquement .js points d'entrée. TypeScript fichiers (.ts) ne sont pas acceptées directement — vous devez les transpiler vers JavaScript avant l'emballage. Nous vous recommandons d'utiliser esbuild pour transpiler et regrouper en une seule étape. Ajoutez esbuild en tant que dépendance de développement avec npm install -D esbuild .

    Les points d'entrée peuvent se trouver dans des sous-répertoires. Par exemple, src/app.js ou dist/index.js sont des points d'entrée valides. Node.js la résolution du module parcourt l'arborescence des répertoires à partir de l'emplacement du point d'entrée, donc les dépendances dans node_modules/ à la racine de votre ZIP sont trouvés automatiquement — non NODE_PATH une configuration est nécessaire.

    Lorsque vous spécifiez un point d'entrée de sous-répertoire, assurez-vous que le chemin dans votre entryPoint la configuration correspond au chemin dans le fichier ZIP.

    Il existe deux approches pour empaqueter les dépendances pour Node.js agents :

    Dépendances fournisseurs (les plus simples) :

    Inclure node_modules/ directement dans votre code postal à côté de votre point d'entrée :

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

    Cela produit un ZIP avec la structure suivante :

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

    Fourni avec esbuild (le plus petit ZIP) :

    Utiliser esbuild pour regrouper toutes les dépendances dans un seul fichier :

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

    Cela produit un ZIP minimal :

    my-agent.zip
    └── bundle.js

    Les deux approches fonctionnent. Les déploiements groupés sont généralement inférieurs à 10 Mo et se déploient plus rapidement. Les déploiements fournis par les fournisseurs sont plus simples et ne nécessitent pas d'étape de génération, mais peuvent être plus importants.

    AgentCore Runtime ne prend en charge que bras 64 architecture du jeu d'instructions. Si votre agent utilise des packages npm qui incluent des modules natifs (compilés) .node ou .so files), ces fichiers binaires doivent être compilés pour Linux arm64.

    AgentCore Runtime valide l'architecture de tous .node et .so fichiers de votre package de déploiement en lisant leurs en-têtes ELF. Si un fichier binaire est compilé pour une architecture différente (telle que x86_64 ou macOS), la création de votre agent échouera avec le statut CREATE_FAILED .

    Pour installer des modules natifs compatibles avec arm64 :

    • Installez les dépendances sur une machine arm64 (telle qu'un AWS Graviton-based Amazon EC2 (instance)

    • Utilisez les npm --arch et --platform drapeaux :

      npm install --arch=arm64 --platform=linux
    • Utilisez esbuild pour regrouper votre code si le module natif peut être évité lors de l'exécution

    Les packages npm les plus populaires (Express, Axios, Fastify, Hono, ws) sont purs JavaScript et ne contiennent pas de modules natifs.

    AgentCore Le runtime ne s'exécute pas TypeScript fichiers directement. Vous devez compiler votre TypeScript code source pour JavaScript avant le déploiement. Il s'agit du même modèle que celui utilisé par AWS Lambda.

    À l'aide du TypeScript compilateur (tsc) :

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

    Ensuite, empaquetez la sortie compilée :

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

    Lors de la création de l'agent, définissez le point d'entrée sur le compilé .js fichier (par exemple, app.js ou dist/app.js en fonction de votre structure ZIP).

    En utilisant esbuild (recommandé pour simplifier l'empaquetage) :

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

    esbuild compile TypeScript et regroupe les dépendances en une seule étape, produisant ainsi un petit .js dossier.

    Si votre package.json comprend un engines.node terrain, AgentCore Runtime valide que la plage spécifiée est compatible avec Node.js version que vous avez sélectionnée (par exemple, Node.js 22 lors de l'utilisation du NODE_22 exécution). Si la plage exclut cette version, la création de votre agent échouera avec le statut CREATE_FAILED .

    Par exemple, ce qui suit engines les déclarations sont compatibles avec Node.js 22 :

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

    Les déclarations suivantes sont incompatibles et entraîneront l'échec de la création de l'agent :

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

    AgentCore Runtime vérifie également engines.node champ pour les dépendances courantes dans votre node_modules/ . Si l'un d'entre eux déclare un Node.js plage de versions qui exclut la version d'exécution cible, la création de l'agent échouera.

    Si vous rencontrez un engines.node incompatibilité, mettez à jour le package vers une version compatible avec votre cible Node.js version ou supprimez le engines champ depuis votre package.json . Pour les personnes soutenues Node.js versions, voir Exécutions linguistiques prises en charge.