Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Flujos de trabajo

Ejecutando transformaciones

En esta sección se describen las diferentes formas de ejecutar las transformaciones y las opciones para controlar el comportamiento de la ejecución.

Modos de ejecución

AWS Transform custom admite tres modos de ejecución para adaptarse a diferentes flujos de trabajo.

Modo conversacional interactivo

Inicie la CLI con atx y pídale al agente que ejecute una transformación a través del lenguaje natural. Este modo le permite mantener una conversación completa con el agente, interrumpir la ejecución en cualquier momento y proporcionar comentarios durante el proceso de transformación.

Utilice este modo cuando desee tener el máximo control y la capacidad de guiar al agente a través de escenarios complejos.

Ejecución interactiva directa

Se utiliza atx custom def exec -n <transformation-name> -p <path> para iniciar una transformación específica de forma interactiva. Este modo le permite revisar el agente e interactuar con él al principio, durante o al final de la ejecución. El agente hará una pausa en los puntos clave de la decisión y le pedirá su opinión.

Esto es ideal para probar y refinar las transformaciones antes de ejecutarlas de forma autónoma.

Puede ejecutar las transformaciones en modo no interactivo o en modo headless. Non-interactive el modo suprime las solicitudes durante una transformación con nombre. El modo Headless permite ejecutar el agente con un mensaje de texto sin formato, sin tener que recurrir por completo a la interfaz interactiva.

Non-interactive modo

Úselo atx custom def exec -n <transformation-name> -p <path> -x -t para una automatización total. -xAñádalo para ejecutar en modo no interactivo y -t para confiar en todas las herramientas automáticamente sin preguntar.

Este modo está diseñado para la integración CI/CD de procesos y la ejecución masiva cuando no se requiere ni se requiere la intervención humana.

Modo Headless

Para completar las tareas sin interactuar con el agente, ejecute atx -x "<prompt>" -t y proporcione sus instrucciones en texto plano.

Ejecución de transformaciones sin interrupciones

Utilice este modo para aplicar una definición de transformación existente a su base de código. La transformación ejecuta cada paso automáticamente sin requerir su aprobación.

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

Desarrollo de una transformación sin precedentes

Cree o modifique las definiciones de transformación.

Para convertir una definición de transformación antigua al nuevo formato de habilidad (SKILL.md + referencias/), ejecute el siguiente comando:

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

Para crear una nueva definición de transformación, ejecute el siguiente comando:

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

Indicadores de comando comunes

Al ejecutar transformaciones conatx custom def exec, se suelen utilizar los siguientes indicadores:

Uso de archivos de configuración

AWS Transform custom admite archivos de configuración opcionales en formato YAML o JSON. Los archivos de configuración permiten especificar los parámetros de ejecución y proporcionar contexto adicional al agente.

Para usar un archivo de configuración:

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

También puede proporcionar la configuración como pares clave-valor en línea:

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

Ejemplo de archivo de configuración (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

El additionalPlanContext parámetro proporciona un contexto adicional para el plan de ejecución del agente. Esto resulta especialmente útil con las transformaciones AWS gestionadas para personalizar su comportamiento en función de sus necesidades específicas.

Comandos de compilación y validación

El comando de compilación o validación es un parámetro opcional que especifica cómo validar el código durante el proceso de transformación. AWS Transform custom intentará deducir cuál es el mejor comando de compilación en función de la transformación si no se especifica, aunque se recomienda que sea específico para garantizar la calidad.

Ejemplos de comandos de compilación y validación:

Incluso para los lenguajes o las transformaciones que no requieren creación, es muy importante proporcionar un comando que valide los resultados y devuelva los problemas si la validación falla para mejorar la calidad de la transformación.

Si no es necesario compilar ni validar, omítelo en la entrada.

Controlar el comportamiento de aprendizaje

De forma predeterminada, AWS Transform custom extrae las lecciones de cada ejecución de transformación. Puede impedir el aprendizaje para determinadas ejecuciones.

Para evitar aprender de una ejecución:

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

El --do-not-learn indicador -d o no permite extraer lecciones de la ejecución actual.

Reanudar conversaciones

AWS Transform custom te permite reanudar las conversaciones anteriores en un plazo de 30 días a partir de su creación.

Para reanudar la conversación más reciente:

atx --resume

Para reanudar una conversación específica:

atx --conversation-id <conversation-id>

Rastreando las actas de

AWS Transform custom rastrea los minutos de los agentes consumidos durante una sesión de transformación. Los minutos de los agentes se acumulan a lo largo del ciclo de vida de la conversación y se muestran al finalizar la conversación:

Agent minutes used: 12.50

Los minutos de los agentes persisten a pesar de las interrupciones. Si interrumpe una sesión con Ctrl+C y la reanuda más tarde, los minutos acumulados anteriormente se acumulan y continúan acumulándose en la sesión reanudada.

Para consultar los minutos de los agentes durante una sesión interactiva:

Escriba /usage en el indicador de entrada para mostrar los minutos de agente acumulados actualmente sin finalizar la conversación.

Para establecer un límite presupuestario para los minutos de los agentes:

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

La --limit opción establece un presupuesto máximo de minutos de agente para la sesión. Los minutos del agente reflejan el tiempo de trabajo del agente activo, no el tiempo del reloj de pared. Cuando se alcanza el límite, la CLI muestra un mensaje y sale con instrucciones para reanudar:

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

Puede reanudar la conversación más adelante con un límite mayor:

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

Aprendizaje continuo

Esta sección describe cómo revisar y gestionar las lecciones creadas por el aprendizaje continuo.

Comprensión de las lecciones

El sistema de aprendizaje continuo extrae automáticamente las lecciones de las fases anteriores de una transformación. El sistema las crea de forma asíncrona en función de:

Las lecciones se acumulan con el tiempo a medida que se ejecuta la transformación en diferentes bases de código. El sistema las aplica automáticamente para mejorar las carreras futuras. Cada lección pertenece a una categoría que contiene todas las lecciones de un dominio similar para que puedan repasar las lecciones relacionadas juntas. En el caso de las lecciones que no desee utilizar, puede archivar o eliminar la lección por completo.

Visualización y administración de las lecciones

Utilice el learnings comando para abrir una sesión interactiva para explorar y gestionar las lecciones de una definición de transformación.

Para abrir el visor de lecciones:

atx custom def learnings -n my-transformation

El visor se abre en una lista de categorías de lecciones, cada una de las cuales muestra cuántas lecciones activas contiene. Seleccione una categoría para ver sus lecciones y, a continuación, seleccione una lección para ver todos sus detalles, incluido el cuerpo de la lección, su impacto y el número de sesiones anteriores en las que se consultó.

Archivar y restaurar las lecciones

El sistema aplica las lecciones automáticamente. Si no desea que el sistema aplique una lección, puede archivarla. El sistema conserva las lecciones archivadas, pero no las aplica a futuras ejecuciones. Todas las lecciones archivadas se agrupan para que puedas revisarlas y volver a utilizarlas de forma activa.

Eliminar lecciones

Eliminar permanentemente una lección que no sea útil. La eliminación no se puede deshacer y el sistema podría volver a aprender la lección eliminada en futuras ejecuciones.

Una lección debe archivarse antes de poder eliminarla.

Configuración avanzada

En esta sección se describen las funciones avanzadas y las opciones de configuración de AWS Transform custom.

Variables de entorno

Puede personalizar el comportamiento de la CLI mediante variables de entorno.

ATX_SHELL_TIMEOUT

Anula el tiempo de espera predeterminado para los comandos del shell (900 minutos). seconds/15

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

Esto resulta útil para bases de código grandes o procesos de compilación de larga duración.

ATX_DISABLE_UPDATE_CHECK

Deshabilite las comprobaciones automáticas de versiones y las notificaciones de actualización durante la ejecución del comando.

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME y ATX_GIT_COMMITTER_EMAIL

Configura la identidad del autor utilizada para las confirmaciones de puntos de control que Transform custom crea en tu repositorio a medida que aplica los cambios durante una transformación. AWS Cuando estas variables no están configuradas, las confirmaciones de puntos de control se atribuyen a una identidad predeterminada ()ATX Bot <checkpoint@atx.bot>. Configure ambas variables para atribuir los puntos de control a un autor específico.

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"

Configuración de confianza

La configuración de confianza le permite preaprobar herramientas y comandos específicos para que se ejecuten sin tener que solicitarlo. También puede requerir un permiso explícito para comandos de shell específicos, independientemente del nivel de confianza. Estos ajustes se configuran en el archivo ~/.aws/atx/trust-settings.yaml.

El archivo contiene tres listas:

Herramientas de confianza predeterminadas:

Edición de la configuración de confianza:

Puedes editar manualmente el archivo trust-settings.yaml para añadir o eliminar herramientas y comandos de confianza. Ambos admiten el uso de patrones comodín trustedShellCommands globosos. alwaysPromptCommands *

A continuación se describe cada lista de comandos y se proporcionan ejemplos:

Session-level confianza:

Durante las indicaciones interactivas, puede elegir:

Session-level la configuración de confianza es temporal y se restablece cuando se reinicia la CLI, lo que proporciona una aprobación temporal sin modificar permanentemente trust-settings.yaml.

Servidores Model Context Protocol (MCP)

La CLI de AWS Transform es compatible con los servidores del Model Context Protocol (MCP), que amplían su funcionalidad con herramientas adicionales.

Configuración:

Configure los servidores MCP en el ~/.aws/atx/mcp.json archivo. La CLI de AWS Transform admite dos tipos de servidores MCP: servidores locales basados en comandos y servidores HTTP remotos.

Servidores locales basados en comandos:

Los servidores locales se ejecutan como procesos secundarios en su máquina. Configúrelos con la command propiedad:

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

Servidores HTTP remotos:

Los servidores remotos se conectan a servidores MCP alojados en una URL HTTP o HTTPS. Configúrelos con la url propiedad:

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

La headers propiedad es opcional y admite la expansión de variables de entorno mediante la ${VAR_NAME} sintaxis. Esto le permite almacenar valores confidenciales, como los tokens de API, en las variables de entorno en lugar de guardarlos en el archivo de configuración.

Propiedades de configuración:

Los servidores locales basados en comandos admiten las siguientes propiedades:

Los servidores HTTP remotos admiten las siguientes propiedades:

Administración de servidores MCP:

Vea la lista de servidores MCP configurados:

atx mcp tools

Enumere las herramientas disponibles que ofrece un servidor MCP específico:

atx mcp tools --server <server-name>

Seguimiento del uso:

La CLI rastrea automáticamente el uso de la herramienta MCP durante las ejecuciones de la transformación. Las estadísticas de uso se conservan al igual que mcp_usage.json en el directorio de conversaciones. metadata.json El archivo registra las métricas por herramienta para cada ejecución, incluidas las siguientes:

Client-Side Habilidades

Client-side las habilidades son capacidades adicionales que amplían al agente durante las ejecuciones de transformación. Permiten proporcionar herramientas, scripts e instrucciones personalizados que el agente puede utilizar junto con sus funciones integradas.

Directorios de descubrimiento de habilidades:

Las habilidades se descubren en cuatro directorios en orden de prioridad. Si una habilidad con el mismo nombre existe en varios directorios, el primer directorio de la lista tiene prioridad:

Los .aws/atx/skills/ directorios son específicos de la CLI de AWS transformación. Los .agents/skills/ directorios son multicliente, lo que significa que las habilidades colocadas allí están disponibles para cualquier herramienta de agente compatible más allá de la AWS CLI de Transform.

Estructura del directorio de habilidades:

Cada habilidad es un directorio que contiene un SKILL.md archivo con la información preliminar de 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 formato:

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

Instructions for the agent...

El name campo debe coincidir con el nombre del directorio principal.

Desactivar una habilidad:

Para evitar que una habilidad se cargue sin eliminar sus archivos, añade disable-model-invocation: true a la portada lo siguiente:

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

Cuando se establece esta propiedad, la CLI omite la habilidad durante el descubrimiento. El agente no puede ver ni utilizar la habilidad a menos que una definición de transformación le indique explícitamente que lea el archivo de habilidades. Utilízalo para desactivar temporalmente una habilidad, marcarla como en progreso o conservar material de referencia destinado únicamente a lectores humanos.

Disponibilidad de habilidades por modo de ejecución:

Verificar el descubrimiento de habilidades:

Consulte el registro de depuración de la CLI después de una ejecución para comprobar qué habilidades se descubrieron:

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

Las habilidades que no pasan la validación se omiten con una advertencia en los registros de depuración.

Elegir entre Project-Level y User-Level habilidades

El lugar donde coloques una habilidad determina quién se beneficia de ella y cuándo se activa.

Project-level habilidades (<project>/.aws/atx/skills/):

Compromételas al control de versiones para que cada miembro del equipo que ejecute transformaciones en el repositorio las descubra automáticamente. Usa tus habilidades a nivel de proyecto para:

User-level habilidades (~/.aws/atx/skills/):

Permanecen en su máquina y se activan durante todas las transformaciones, independientemente del repositorio al que se dirija. Utilice sus habilidades a nivel de usuario para:

Consejos para desarrollar habilidades eficaces:

Client-Side Ejemplos de habilidades

Estos ejemplos muestran dos patrones comunes: una habilidad de validación basada en guiones y una habilidad solo de referencia.

Ejemplo: Dockerfile Compliance Checker () Script-Based

Esta habilidad valida los archivos de Dockerfiles según las mejores prácticas operativas y de seguridad. Utiliza un script de validación que el agente ejecuta antes y después de realizar los cambios.

Estructura de directorios:

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

El script de validación comprueba si hay etiquetas de imagen base no ancladas, si se ejecutan como root, si hay secretos codificados en ENV las directivas o si faltan definiciones. HEALTHCHECK El agente ejecuta el script, corrige las infracciones utilizando patrones del archivo de referencia y vuelve a ejecutar el script para confirmar su conformidad.

Ejemplo: API Deprecation Helper () Reference-Only

Esta habilidad guía al agente a reemplazar las llamadas a la API obsoletas durante las transformaciones de la actualización. Utiliza solo archivos de referencia sin scripts.

Estructura de directorios:

.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

Los archivos de referencia contienen ejemplos de código del antes y el después. Por ejemplo, aws-sdk-v2-to-v3.md mapea patrones similares s3.putObject(params).promise() a los del equivalente modular de la versión 3 utilizando y. S3Client PutObjectCommand

Etiquetas y organización

Puede organizar las transformaciones con etiquetas para el control de acceso y la categorización.

Para enumerar las etiquetas de una transformación:

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

Para añadir etiquetas a una transformación:

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

Para eliminar etiquetas de una transformación:

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

Las etiquetas se pueden utilizar para el control de acceso agrupado en las políticas de IAM. Puede crear políticas que concedan permisos a todas las transformaciones con etiquetas específicas (por ejemplo, todas las transformaciones etiquetadas con team:frontend oenvironment:production).

Registros

AWS La CLI de Transform mantiene tres tipos de registros para la solución de problemas y la depuración.

Registros de conversaciones:

Linux and macOS

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

Windows

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

Estos registros contienen el historial completo de conversaciones de una sesión específica.

Registros de subagentes:

Linux and macOS

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

Windows

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

Estos registros contienen los resultados de los subagentes que el agente principal genera durante las transformaciones. No es necesario gestionar los subagentes directamente.

Registros de depuración de desarrolladores:

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

Estos registros proporcionan información avanzada de solución de problemas para la propia CLI.

Actualizaciones de CLI

Mantenga su CLI actualizada para acceder a nuevas funciones y mejoras.

Para comprobar si hay actualizaciones:

atx update --check

Para actualizar a la versión más reciente:

atx update

Para actualizar a una versión específica:

atx update --target-version <version>

Cree transformaciones personalizadas

En esta sección se describe cómo crear, modificar y administrar las definiciones de transformación personalizadas.

Crear una nueva transformación

Utilice la CLI interactiva para crear una nueva definición de transformación.

Para crear una definición de transformación

Mejores prácticas para crear transformaciones:

Proporcionar materiales de referencia

Puede proporcionar archivos de referencia a AWS Transform custom especificando las rutas de los archivos durante la conversación. Estos archivos se almacenan en la references/ carpeta de la definición de transformación.

Tipos de archivos de referencia recomendados:

Para proporcionar un archivo de referencia:

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

También puede proporcionar un directorio que contenga varios archivos de referencia:

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

Modificación de una transformación existente

Puede modificar las transformaciones personalizadas antes y después de guardarlas como borradores o publicarlas. No puede modificar las transformaciones AWS gestionadas por terceros. Si necesita personalizarlas, puede proporcionar contexto adicional mediante el archivo de configuración.

Para modificar una transformación existente

Publicar y gestionar las transformaciones

Puede publicar y gestionar sus transformaciones mediante la experiencia interactiva o con los siguientes comandos.

Para guardar una transformación como borrador:

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

Para publicar una transformación:

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

Para ver una lista de las transformaciones disponibles:

atx custom def list

Para descargar una definición de transformación:

atx custom def get -n my-transformation

De este modo, se descarga la definición de transformación en su directorio de trabajo actual. Puede especificar un directorio de destino con la --td marca y una versión con la --tv marca.

Para eliminar una definición de transformación:

atx custom def delete -n my-transformation

Gestión de las versiones de transformación

AWS Transform custom mantiene las versiones de sus definiciones de transformación. Puede especificar una versión al ejecutar o descargar una transformación.

Para ejecutar una versión específica:

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

Para descargar una versión específica:

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

Si no se especifica ninguna versión, se utiliza la versión más reciente.