Aller au contenu principal

Déployer Mastra sur Amazon Bedrock AgentCore

Déployez votre application Mastra sur Amazon Bedrock AgentCore Runtime avec la CLI AgentCore. La CLI génère le squelette d’un projet TypeScript où vous apportez votre propre code, ou BYO, crée le conteneur avec AWS CodeBuild et provisionne le runtime. Un démon Docker local n’est pas nécessaire pour le déploiement.

Ce guide suit le tutoriel TypeScript officiel d’AgentCore et l’adapte afin d’appeler un Agent Mastra depuis le gestionnaire d’invocation.

info

Pour un déploiement du serveur Mastra complet basé sur Lambda, consultez le guide AWS Lambda. Pour une machine virtuelle de longue durée, consultez le guide Amazon EC2.

Avant de commencer
Lien direct vers Avant de commencer

Vous aurez besoin de :

  • Un compte AWS disposant d’autorisations pour Amazon Bedrock AgentCore, AWS CodeBuild, Amazon ECR et AWS IAM
  • La CLI AWS installée et authentifiée, avec aws configure ou aws sso login
  • Node.js v22.13.0 ou version ultérieure installé
  • Docker, Podman ou Finch pour les tests locaux avec agentcore dev, non requis pour agentcore deploy

Amazon Bedrock AgentCore Runtime est disponible dans un sous-ensemble des régions AWS. Utilisez une région où AgentCore est disponible et où les modèles de fondation que vous prévoyez d’appeler sont activés.

Créer un projet AgentCore
Lien direct vers Créer un projet AgentCore

Exécutez la commande suivante pour créer un projet AgentCore :

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

Accédez au répertoire MastraOnAgentCore qui vient d’être créé :

cd MastraOnAgentCore

Initialisez un Agent TypeScript BYO qui sera créé dans app/MastraAgent :

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

La CLI modifie le fichier agentcore/agentcore.json et crée un répertoire app/MastraAgent vide.

Configurer le projet de l’Agent
Lien direct vers Configurer le projet de l’Agent

Accédez au répertoire app/MastraAgent et initialisez un nouveau projet Node.js :

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

Installez les dépendances requises. Le package bedrock-agentcore fournit le serveur HTTP BedrockAgentCoreApp, qui implémente le contrat de service AgentCore Runtime. Les packages @ai-sdk/amazon-bedrock et @aws-sdk/credential-providers permettent à l’Agent Mastra d’appeler Bedrock par le rôle d’exécution AgentCore Runtime :

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

Installez également TypeScript et les dépendances de développement associées :

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

Exécutez mastra init pour configurer un nouveau projet Mastra. Le fournisseur choisi dans le prompt est remplacé à l’étape suivante ; toute valeur convient donc :

npx mastra@latest init

Remplacez le fichier src/mastra/agents/weather-agent.ts généré afin d’utiliser Amazon Bedrock. La valeur memory: new Memory() d’origine est supprimée, car la couche de stockage sera supprimée à l’étape suivante :

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 },
})
remarque

fromNodeProviderChain() permet à l’Agent de récupérer les identifiants AWS avec la chaîne de résolution SDK standard, notamment les variables d’environnement, les fichiers de configuration partagés, SSO et les rôles de conteneur ou EC2, plutôt qu’uniquement par les variables d’environnement.

Remplacez le fichier src/mastra/index.ts généré pour supprimer la configuration par défaut du stockage basé sur fichiers et de l’observabilité. Les conteneurs AgentCore Runtime s’exécutent avec un utilisateur non-root et un répertoire d’application en lecture seule ; le LibSQLStore par défaut ne peut donc pas ouvrir ./mastra.db et le runtime échoue au démarrage :

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',
  }),
})

Créez un fichier tsconfig.json avec le contenu suivant :

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

Après l’ajout du fichier tsconfig.json, votre éditeur affichera des erreurs dans le projet src/mastra généré. C’est attendu, car la configuration requiert désormais des extensions de fichiers dans les imports. Vous pouvez les corriger en ajoutant .js, par exemple :

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

Mettez à jour votre package.json pour définir le point d’entrée et les scripts de création. L’utilisation de npm pkg set conserve les dépendances ajoutées par 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"

Initialiser l’Agent
Lien direct vers Initialiser l’Agent

Créez un fichier agent.ts. Ce gestionnaire est appelé pour chaque requête POST /invocations. Récupérez l’Agent Mastra et appelez-le dans le gestionnaire :

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()

Exécutez npm run build pour vérifier que votre projet se compile correctement.

Créer un Dockerfile
Lien direct vers Créer un Dockerfile

Créez un Dockerfile dans le répertoire app/MastraAgent. Le déploiement fondé sur des conteneurs utilise une création Docker en plusieurs étapes : l’étape de création compile TypeScript en JavaScript, tandis que l’étape de production n’exécute que la sortie compilée. L’image s’exécute avec un utilisateur non-root pour la sécurité et expose les ports 8080 pour HTTP, 8000 pour MCP et 9000 pour A2A. L’instrumentation OpenTelemetry est incluse automatiquement au démarrage.

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"]
remarque

Choisissez une valeur AWS_REGION correspondant au préfixe d’identifiant de votre modèle Bedrock : us., jp., eu. ou global..

Créez également un fichier .dockerignore pour exclure les fichiers inutiles du contexte de création Docker :

node_modules
dist
.git
*.log

Tester votre Agent
Lien direct vers Tester votre Agent

Revenez à la racine du projet :

cd ../..

Testez votre Agent localement :

npx @aws/agentcore dev --runtime MastraAgent

Dans un terminal distinct, envoyez une requête de test :

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

Déployer votre Agent
Lien direct vers Déployer votre Agent

Définissez le compte AWS et la région dans agentcore/aws-targets.json :

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

Déployez sur AgentCore Runtime. La CLI crée l’image avec AWS CodeBuild, la pousse vers Amazon ECR et crée le runtime ainsi qu’un endpoint DEFAULT :

npx @aws/agentcore deploy
remarque

Définissez les clés API du fournisseur et les autres secrets dans agentcore/agentcore.json, sous le champ environmentVariables de l’Agent, avant le déploiement.

Vérifier votre déploiement
Lien direct vers Vérifier votre déploiement

Exécutez agentcore status pour afficher l’ARN du runtime, l’endpoint et les invocations récentes. Appelez ensuite l’Agent déployé depuis la CLI :

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

Pour diffuser les tokens pendant leur génération, utilisez --stream :

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