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

Ejecución de transformaciones

En esta sección se describen las diferentes formas de ejecutar transformaciones y las opciones para controlar el comportamiento de 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 atx y pida al agente que ejecute una transformación mediante 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 en situaciones complejas.

Ejecución interactiva directa

atx custom def exec -n <transformation-name> -p <path>Utilícela 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 de decisión clave 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 sin interfaz. 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 pasar por completo por la interfaz interactiva.

Non-interactive modo

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

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

Modo Headless

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

Ejecución automática de la transformación

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

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

Desarrollo de transformaciones sin rumbo

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

Banderas 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 es especialmente útil con las transformaciones AWS administradas para personalizar su comportamiento según 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 por motivos de calidad.

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

Incluso en el caso de 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 en ejecuciones específicas.

Para evitar aprender de una ejecución:

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

La --do-not-learn marca -d o impide que se extraigan lecciones de la ejecución actual.

Reanudación de las 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>

Minutos del agente de seguimiento

AWS Transform Custom rastrea los minutos que los agentes consumieron 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 cuando finaliza la conversación:

Agent minutes used: 12.50

Los minutos de los agentes se mantienen durante las interrupciones. Si interrumpe una sesión con Ctrl+C y la reanuda más tarde, los minutos acumulados anteriormente se acumulan y se siguen acumulando en la sesión reanudada.

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

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

Para establecer un límite presupuestario de minutos para 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 de los agentes reflejan el tiempo de trabajo de los agentes activos, no la hora 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 administrar las lecciones creadas por el aprendizaje continuo.

Comprensión de las lecciones

El sistema de aprendizaje continuo extrae automáticamente las lecciones de las etapas anteriores de una transformación. El sistema las crea de forma asincrónica basándose en:

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 ejecuciones futuras. Cada lección pertenece a una categoría que contiene todas las lecciones de un dominio similar para que puedan revisar las lecciones relacionadas juntas. En el caso de las lecciones que no quieras usar, puedes archivar o eliminar la lección por completo.

Visualización y administración de las lecciones

Use el learnings comando para abrir una sesión interactiva para explorar y administrar 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 el número de lecciones activas que contiene. Seleccione una categoría para ver sus lecciones y, a continuación, seleccione una lección para ver todos sus detalles, incluido el contenido de la lección, su impacto y el número de ediciones anteriores consultadas.

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 ediciones futuras. Todas las lecciones archivadas se agrupan para que pueda revisarlas y restablecer el uso activo de cualquiera de ellas.

Eliminar lecciones

Elimine permanentemente una lección que no sea útil. La eliminación no se puede deshacer y es posible que el sistema vuelva a aprender una 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 de 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 es ú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 en los puntos de control se atribuyen a una identidad predeterminada ()ATX Bot <checkpoint@atx.bot>. Configure ambas variables para atribuir 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 permite aprobar previamente herramientas y comandos específicos para que se ejecuten sin necesidad de solicitarlo. También puedes solicitar 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 confiables predeterminadas:

Edición de la configuración de confianza:

Puede editar manualmente el archivo trust-settings.yaml para agregar o eliminar herramientas y comandos confiables. Ambos trustedShellCommands y alwaysPromptCommands admiten el uso de patrones comodín globales. *

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

Session-level confianza:

Durante las instrucciones 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 de protocolo de contexto modelo (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úralos con la command propiedad:

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

Servidores HTTP remotos:

Los servidores remotos se conectan a los servidores MCP alojados en una URL HTTP o HTTPS. Configúralos 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 variables de entorno en lugar de 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:

Ver 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 las herramientas MCP durante las ejecuciones de la transformación. Las estadísticas de uso se mantienen al igual que mcp_usage.json en el directorio de conversaciones. metadata.json El archivo registra las métricas de cada ejecución por herramienta, entre las que se incluyen:

Client-Side Habilidades

Client-side las habilidades son capacidades adicionales que amplían el funcionamiento del agente durante las ejecuciones de la transformación. Permiten proporcionar herramientas, scripts e instrucciones personalizadas que el agente puede usar junto con sus capacidades integradas.

Directorios de descubrimiento de habilidades:

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

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

Estructura del directorio de habilidades:

Cada habilidad es un directorio que contiene un SKILL.md archivo con el contenido principal 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.

Deshabilitar una habilidad:

Para evitar que una habilidad se cargue sin eliminar sus archivos, añada disable-model-invocation: true al principio:

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

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

Disponibilidad de habilidades por modo de ejecución:

Verificación del descubrimiento de habilidades:

Compruebe el registro de depuración de la CLI después de ejecutarla 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 superan la validación se omiten con una advertencia en los registros de depuración.

Elección entre Project-Level y User-Level habilidades

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

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

Contrólelas en el control de versiones para que todos los miembros del equipo que ejecuten transformaciones en el repositorio las descubran 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 adquirir habilidades eficaces:

Client-Side Ejemplos de habilidades

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

Ejemplo: Dockerfile Compliance Checker () Script-Based

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

Estructura del directorio:

.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 las etiquetas de imagen base no están ancladas, si se ejecutan como root, si ENV las directivas contienen secretos codificados y si faltan definiciones. HEALTHCHECK El agente ejecuta el script, corrige las infracciones utilizando los patrones del archivo de referencia y vuelve a ejecutar el script para confirmar el cumplimiento.

Ejemplo: API Deprecation Helper () Reference-Only

Esta habilidad ayuda al agente a reemplazar las llamadas a la API obsoletas durante las transformaciones de actualización. Solo usa 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 de antes y 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 usando 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 las etiquetas de una transformación:

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

Las etiquetas se pueden usar 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 administrar 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 sobre la solución de problemas de 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>

Crea transformaciones personalizadas

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

Creación de 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 de publicarlas. No puede modificar las transformaciones AWS administradas. Si necesita personalizarlas, puede proporcionar un contexto adicional mediante el archivo de configuración.

Para modificar una transformación existente

Publicación y administración de transformaciones

Puede publicar y administrar 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

Esto descarga la definición de transformación en su directorio de trabajo actual. Puede especificar un directorio de destino con el --td indicador y una versión con el --tv indicador.

Para eliminar una definición de transformación:

atx custom def delete -n my-transformation

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