直接部署代码 Node.js

直接部署代码使您只需将 Node.js-based 代理代码及其依赖项打包到.zip 文件存档中即可将代理引入 Amazon Bedrock Runt AgentCore ime。您的代理仍然需要遵循AgentCore 运行时要求：拥有一个实现 P /invocations OST 和 /ping GET 服务器端点的入口点.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 步：创建您的代理代码

创建您的代理入口点。您的代理必须使用 GET AgentCore 运行状况端点和 P /invocations OS /ping T 处理程序实现运行时 HTTP 合约。

第 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

部署时，请node_modules/在 ZIP 中包含并在入口点中使用opentelemetry-instrument前缀（参见步骤 5）。

步骤 5：部署到 AgentCore 运行时并调用

使用您的代理代码和依赖项创建一个.zip 文件。 AgentCore Runtime 仅支持 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 运行时上调用代理，请参阅：以编程方式调用代理

步骤 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 运行时和 S3 中的.zip 存档文件。

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 直接代码部署的概念

了解在 Amazon Bedrock Runt AgentCore ime 中使用直接代码部署时的 Node.js-specific 概念。

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