Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Flux de travail

Exécution de transformations

Cette section décrit les différentes méthodes d'exécution des transformations et les options permettant de contrôler le comportement d'exécution.

Modes d'exécution

AWS Transform custom prend en charge trois modes d'exécution adaptés aux différents flux de travail.

Mode conversationnel interactif

Démarrez la CLI avec atx et demandez à l'agent d'exécuter une transformation en langage naturel. Ce mode vous permet d'avoir une conversation complète avec l'agent, d'interrompre l'exécution à tout moment et de fournir des commentaires pendant le processus de transformation.

Utilisez ce mode lorsque vous souhaitez un contrôle maximal et la capacité de guider l'agent dans des scénarios complexes.

Exécution interactive directe

atx custom def exec -n <transformation-name> -p <path>À utiliser pour démarrer une transformation spécifique de manière interactive. Ce mode vous permet de consulter l'agent et d'interagir avec lui au début, pendant ou à la fin de l'exécution. L'agent fera une pause aux points de décision clés et vous demandera votre avis.

C'est idéal pour tester et affiner les transformations avant de les exécuter de manière autonome.

Vous pouvez exécuter des transformations en mode non interactif ou en mode headless. Non-interactive le mode supprime les invites lors d'une transformation nommée. Le mode Headless vous permet d'exécuter l'agent à l'aide d'une invite en texte brut, en contournant complètement l'interface interactive.

Non-interactive mode

À utiliser atx custom def exec -n <transformation-name> -p <path> -x -t pour une automatisation complète. Ajoutez -x pour exécuter en mode non interactif et -t pour faire confiance à tous les outils automatiquement sans qu'on vous le demande.

Ce mode est conçu pour l'intégration de CI/CD pipelines et l'exécution en masse lorsqu'aucune intervention humaine n'est disponible ou souhaitée.

Mode sans tête

Pour effectuer des tâches sans interagir avec l'agent, exécutez atx -x "<prompt>" -t et fournissez vos instructions en texte brut.

Exécution de transformations sans tête

Utilisez ce mode pour appliquer une définition de transformation existante à votre base de code. La transformation exécute chaque étape automatiquement sans nécessiter votre approbation.

atx -x "apply transformation definition <transformation_definition_name> to <codebase_path>" -t

Développement d'une transformation sans tête

Créez ou modifiez des définitions de transformation.

Pour convertir une ancienne définition de transformation dans le nouveau format de compétence (SKILL.md + références/), exécutez la commande suivante :

atx -x "convert <legacy_transformation_definition_name> transformation definition to skill and save as draft" -t

Pour créer une nouvelle définition de transformation, exécutez la commande suivante :

atx -x "create a transformation definition to <description> with references docs <reference_docs_path>" -t

Drapeaux de commande courants

Lors de l'exécution de transformations avecatx custom def exec, les indicateurs suivants sont couramment utilisés :

Utilisation des fichiers de configuration

AWS Transform custom prend en charge les fichiers de configuration facultatifs au format YAML ou JSON. Les fichiers de configuration vous permettent de définir les paramètres d'exécution et de fournir un contexte supplémentaire à l'agent.

Pour utiliser un fichier de configuration :

atx custom def exec --configuration file://config.yaml

Vous pouvez également fournir une configuration sous forme de paires clé-valeur en ligne :

atx custom def exec --configuration "key=value,key2=value2"

Exemple de fichier de configuration (config.yaml) :

codeRepositoryPath: ./my-project
transformationName: my-transformation
buildCommand: mvn clean install
additionalPlanContext: |
  The target Java version to upgrade to is Java 17.
  Ensure compatibility with our internal logging framework version 2.3.
validationCommands: |
  mvn test
  mvn verify

Le additionalPlanContext paramètre fournit un contexte supplémentaire pour le plan d'exécution de l'agent. Cela est particulièrement utile avec les transformations AWS gérées par -managed pour personnaliser leur comportement en fonction de vos besoins spécifiques.

Commandes de génération et de validation

La commande de génération ou de validation est un paramètre facultatif qui indique comment valider votre code pendant le processus de transformation. AWS Transform custom tentera de déduire la meilleure commande de génération en fonction de la transformation si elle n'est pas spécifiée, bien qu'il soit recommandé d'être spécifique pour des raisons de qualité.

Exemples de commandes de construction et de validation :

Même pour les langages ou les transformations qui ne nécessitent pas de création, il est très important de fournir une commande qui valide les résultats et renvoie des problèmes en cas d'échec de la validation pour améliorer la qualité de la transformation.

Si aucune compilation ou validation n'est nécessaire, omettez de le saisir.

Contrôler le comportement d'apprentissage

Par défaut, AWS Transform custom extrait les leçons de chaque exécution de transformation. Vous pouvez empêcher l'apprentissage pour des exécutions spécifiques.

Pour éviter de tirer des leçons d'une exécution, procédez comme suit :

atx custom def exec -n my-transformation -p ./my-project -d

L'--do-not-learnindicateur -d or permet de refuser d'autoriser l'extraction de leçons à partir de l'exécution en cours.

Reprise des conversations

AWS Transform custom vous permet de reprendre les conversations précédentes dans les 30 jours suivant leur création.

Pour reprendre la conversation la plus récente :

atx --resume

Pour reprendre une conversation spécifique, procédez comme suit :

atx --conversation-id <conversation-id>

Procès-verbaux des agents

AWS Transform Custom suit les minutes consommées par les agents au cours d'une session de transformation. Les minutes des agents s'accumulent tout au long du cycle de vie de la conversation et sont affichées à la fin de la conversation :

Agent minutes used: 12.50

Les minutes des agents persistent malgré les interruptions. Si vous interrompez une session avec Ctrl+C et que vous la reprenez ultérieurement, les minutes accumulées précédemment sont reportées et continuent de s'accumuler dans la session reprise.

Pour consulter les minutes des agents au cours d'une session interactive, procédez comme suit :

Tapez /usage à l'invite de saisie pour afficher les minutes d'agent cumulées en cours sans mettre fin à la conversation.

Pour définir une limite de budget pour les minutes d'agent, procédez comme suit :

atx custom def exec -n my-transformation -p ./my-project --limit 30

L'--limitoption définit un budget maximum de minutes d'agent pour la session. Les minutes de l'agent reflètent le temps de travail de l'agent actif, et non l'heure de l'horloge murale. Lorsque la limite est atteinte, la CLI affiche un message et sort avec des instructions pour reprendre :

⚠️ Budget limit reached: 30.00 / 30.00 Agent Minutes. Exiting.

Vous pouvez reprendre la conversation ultérieurement avec une limite accrue :

atx --conversation-id <conversation_id> -t --limit <increased_limit>

Apprentissage continu

Cette section décrit comment examiner et gérer les leçons créées par l'apprentissage continu.

Comprendre les leçons

Le système d'apprentissage continu extrait automatiquement les leçons des précédentes étapes d'une transformation. Le système les crée de manière asynchrone en fonction des éléments suivants :

Les leçons s'accumulent au fil du temps à mesure que vous exécutez la transformation sur différentes bases de code. Le système les applique automatiquement pour améliorer les futures séries. Chaque leçon appartient à une catégorie contenant toutes les leçons d'un domaine similaire afin que vous puissiez passer en revue les leçons connexes ensemble. Pour les leçons que vous ne souhaitez pas utiliser, vous pouvez les archiver ou les supprimer entièrement.

Afficher et gérer les leçons

Utilisez la learnings commande pour ouvrir une session interactive afin de parcourir et de gérer les leçons d'une définition de transformation.

Pour ouvrir l'afficheur de leçons, procédez comme suit :

atx custom def learnings -n my-transformation

L'afficheur s'ouvre sur une liste de catégories de leçons, chacune indiquant le nombre de leçons actives qu'elle contient. Sélectionnez une catégorie pour voir ses leçons, puis sélectionnez une leçon pour en afficher tous les détails, y compris le corps de la leçon, son impact et le nombre de versions précédentes qui l'ont consultée.

Leçons d'archivage et de restauration

Le système applique automatiquement les leçons. Si vous ne souhaitez pas que le système applique une leçon, vous pouvez l'archiver. Le système conserve les leçons archivées mais ne les applique pas aux futures éditions. Toutes les leçons archivées sont regroupées afin que vous puissiez les consulter et rétablir leur utilisation active.

Supprimer des leçons

Supprimez définitivement une leçon qui n'est pas utile. La suppression ne peut pas être annulée et le système peut réapprendre une leçon supprimée lors de futures exécutions.

Une leçon doit être archivée avant de pouvoir être supprimée.

Configuration avancée

Cette section décrit les fonctionnalités avancées et les options de configuration de AWS Transform custom.

Variables d’environnement

Vous pouvez personnaliser le comportement de la CLI à l'aide de variables d'environnement.

ATX_SHELL_TIMEOUT

Remplacez le délai d'expiration par défaut pour les commandes shell (900 seconds/15 minutes).

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

Cela est utile pour les bases de code volumineuses ou les processus de construction de longue durée.

ATX_DISABLE_UPDATE_CHECK

Désactivez les vérifications de version automatiques et les notifications de mise à jour lors de l'exécution des commandes.

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME et ATX_GIT_COMMITTER_EMAIL

Configurez l'identité de l'auteur utilisée pour les validations de point de contrôle que AWS Transform Custom crée dans votre référentiel lorsqu'il applique les modifications lors d'une transformation. Lorsque ces variables ne sont pas définies, les validations des points de contrôle sont attribuées à une identité par défaut (ATX Bot <checkpoint@atx.bot>). Définissez les deux variables pour attribuer des points de contrôle à un auteur spécifique.

Linux and macOS

export ATX_GIT_COMMITTER_NAME="Jane Developer"
export ATX_GIT_COMMITTER_EMAIL="jane@example.com"

Windows (PowerShell)

$env:ATX_GIT_COMMITTER_NAME="Jane Developer"
$env:ATX_GIT_COMMITTER_EMAIL="jane@example.com"

Paramètres de confiance

Les paramètres de confiance vous permettent de préapprouver des outils et des commandes spécifiques à exécuter sans invite. Vous pouvez également demander une autorisation explicite pour des commandes shell spécifiques, quel que soit le niveau de confiance. Ces paramètres sont configurés dans le ~/.aws/atx/trust-settings.yaml fichier.

Le fichier contient trois listes :

Outils fiables par défaut :

Modification des paramètres de confiance :

Vous pouvez modifier manuellement le fichier trust-settings.yaml pour ajouter ou supprimer des outils et des commandes fiables. Les deux trustedShellCommands et alwaysPromptCommands supportez les modèles de caractères génériques globaux en utilisant. *

La section suivante décrit chaque liste de commandes et fournit des exemples :

Session-level confiance :

Pendant les instructions interactives, vous pouvez choisir :

Session-level les paramètres de confiance sont temporaires et réinitialisés au redémarrage de la CLI, fournissant une approbation temporaire sans modifier définitivement trust-settings.yaml.

Serveurs MCP (Model Context Protocol)

La CLI AWS Transform prend en charge les serveurs MCP (Model Context Protocol), qui étendent ses fonctionnalités grâce à des outils supplémentaires.

Configuration :

Configurez les serveurs MCP dans le ~/.aws/atx/mcp.json fichier. La CLI AWS Transform prend en charge deux types de serveurs MCP : les serveurs locaux basés sur les commandes et les serveurs HTTP distants.

Serveurs locaux basés sur les commandes :

Les serveurs locaux s'exécutent en tant que processus enfants sur votre machine. Configurez-les avec la command propriété :

{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

Serveurs HTTP distants :

Les serveurs distants se connectent aux serveurs MCP hébergés sur une URL HTTP ou HTTPS. Configurez-les avec la url propriété :

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_API_TOKEN}"
      }
    }
  }
}

La headers propriété est facultative et prend en charge l'expansion des variables d'environnement à l'aide de ${VAR_NAME} la syntaxe. Cela vous permet de stocker des valeurs sensibles telles que des jetons d'API dans des variables d'environnement plutôt que dans le fichier de configuration.

Propriétés de configuration :

Les serveurs locaux basés sur les commandes prennent en charge les propriétés suivantes :

Les serveurs HTTP distants prennent en charge les propriétés suivantes :

Gestion des serveurs MCP :

Afficher la liste des serveurs MCP configurés :

atx mcp tools

Répertoriez les outils disponibles proposés par un serveur MCP spécifique :

atx mcp tools --server <server-name>

Suivi de l'utilisation :

La CLI suit automatiquement l'utilisation de l'outil MCP lors des exécutions de transformation. Les statistiques d'utilisation sont conservées comme mcp_usage.json dans le répertoire des conversations ci-contre. metadata.json Le fichier enregistre les métriques par outil pour chaque exécution, notamment :

Client-Side Compétences

Client-side les compétences sont des capacités supplémentaires qui étendent l'agent lors des exécutions de transformation. Ils vous permettent de fournir des outils, des scripts et des instructions personnalisés que l'agent peut utiliser en plus de ses fonctionnalités intégrées.

Répertoires de découverte de compétences :

Les compétences sont découvertes dans quatre répertoires par ordre de priorité. Si une compétence portant le même nom existe dans plusieurs répertoires, le premier répertoire de la liste est prioritaire :

Les .aws/atx/skills/ répertoires sont spécifiques à la CLI AWS Transform. Les .agents/skills/ répertoires sont interclients, ce qui signifie que les compétences qui y sont placées sont accessibles à tous les outils d'agent compatibles autres que la AWS CLI Transform.

Structure du répertoire des compétences :

Chaque compétence est un répertoire contenant un SKILL.md fichier avec une interface YAML :

~/.aws/atx/skills/
└── my-skill/
    ├── SKILL.md          # Required: frontmatter + instructions
    ├── references/       # Optional: reference docs the agent can read
    │   └── guide.md
    └── scripts/          # Optional: scripts the agent can execute
        └── validate.py

SKILL.md format :

---
name: my-skill
description: When to use this skill
---
# Skill Title

Instructions for the agent...

Le name champ doit correspondre au nom du répertoire parent.

Désactivation d'une compétence :

Pour empêcher le chargement d'une compétence sans supprimer ses fichiers, ajoutez disable-model-invocation: true à l'en-tête :

---
name: my-skill
description: When to use this skill
disable-model-invocation: true
---

Lorsque cette propriété est définie, la CLI ignore la compétence lors de la découverte. L'agent ne peut ni voir ni utiliser la compétence à moins qu'une définition de transformation ne lui indique explicitement de lire le fichier de compétence. Utilisez-le pour désactiver temporairement une compétence, la marquer comme étant en cours de développement ou conserver des documents de référence destinés uniquement à des lecteurs humains.

Disponibilité des compétences par mode d'exécution :

Vérification de la découverte des compétences :

Consultez le journal de débogage de la CLI après une exécution pour vérifier quelles compétences ont été découvertes :

Linux and macOS

grep -i "skill" ~/.aws/atx/logs/debug.log | tail -20

Windows (PowerShell)

Select-String -Pattern "skill" "$env:USERPROFILE\.aws\atx\logs\debug.log" | Select-Object -Last 20

Les compétences dont la validation échoue sont ignorées avec un avertissement dans les journaux de débogage.

Choisir entre Project-Level et User-Level compétences

L'endroit où vous placez une compétence détermine qui en bénéficie et à quel moment elle est activée.

Project-level compétences (<project>/.aws/atx/skills/) :

Consignez-les dans le contrôle de version afin que chaque membre de l'équipe exécutant des transformations dans le référentiel les découvre automatiquement. Utilisez les compétences au niveau du projet pour :

User-level compétences (~/.aws/atx/skills/) :

Ils restent sur votre machine et s'activent pendant toutes les transformations, quel que soit le référentiel que vous ciblez. Utilisez les compétences de niveau utilisateur pour :

Conseils pour acquérir des compétences efficaces :

Client-Side Exemples de compétences

Ces exemples montrent deux modèles courants : une compétence de validation basée sur un script et une compétence basée uniquement sur des références.

Exemple : Vérificateur de conformité Dockerfile () Script-Based

Cette compétence valide Dockerfiles par rapport aux meilleures pratiques opérationnelles et de sécurité. Il utilise un script de validation que l'agent exécute avant et après les modifications.

Structure du répertoire :

.aws/atx/skills/
└── dockerfile-compliance/
    ├── SKILL.md
    ├── scripts/
    │   └── lint_dockerfile.sh
    └── references/
        └── dockerfile-best-practices.md

SKILL.md:

---
name: dockerfile-compliance
description: Validates Dockerfiles against security and operational best practices
---
# Dockerfile Compliance Checker

When a transformation creates or modifies Dockerfiles, run the compliance checker.

## When to use

- After creating a new Dockerfile
- After modifying FROM, RUN, USER, or EXPOSE directives
- When containerizing an application as part of a transformation

## How to use

Run: `bash scripts/lint_dockerfile.sh <path-to-Dockerfile>`

If violations are found, consult `references/dockerfile-best-practices.md`
for compliant patterns.

Le script de validation vérifie la présence de balises d'image de base non épinglées, exécutées en tant que root, de secrets codés en dur dans les ENV directives et de définitions manquantes. HEALTHCHECK L'agent exécute le script, corrige les violations à l'aide des modèles du fichier de référence et réexécute le script pour confirmer la conformité.

Exemple : API Deprecation Helper () Reference-Only

Cette compétence guide l'agent dans le remplacement des appels d'API obsolètes lors des transformations de mise à niveau. Il utilise uniquement des fichiers de référence sans scripts.

Structure du répertoire :

.aws/atx/skills/
└── api-deprecation-helper/
    ├── SKILL.md
    └── references/
        ├── aws-sdk-v2-to-v3.md
        └── react-class-to-hooks.md

SKILL.md:

---
name: api-deprecation-helper
description: Guides the agent through replacing deprecated API calls with modern equivalents
---
# API Deprecation Helper

When performing upgrade transformations, use this skill to identify and replace
deprecated API calls with their modern equivalents.

## When to use

- During any version upgrade transformation
- When build warnings mention deprecated APIs
- When transforming code that uses legacy patterns

## Process

1. Identify deprecated API calls in the codebase
2. For each deprecated call, find the replacement in `references/`
3. Apply the replacement, preserving the original behavior
4. Verify the replacement compiles and tests pass

Les fichiers de référence contiennent des exemples de code avant/après. Par exemple, aws-sdk-v2-to-v3.md des modèles de cartes similaires s3.putObject(params).promise() à l'équivalent modulaire de la version 3 en utilisant S3Client etPutObjectCommand.

Tags et organisation

Vous pouvez organiser les transformations à l'aide de balises pour le contrôle d'accès et la catégorisation.

Pour répertorier les balises d'une transformation, procédez comme suit :

atx custom def list-tags --arn <transformation-arn>

Pour ajouter des balises à une transformation :

atx custom def tag --arn <transformation-arn> --tags '{"env":"prod","team":"backend"}'

Pour supprimer des balises d'une transformation, procédez comme suit :

atx custom def untag --arn <transformation-arn> --tag-keys "env,team"

Les balises peuvent être utilisées pour le contrôle d'accès groupé dans les politiques IAM. Vous pouvez créer des politiques qui accordent des autorisations à toutes les transformations dotées de balises spécifiques (par exemple, toutes les transformations marquées d'un team:frontend ouenvironment:production).

Journaux

AWS La CLI Transform gère trois types de journaux pour le dépannage et le débogage.

Journaux de conversation :

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/<timestamp>-conversation.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\<timestamp>-conversation.log

Ces journaux contiennent l'historique complet des conversations pour une session spécifique.

Journaux des sous-agents :

Linux and macOS

~/.aws/atx/custom/<conversation_id>/logs/subagents/<name>.log

Windows

%USERPROFILE%\.aws\atx\custom\<conversation_id>\logs\subagents\<name>.log

Ces journaux contiennent les résultats des sous-agents générés par l'agent principal lors des transformations. Il n'est pas nécessaire de gérer directement les sous-agents.

Journaux de débogage des développeurs :

Linux and macOS

~/.aws/atx/logs/debug*.log
~/.aws/atx/logs/error.log

Windows

%USERPROFILE%\.aws\atx\logs\debug*.log
%USERPROFILE%\.aws\atx\logs\error.log

Ces journaux fournissent des informations de dépannage avancées pour la CLI elle-même.

Mises à jour du CLI

Maintenez votre CLI à jour pour accéder aux nouvelles fonctionnalités et améliorations.

Pour vérifier les mises à jour :

atx update --check

Pour effectuer la mise à jour vers la dernière version :

atx update

Pour effectuer une mise à jour vers une version spécifique :

atx update --target-version <version>

Création de transformations personnalisées

Cette section explique comment créer, modifier et gérer des définitions de transformation personnalisées.

Création d'une nouvelle transformation

Utilisez la CLI interactive pour créer une nouvelle définition de transformation.

Pour créer une définition de transformation

Bonnes pratiques pour créer des transformations :

Fourniture de matériel de référence

Vous pouvez fournir des fichiers de référence à AWS Transform custom en spécifiant les chemins des fichiers au cours de la conversation. Ces fichiers sont stockés dans le references/ dossier de définition de la transformation.

Types de fichiers de référence recommandés :

Pour fournir un fichier de référence :

Take a look at the documentation here: /path/to/migration-guide.md

Vous pouvez également fournir un répertoire contenant plusieurs fichiers de référence :

Take a look at the docs we have here: /path/to/docs/

Modifier une transformation existante

Vous pouvez modifier les transformations personnalisées avant et après les avoir enregistrées sous forme de brouillons ou après les avoir publiées. Vous ne pouvez pas modifier les transformations AWS gérées par -managed. Si vous devez les personnaliser, vous pouvez fournir un contexte supplémentaire à l'aide du fichier de configuration.

Pour modifier une transformation existante

Publication et gestion des transformations

Vous pouvez publier et gérer vos transformations à l'aide de l'expérience interactive ou des commandes suivantes.

Pour enregistrer une transformation sous forme de brouillon, procédez comme suit :

atx custom def save-draft -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

Pour publier une transformation, procédez comme suit :

atx custom def publish -n my-transformation --description "Description of the transformation" --sd ./transformation-directory

Pour répertorier les transformations disponibles, procédez comme suit :

atx custom def list

Pour télécharger une définition de transformation, procédez comme suit :

atx custom def get -n my-transformation

Cela télécharge la définition de transformation dans votre répertoire de travail actuel. Vous pouvez spécifier un répertoire cible avec le --td drapeau et une version avec l'--tvindicateur.

Pour supprimer une définition de transformation, procédez comme suit :

atx custom def delete -n my-transformation

Gestion des versions de transformation

AWS Transform Custom gère les versions de vos définitions de transformation. Vous pouvez spécifier une version lors de l'exécution ou du téléchargement d'une transformation.

Pour exécuter une version spécifique :

atx custom def exec -n my-transformation --tv v1 -p ./my-project

Pour télécharger une version spécifique :

atx custom def get -n my-transformation --tv v1

Si aucune version n'est spécifiée, la dernière version est utilisée.