跳到主要内容

将 Mastra 部署到 Amazon Bedrock AgentCore

使用 AgentCore CLI 将 Mastra 应用部署到 Amazon Bedrock AgentCore Runtime。该 CLI 会搭建自带代码（BYO）TypeScript 项目，使用 AWS CodeBuild 构建容器，并预置 Runtime。部署不需要本地 Docker daemon。

本指南遵循官方 AgentCore TypeScript 演练，并对其进行调整，以便从调用 handler 中调用 Mastra Agent。

信息

如需基于 Lambda 部署完整 Mastra Server，请参阅 AWS Lambda 指南。如需使用长时运行的虚拟机，请参阅 Amazon EC2 指南。

开始之前
开始之前的直接链接

你需要：

  • 一个拥有 Amazon Bedrock AgentCore、AWS CodeBuild、Amazon ECR 和 AWS IAM 权限的 AWS 账户
  • 已安装并完成身份验证的 AWS CLI（aws configure 或 aws sso login）
  • 已安装 Node.js v22.13.0 或更高版本
  • 使用 agentcore dev 进行本地测试所需的 Docker、Podman 或 Finch（agentcore deploy 不需要）

Amazon Bedrock AgentCore Runtime 仅在部分 AWS 区域可用。请使用 AgentCore 可用且已启用计划调用基础模型的区域。

创建新的 AgentCore 项目
创建新的 AgentCore 项目的直接链接

运行以下命令创建新的 AgentCore 项目：

npx @aws/agentcore create --name MastraOnAgentCore --no-agent

进入新创建的 MastraOnAgentCore 目录：

cd MastraOnAgentCore

初始化一个 BYO TypeScript Agent，它将创建在 app/MastraAgent 中：

npx @aws/agentcore add agent --name MastraAgent --type byo --build Container --language TypeScript --framework Strands --model-provider Bedrock --code-location app/MastraAgent

CLI 会修改 agentcore/agentcore.json 文件，并创建空的 app/MastraAgent 目录。

设置 Agent 项目
设置 Agent 项目的直接链接

进入 app/MastraAgent 目录并初始化新的 Node.js 项目：

cd app/MastraAgent
npm init --init-type=module -y

安装所需依赖。bedrock-agentcore 包提供实现 AgentCore Runtime 服务契约的 BedrockAgentCoreApp HTTP Server。@ai-sdk/amazon-bedrock 和 @aws-sdk/credential-providers 包让 Mastra Agent 可以通过 AgentCore Runtime 执行角色调用 Bedrock：

npm install bedrock-agentcore @opentelemetry/auto-instrumentations-node @ai-sdk/amazon-bedrock @aws-sdk/credential-providers --legacy-peer-deps

另外安装 TypeScript 和相关开发依赖：

npm install --save-dev typescript @types/node tsx

运行 mastra init 设置新的 Mastra 项目。提示中选择的 Provider 会在下一步被覆盖，因此可以选择任意值：

npx mastra@latest init

替换生成的 src/mastra/agents/weather-agent.ts，使其使用 Amazon Bedrock。原有的 memory: new Memory() 已移除，因为下一步会移除 Storage 层：

app/MastraAgent/src/mastra/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent'
import { createAmazonBedrock } from '@ai-sdk/amazon-bedrock'
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'
import { weatherTool } from '../tools/weather-tool.js'

const bedrock = createAmazonBedrock({
  credentialProvider: fromNodeProviderChain(),
})

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions:
    'You are a helpful weather assistant. Use the weatherTool to fetch current weather data.',
  model: bedrock('us.anthropic.claude-sonnet-4-6'),
  tools: { weatherTool },
})
备注

fromNodeProviderChain() 让 Agent 可以通过标准 SDK 解析链（环境变量、共享配置文件、SSO 以及容器或 EC2 角色）获取 AWS 凭证，而不是只能通过环境变量获取。

替换生成的 src/mastra/index.ts，移除默认的基于文件的 Storage 和 observability 配置。AgentCore Runtime 容器以非 root 用户身份运行，应用目录为只读，因此默认 LibSQLStore 无法打开 ./mastra.db，导致 Runtime 启动失败：

app/MastraAgent/src/mastra/index.ts
import { Mastra } from '@mastra/core/mastra'
import { PinoLogger } from '@mastra/loggers'
import { weatherWorkflow } from './workflows/weather-workflow.js'
import { weatherAgent } from './agents/weather-agent.js'

export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})

创建包含以下内容的 tsconfig.json 文件：

app/MastraAgent/tsconfig.json
{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": ".",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "forceConsistentCasingInFileNames": true
  },
  "include": ["*.ts", "src/**/*"],
  "exclude": ["node_modules", "dist"]
}
备注

添加 tsconfig.json 文件后，编辑器会在生成的 src/mastra 项目中显示错误。这是预期行为，因为该配置现在要求 import 包含文件扩展名。可以通过添加 .js 修复，例如：

app/MastraAgent/src/mastra/index.ts
// Before
import { weatherWorkflow } from './workflows/weather-workflow'
// After
import { weatherWorkflow } from './workflows/weather-workflow.js'

更新 package.json 以设置入口点和构建脚本。使用 npm pkg set 可以保留 mastra init 添加的依赖：

npm pkg set main=dist/agent.js scripts.build=tsc scripts.start="node dist/agent.js" scripts.dev="npx tsx --watch agent.ts"

初始化 Agent
初始化 Agent的直接链接

创建 agent.ts 文件。每个 POST /invocations 请求都会调用此 handler。在 handler 中解析并调用 Mastra Agent：

app/MastraAgent/agent.ts
import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime'
import { mastra } from './src/mastra/index.js'

const app = new BedrockAgentCoreApp({
  invocationHandler: {
    process: async (payload, context) => {
      const { prompt } = payload as { prompt: string }

      const agent = mastra.getAgentById('weather-agent')
      const response = await agent.generate(prompt, {
        runId: context.sessionId,
      })

      return response.text
    },
  },
})

app.run()

运行 npm run build，验证项目能否成功编译。

创建 Dockerfile
创建 Dockerfile的直接链接

在 app/MastraAgent 目录中创建 Dockerfile。基于容器的部署使用多阶段 Docker 构建：builder 阶段将 TypeScript 编译为 JavaScript，生产阶段只运行编译后的输出。为保证安全，镜像以非 root 用户身份运行，并暴露 8080（HTTP）、8000（MCP）和 9000（A2A）端口。启动时会自动包含 OpenTelemetry instrumentation。

app/MastraAgent/Dockerfile
FROM node:22-slim AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim
WORKDIR /app
ENV AWS_REGION=us-east-1
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./

RUN useradd -m bedrock_agentcore
USER bedrock_agentcore

EXPOSE 8080 8000 9000
CMD ["node", "--require", "@opentelemetry/auto-instrumentations-node/register", "dist/agent.js"]
备注

请选择与 Bedrock 模型 ID 前缀（us.、jp.、eu. 或 global.）相匹配的 AWS_REGION。

还要创建 .dockerignore 文件，从 Docker 构建上下文中排除不必要的文件：

node_modules
dist
.git
*.log

测试 Agent
测试 Agent的直接链接

返回项目根目录：

cd ../..

在本地测试 Agent：

npx @aws/agentcore dev --runtime MastraAgent

在另一个终端中发送测试请求：

npx @aws/agentcore dev "What is the weather in Tokyo?"

部署 Agent
部署 Agent的直接链接

在 agentcore/aws-targets.json 中设置 AWS 账户和区域：

agentcore/aws-targets.json
[
  {
    "name": "default",
    "account": "123456789012",
    "region": "us-east-1"
  }
]

部署到 AgentCore Runtime。CLI 会使用 AWS CodeBuild 构建镜像，将其推送到 Amazon ECR，并创建 Runtime 和 DEFAULT 端点：

npx @aws/agentcore deploy
备注

部署前，请在 agentcore/agentcore.json 中 Agent 的 environmentVariables 字段下设置 Provider API Key 和其他 secret。

验证部署
验证部署的直接链接

运行 agentcore status 查看 Runtime ARN、端点和最近的调用。然后从 CLI 调用已部署的 Agent：

npx @aws/agentcore invoke "What is the weather in Tokyo?"

如需在 token 生成时进行流式传输，请使用 --stream：

npx @aws/agentcore invoke --stream "Plan a 3-day trip to Tokyo"
On this page