Déploiement direct du 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 regroupant le code de l'agent et ses dépendances dans une archive de fichier .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 fichier ZIP ou sous forme de fichier unique fourni 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

Exécutez éventuellement 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 point de terminaison de santé /ping GET et un gestionnaire /invocations POST.

Étape 3 : Tester localement

Assurez-vous que le port 8080 est libre avant de démarrer. Voir Port 8080 en cours d'utilisation (local uniquement) dans Problèmes courants et solutions.

Ouvrez une fenêtre de terminal et lancez 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 Transaction Search en suivant les instructions de la section Activer l'observabilité du AgentCore runtime Amazon Bedrock. Pour observer votre agent, consultez 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 vers AgentCore Runtime et invoquer

Créez un fichier .zip avec 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 natifs (.nodefichiers) sont compilés pour arm64.

Une archive ZIP contenant des dépendances 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 ici pour créer un bucket. Le TypeScript code suivant téléchargera l'archive de fichiers .zip dans 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, node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/ incluez-le dans votre ZIP et utilisez le opentelemetry-instrument préfixe dans le point d'entrée :

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

Pour appeler un agent sur Amazon Bedrock AgentCore Runtime par programmation, reportez-vous à : Invoquer un agent par programmation

Étape 6 : arrêt de 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 d'éventuels coûts supplémentaires, 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 les Node.js-specific concepts liés à l'utilisation du 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" } }