> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Déployer Mastra sur Amazon Bedrock AgentCore

Déployez votre application Mastra sur [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/) avec la [CLI AgentCore](https://github.com/aws/agentcore-cli). 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli-typescript.html) 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](https://mastra.zisheng.pro/fr/guides/deployment/aws-lambda). Pour une machine virtuelle de longue durée, consultez le [guide Amazon EC2](https://mastra.zisheng.pro/fr/guides/deployment/amazon-ec2).

## Avant de commencer

Vous aurez besoin de :

- Un [compte AWS](https://aws.amazon.com/) disposant d’autorisations pour Amazon Bedrock AgentCore, AWS CodeBuild, Amazon ECR et AWS IAM
- La [CLI AWS](https://aws.amazon.com/cli/) installée et authentifiée, avec `aws configure` ou `aws sso login`
- Node.js `v22.13.0` ou version ultérieure installé
- [Docker](https://www.docker.com/), [Podman](https://podman.io/) ou [Finch](https://runfinch.com/) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-regions.html). 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

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

**npm**:

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

**pnpm**:

```bash
pnpm dlx @aws/agentcore create --name MastraOnAgentCore --no-agent
```

**Yarn**:

```bash
yarn dlx @aws/agentcore create --name MastraOnAgentCore --no-agent
```

**Bun**:

```bash
bun x @aws/agentcore create --name MastraOnAgentCore --no-agent
```

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

```bash
cd MastraOnAgentCore
```

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
bun x @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

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

```bash
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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html). 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**:

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

**pnpm**:

```bash
pnpm add bedrock-agentcore @opentelemetry/auto-instrumentations-node @ai-sdk/amazon-bedrock @aws-sdk/credential-providers --legacy-peer-deps
```

**Yarn**:

```bash
yarn add bedrock-agentcore @opentelemetry/auto-instrumentations-node @ai-sdk/amazon-bedrock @aws-sdk/credential-providers --legacy-peer-deps
```

**Bun**:

```bash
bun add 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**:

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

**pnpm**:

```bash
pnpm add --save-dev typescript @types/node tsx
```

**Yarn**:

```bash
yarn add --dev typescript @types/node tsx
```

**Bun**:

```bash
bun add --dev typescript @types/node tsx
```

Exécutez [`mastra init`](https://mastra.zisheng.pro/fr/reference/cli/mastra) pour configurer un nouveau projet Mastra. Le fournisseur choisi dans le prompt est remplacé à l’étape suivante ; toute valeur convient donc :

**npm**:

```bash
npx mastra@latest init
```

**pnpm**:

```bash
pnpm dlx mastra@latest init
```

**Yarn**:

```bash
yarn dlx mastra@latest init
```

**Bun**:

```bash
bun x 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 :

```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 :

```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 :

```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 :
>
> ```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` :

```bash
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

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 :

```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

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.

```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 :

```bash
node_modules
dist
.git
*.log
```

## Tester votre Agent

Revenez à la racine du projet :

```bash
cd ../..
```

Testez votre Agent localement :

**npm**:

```bash
npx @aws/agentcore dev --runtime MastraAgent
```

**pnpm**:

```bash
pnpm dlx @aws/agentcore dev --runtime MastraAgent
```

**Yarn**:

```bash
yarn dlx @aws/agentcore dev --runtime MastraAgent
```

**Bun**:

```bash
bun x @aws/agentcore dev --runtime MastraAgent
```

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

**npm**:

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

**pnpm**:

```bash
pnpm dlx @aws/agentcore dev "What is the weather in Tokyo?"
```

**Yarn**:

```bash
yarn dlx @aws/agentcore dev "What is the weather in Tokyo?"
```

**Bun**:

```bash
bun x @aws/agentcore dev "What is the weather in Tokyo?"
```

## Déployer votre Agent

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

```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` :

**npm**:

```bash
npx @aws/agentcore deploy
```

**pnpm**:

```bash
pnpm dlx @aws/agentcore deploy
```

**Yarn**:

```bash
yarn dlx @aws/agentcore deploy
```

**Bun**:

```bash
bun x @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

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 :

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

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

```bash
npx @aws/agentcore invoke --stream "Plan a 3-day trip to Tokyo"
```

## Ressources associées

- [Documentation Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/)
- [CLI AgentCore sur GitHub](https://github.com/aws/agentcore-cli)