Node.js の直接コードデプロイ

直接コードデプロイを使用すると、エージェントコードとその依存関係を .zip ファイルアーカイブにパッケージ化するだけで、Node.js ベースのエージェントを Amazon Bedrock AgentCore ランタイムに持ち込むことができます。エージェントは引き続き AgentCore ランタイム要件に従う必要があります。POST および /ping GET /invocations サーバーエンドポイントを実装するエントリポイント.jsファイルが必要です。

依存関係は、ZIP node_modules/でベンダーとして、または esbuild バンドルされた単一.jsファイルとして含めることができます。

前提条件

開始する前に、以下があることを確認してください。

ステップ 1: プロジェクトをセットアップし、依存関係をインストールする

次のコマンドを使用してプロジェクトを初期化します。

mkdir agentcore_runtime_node_deploy
cd agentcore_runtime_node_deploy
npm init -y

必要に応じて、 npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation を実行して Amazon Bedrock AgentCore オブザーバビリティトレースを有効にします。

ステップ 2: エージェントコードを作成する

エージェントエントリポイントを作成します。エージェントは、/pingGET ヘルスエンドポイントと POST ハンドラーを使用して AgentCore Runtime HTTP /invocations 契約を実装する必要があります。

ステップ 3: ローカルでテストする

開始する前に、ポート 8080 が空いていることを確認してください。一般的な問題と解決策の「使用中のポート 8080 (ローカルのみ)」を参照してください。

ターミナルウィンドウを開き、エージェントを起動します。

ステップ 4: エージェントのオブザーバビリティを有効にする

Amazon Bedrock AgentCore オブザーバビリティは、AgentCore ランタイムでホストするエージェントをトレース、デバッグ、モニタリングするのに役立ちます。まず、「Amazon Bedrock AgentCore ランタイムオブザーバビリティを有効にする」の手順に従って CloudWatch トランザクション検索を有効にします。エージェントを監視するには、「Amazon Bedrock AgentCore エージェントのオブザーバビリティデータを表示する」を参照してください。

Node.js エージェントの自動計測を有効にするには、ADOT パッケージを追加します。

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

デプロイするときは、ZIP node_modules/に を含め、エントリポイントに opentelemetry-instrument プレフィックスを使用します (ステップ 5 を参照）。

ステップ 5: AgentCore ランタイムにデプロイして呼び出す

エージェントコードと依存関係を含む .zip ファイルを作成します。AgentCore ランタイムは arm64 命令セットアーキテクチャのみをサポートします。ネイティブモジュール (.node ファイル) が arm64 用にコンパイルされていることを確認します。

Linux arm64 依存関係を含む ZIP アーカイブは、エージェントランタイムを作成する前提条件として S3 にアップロードする必要があります。次のコードでは、指定された S3 バケットがすでに存在している必要があります。バケットを作成するには、こちらの AWS ドキュメントに従ってください。次の TypeScript コードは、.zip ファイルアーカイブを S3 にアップロードし、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}`);

OTEL 自動計測を有効にするには、ZIP node_modules/@aws/aws-distro-opentelemetry-node-autoinstrumentation/に を含め、エントリポイントに opentelemetry-instrument プレフィックスを使用します。

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

Amazon Bedrock AgentCore ランタイムでエージェントをプログラムで呼び出すには、「Invoke an agent programmatically」を参照してください。

ステップ 6: セッション、更新、またはクリーンアップを停止する

次の TypeScript コードは AgentCore ランタイムを更新します。新しいデプロイパッケージを S3 にアップロードし、 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}`);

設定可能な IdleRuntimeSessionTimeout (デフォルトは 15 分) より前に実行中のセッションを停止し、潜在的なランアウェイコストを節約するには、次のコードを使用します。

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 コードでは、Amazon Bedrock AgentCore ランタイムと .zip アーカイブファイルが 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 固有の概念

Amazon Bedrock AgentCore ランタイムで直接コードデプロイを使用する場合の Node.js 固有の概念について説明します。

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" } }