Déploiement direct de code pour Node.js

Le déploiement direct du code vous permet d'intégrer votre Node.js-based agent à Amazon Bedrock AgentCore Runtime simplement en empaquetant le code de l'agent et ses dépendances dans une archive de fichiers .zip. Votre agent doit toujours respecter les exigences AgentCore d'exécution  : disposer d'un .js fichier de point d'entrée qui implémente les points de terminaison des serveurs /invocations POST et /ping GET.

Vous pouvez inclure les dépendances telles qu'elles sont fournies node_modules/ dans votre ZIP ou sous la forme d'un fichier unique groupé par esbuild. .js

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 les traces d' AgentCore observabilité d'Amazon Bedrock.

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

Créez le point d'entrée de votre agent. Votre agent doit implémenter le contrat HTTP AgentCore Runtime avec un endpoint /ping GET health et un gestionnaire /invocations POST.

Étape 3 : Testez localement

Assurez-vous que le port 8080 est libre avant de démarrer. Consultez la section Résoudre les problèmes si le port est déjà utilisé.

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

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

Amazon Bedrock AgentCore Observability vous permet de suivre, de déboguer et de surveiller les agents que vous hébergez dans Runtime. AgentCore Activez d'abord CloudWatch la recherche de transactions en suivant les instructions de la section Activation de l'observabilité de l' AgentCore environnement d'exécution d'Amazon Bedrock. Pour observer votre agent, voir Afficher les données d'observabilité de vos agents Amazon Bedrock AgentCore .

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

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

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

Étape 5 : Déployer sur AgentCore Runtime et invoquer

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

Une archive ZIP contenant les dépendances de Linux arm64 doit être téléchargée sur S3 comme condition préalable à Create Agent Runtime. Le code ci-dessous nécessite que le compartiment S3 spécifié existe déjà. Veuillez suivre la AWS documentation disponible ici pour créer un bucket. Le TypeScript code suivant téléchargera l'archive du fichier .zip sur S3 et créera un environnement d'exécution 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}`);

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

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

Pour appeler un agent sur Amazon Bedrock AgentCore Runtime par programmation, voir Invoquer un agent par programmation.

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

TypeScript Le code suivant mettra à jour un AgentCore Runtime. 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 économiser sur les é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!");

TypeScript Le code suivant supprimera un environnement d' AgentCore exécution Amazon Bedrock 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

Découvrez Node.js-specific les concepts liés au déploiement direct de code avec Amazon Bedrock AgentCore Runtime.

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

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

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

my-agent.zip
└── bundle.js

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

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

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

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

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