跳至主要內容

將 Mastra 部署至 Amazon Bedrock AgentCore

使用 AgentCore CLI 將 Mastra 應用程式部署至 Amazon Bedrock AgentCore Runtime。CLI 會建立自備程式碼（BYO）的 TypeScript 專案骨架、使用 AWS CodeBuild 建置容器，並佈建 Runtime。部署時不需要本機 Docker 常駐程式。

本指南依循官方 AgentCore TypeScript 逐步指南，並調整為從叫用處理常式呼叫 Mastra Agent。

資訊

若要以 Lambda 部署完整 Mastra 伺服器，請參閱 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

初始化將建立於 app/MastraAgent 內的 BYO TypeScript Agent：

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 伺服器。@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()：

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，移除預設的檔案型儲存空間和可觀測性設定。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 專案中顯示錯誤。這是預期行為，因為目前的設定要求匯入項目包含副檔名。你可以加入 .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 要求都會呼叫此處理常式。在處理常式內解析並呼叫 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 建置：建置階段會將 TypeScript 編譯為 JavaScript，正式環境階段則只執行編譯後的輸出。為了安全，映像檔會以非 root 使用者執行，並公開 8080（HTTP）、8000（MCP）和 9000（A2A）連接埠。啟動時會自動包含 OpenTelemetry 檢測。

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 金鑰和其他密鑰。

驗證部署
「驗證部署」的直接連結

執行 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