View a markdown version of this page

Flujos de trabajo - AWS Transformar

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 con atx y pida 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 en situaciones complejas.

Ejecución interactiva directa

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

Uso atx custom def exec -n <transformation-name> -p <path> -x -t para una automatización completa. Añadir -x para ejecutarse en modo no interactivo, y -t confiar en todas las herramientas de forma automática y sin necesidad de solicitarlas.

Este modo está diseñado para CI/CD la integración de canalizaciones y la ejecución masiva cuando no se desee o esté disponible 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 supervisió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 habilidades (SKILL.md + references/), 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 con atx custom def exec, se suelen utilizar los siguientes indicadores:

  • -n o --transformation-name - Especifica el nombre de la transformación que se va a ejecutar

  • -p o --code-repository-path - Especifica la ruta a su base de código (utilice «.» para el directorio actual)

  • -c o --build-command - Especifica el comando de compilación o validación que se va a ejecutar

  • -x o --non-interactive - Activa el modo no interactivo (sin indicaciones del usuario)

  • -t o --trust-all-tools - Confía automáticamente en todas las herramientas sin preguntar

  • -d o --do-not-learn - Impide la extracción de lecciones de esta ejecución

  • --tv o --transformation-version - Especifica una versión específica de la transformación

  • -g o --configuration - Proporciona un archivo de configuración o una configuración en línea

importante

- El -t o --trust-all-tools flag aprueba automáticamente todas las ejecuciones de la herramienta sin previo aviso y evita la mayoría de las barreras de seguridad (los comandos coinciden con sus alwaysPromptCommands la lista aún requiere un permiso explícito a menos que sea anulada por trustedShellCommands). Pasando --non-interactive y --trust-all-tools es necesario para una experiencia totalmente autónoma, pero no es necesario para ejecutar la transformación. Úsela con precaución en entornos de producción.

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 el parámetro proporciona un contexto adicional para el plan de ejecución del agente. Esto es especialmente útil con AWS-gestionó las transformaciones 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:

  • Java: mvn clean install o gradle build

  • Python: pytest o python -m py_compile

  • Node.js: npm run build o npm test

  • Linters: eslint . o pylint .

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

El -d o --do-not-learn flag opta por no permitir la extracción de 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>
importante

Las conversaciones solo se pueden reanudar en un plazo de 30 días a partir de su creación. Transcurridos 30 días, la conversación ya no se puede reanudar.

Minutos del agente de seguimiento

AWS Transforma las pistas personalizadas minutos de agente 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 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 el indicador 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

El --limit la opción establece un máximo Minutos del agente presupuesto para la sesión. Las actas de los agentes reflejan el tiempo de trabajo de los agentes activos, no el horario 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:

  • Los comentarios de los desarrolladores se proporcionan en modo interactivo

  • Problemas de código encontrados durante las transformaciones

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

Utilice 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 para AWS Transforme lo personalizado.

Variables de entorno

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

nota

Los siguientes ejemplos muestran la sintaxis de Linux y macOS (export). En Windows, defina las variables de entorno en PowerShell usando $env:NAME="value". Vea el Windows (PowerShell) pestañas para los comandos equivalentes.

ATX_SHELL_TIMEOUT

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

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

La configuración de la identidad del autor utilizada para el punto de control confirma que AWS Transforma las creaciones personalizadas de tu repositorio a medida que apliquen los cambios durante una transformación. 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:

  • trustedTools - Herramientas que se pueden ejecutar sin preguntar

  • trustedShellCommands - Comandos de Shell que se pueden ejecutar sin preguntar

  • alwaysPromptCommands - Patrones de comandos de Shell que requieren un permiso explícito, a menos que sean anulados por trustedShellCommands, independientemente de -t bandera o confianza de sesión. Estos patrones no se aplican en el modo no interactivo (-x).

Herramientas confiables predeterminadas:

  • file_read

  • get_transformation_from_registry

  • list_available_transformations_from_registry

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 patrones comodín globales usando *.

nota

Si un comando coincide con ambas listas, trustedShellCommands tiene prioridad.

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

  • trustedShellCommands - Los comandos que coinciden con estos patrones se ejecutan sin preguntar, sin pasar por todas las demás barandillas. Los patrones se comparan con la cadena de comandos completa.

    Ejemplos:

    • cd * - Coincide con los comandos compuestos que comienzan por cd

    • *&&* - Confía en todos los comandos con operadores &&

  • alwaysPromptCommands - Los comandos que coincidan con estos patrones requieren un permiso explícito a menos que sean anulados por trustedShellCommands, independientemente de -t bandera o confianza de sesión. Estos patrones no se aplican en el modo no interactivo (-x). Los patrones se comparan con cada subcomando en las expresiones compuestas (&&, ||, sustituciones de comandos).

    Ejemplos:

    • rm -rf * - Siempre solicita comandos de eliminación forzosa recursivos

    • sudo * - Siempre solicita los comandos ejecutados con sudo

    • find * -exec * - Siempre solicita los comandos de búsqueda con -exec

Session-level confianza:

Durante las instrucciones interactivas, puede elegir:

  • (y)es - Ejecutar una vez

  • (n)o - Denegar

  • (t)rust - Confíe únicamente para la sesión actual

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.

nota

La confianza de sesión no está disponible para los comandos que coincidan con su alwaysPromptCommands lista.

Servidores de protocolo de contexto modelo (MCP)

Los AWS La CLI de 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. El AWS La CLI de 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 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 url propiedad:

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

El headers la propiedad es opcional y admite la expansión de variables de entorno mediante ${VAR_NAME} sintaxis. Esto permite almacenar valores sensibles, 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:

  • command (obligatorio): el comando para ejecutar el servidor

  • args (opcional): matriz de argumentos de línea de comandos

  • env (opcional): variables de entorno para pasar al proceso del servidor

Los servidores HTTP remotos admiten las siguientes propiedades:

  • url (obligatorio): la URL HTTP o HTTPS del servidor MCP remoto

  • headers (opcional): encabezados HTTP para incluir en las solicitudes, compatibles con ${VAR_NAME} expansión de variables de entorno

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 conservan como mcp_usage.json en el directorio de conversaciones al lado metadata.json. El archivo registra las métricas por herramienta para cada ejecución, que incluyen:

  • Número de invocaciones por herramienta

  • Número de errores por herramienta

  • Tiempo total de ejecución por herramienta

  • Detalles del último error (si lo hubiera)

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:

  1. <project>/.aws/atx/skills/ - Project-level, AWS Transformar CLI-specific

  2. <project>/.agents/skills/ - Project-level, multicliente (disponible para cualquier herramienta de agente compatible)

  3. ~/.aws/atx/skills/ - User-level, AWS Transformar CLI-specific

  4. ~/.agents/skills/ - User-level, multicliente (disponible para cualquier herramienta de agente compatible)

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

Estructura del directorio de habilidades:

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

nota

Los archivos de una habilidad deshabilitada permanecen en el disco. Si una definición de transformación indica al agente que lea una ruta de archivo específica, el agente podrá seguir accediendo al contenido. El disable-model-invocation la propiedad impide el descubrimiento automático y la inyección de contexto, no el acceso al sistema de archivos.

Disponibilidad de habilidades por modo de ejecución:

  • Modo Exec (atx custom def exec con --code-repository-path) - Descubre las habilidades de los directorios a nivel de usuario y de proyecto.

  • Modo interactivo (atx) - Inicialmente, solo se descubren las habilidades a nivel de usuario. Al proporcionar una ruta al repositorio de código durante la sesión, también se cargan las habilidades a nivel de proyecto.

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.

nota

Client-side las habilidades requieren la versión 2.0 o posterior de la CLI.

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

  • Repository-specific comprobaciones de cumplimiento (reglas de Dockerfile, políticas de Terraform, validadores de seguridad de la migración)

  • Estándares de codificación organizacional que se aplican a esta base de código (patrones de observabilidad, manejo de errores, convenciones de nomenclatura)

  • Cree o pruebe scripts exclusivos para el proyecto (linteros personalizados, funciones de adecuación de la arquitectura)

  • Guías de migración de API para las bibliotecas internas utilizadas en este repositorio

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:

  • Herramientas de flujo de trabajo personales (generadores de registros de cambios, formateadores de mensajes de confirmación)

  • Cross-project preferencias (patrones de prueba preferidos, recordatorios de estilo de documentación)

  • Las comprobaciones de cumplimiento de licencias que su organización exige en todos los repositorios

  • Umbrales de cobertura o barreras de calidad que impones en cada base de código con la que trabajas

Consejos para adquirir habilidades eficaces:

  • Escriba con claridad description campos en tu SKILL.md portada. El agente usa este campo para decidir cuándo una habilidad es relevante.

  • Salga de los scripts de validación con el código 0 en caso de éxito y un código distinto de cero en caso de error. El agente interpreta los códigos de salida para determinar el cumplimiento.

  • Imprima mensajes de error claros y procesables en los scripts. El agente lee el resultado para saber qué corregir.

  • Coloque las habilidades en el directorio entre clientes (.agents/skills/) en cualquier nivel para compartirlas con otras herramientas de desarrollo de IA más allá del AWS Transforme la CLI.

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 los Dockerfiles comparándolos con 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 hay etiquetas de imagen base no ancladas, ejecutadas como root o secretos codificados en ENV directivas, y faltan HEALTHCHECK definiciones. 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 como s3.putObject(params).promise() al equivalente modular v3 usando S3Client y PutObjectCommand.

Etiquetas y organización

Puede organizar las definiciones de transformación que pertenecen a los clientes con etiquetas para el control de acceso, la categorización y la asignación de costos.

Solo puede agregar, actualizar o eliminar etiquetas en las definiciones de transformación propiedad del cliente. No puede administrar las etiquetas en AWS-transformaciones gestionadas.

nota

Algunos de estos comandos requieren especificar el nombre de recurso de Amazon (ARN) para una definición de transformación. La estructura del ARN es: arn:aws:transform-custom:<region>:<account-id>:package/<td-name>

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 o environment:production).

Utilice etiquetas para la asignación de costos

Puede usar etiquetas en las definiciones de transformación que pertenecen a los clientes para organizar sus AWS factura. AWS Transform Custom registra la definición de transformación como recurso de facturación para el Minutos del agente una ejecución consume. Cada ejecución hereda las etiquetas de la definición de transformación que ejecuta. Si varios equipos o proyectos comparten uno AWS cuenta, etiquete cada definición propiedad del cliente con el propietario del costo. A continuación, puede separar los costos de transformación de cada equipo o proyecto.

Después de etiquetar las definiciones de transformación que pertenecen a los clientes, active esas claves de etiqueta en el AWS Consola de facturación y administración de costos. Los valores de las etiquetas no aparecen en los datos de costos hasta que se active la clave de etiqueta. La activación se aplica al uso futuro. Para atribuir el uso de meses anteriores, solicita que se rellene la etiqueta de asignación de costos. Para obtener más información, consulta Asignación de costos y etiquetado en el AWS Guía del usuario de facturación y administración de costos.

Una vez que una clave de etiqueta esté activa, puede agrupar AWS Transforma los cargos con esa clave en Cost Explorer. También puede incluir los ID de recursos en AWS Informes de costo y uso para ver el ARN de la definición de transformación y sus valores de etiqueta en cada partida. Para ver las columnas que contienen esos valores, consulte Columnas de etiquetas de recursos en el AWS Guía del usuario de exportación de datos. El siguiente ejemplo devuelve AWS Transforme el costo y los minutos de los agentes para un día, agrupados por CostCenter etiqueta.

aws ce get-cost-and-usage \ --time-period Start=2026-09-01,End=2026-09-02 \ --granularity DAILY \ --metrics UnblendedCost UsageQuantity \ --filter '{"Dimensions":{"Key":"SERVICE","Values":["AWS Transform"]}}' \ --group-by Type=TAG,Key=CostCenter

Cost Explorer devuelve los cargos sin valor para la clave como un solo grupo con un valor vacío. Esto muestra cuánto gasto queda sin atribuir.

Qué no puedes atribuir por etiqueta

Tag-based la atribución se basa en la definición de transformación. Confirme lo siguiente comparándolo con su modelo de costes antes de utilizar etiquetas para la devolución de cargos.

De uso Por qué no se atribuye y qué hacer en su lugar
AWS-transformaciones gestionadas No puede agregar, actualizar ni eliminar etiquetas en AWS-definiciones de transformación gestionadas. Sus cargos por minutos de agente no heredan las etiquetas de asignación de costos definidas por el cliente.
Sesiones que no ejecutan ninguna definición de transformación Minutos de agente consumidos en un atx las sesiones en las que no se ejecuta una definición de transformación se graban sin un identificador de recurso, por lo que no hay ningún recurso que pueda heredar las etiquetas. Realice el trabajo siguiendo una definición de transformación etiquetada cuando deba atribuirse el gasto.
Ejecuciones individuales de una definición Las etiquetas son una propiedad de la definición de transformación, no de una ejecución, y atx custom def exec no acepta etiquetas. Todas las ejecuciones de una definición comparten los valores de sus etiquetas. Para separar dos responsables de costos, asigne a cada uno su propia definición de transformación.
Usuarios individuales o directores de IAM Los cargos se atribuyen a la definición de la transformación y a la cuenta de ejecución, no a la identidad que inició la ejecución. Per-user la atribución no está disponible a través de las etiquetas de asignación de costos.

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.

nota

Es posible que haya varios archivos de registro de depuración en el directorio de registros (es decir, debug1.log, debug2.log). Revise y proporcione todos los registros relevantes, por ejemplo, ~/.aws/atx/custom/ /* y <conversation-id>~/.aws/atx/logs/ *, al abrir los tickets de soporte para una resolución más rápida.

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.

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

  1. Inicie el AWS Transforme la CLI:

    atx
  2. Dígale al agente que desea crear una nueva transformación.

  3. Proporcione una descripción clara y detallada del objetivo de transformación. Incluya:

    • El estado de origen y el estado de destino (por ejemplo, «actualizar de la versión X a la versión Y»)

    • Se requieren cambios específicos (por ejemplo, «actualizar las declaraciones de importación, reemplazar los métodos obsoletos»)

    • ¿Alguna consideración o restricción especial

  4. Cuando el agente solicite aclaraciones o información adicional, proporcione ejemplos específicos y materiales de referencia.

  5. Revise la definición de transformación inicial creada por el agente.

  6. Pruebe la transformación en una base de código de muestra.

  7. Repite proporcionando comentarios, correcciones de código o ejemplos adicionales.

  8. Guarde la transformación localmente o publíquela en el registro.

Mejores prácticas para crear transformaciones:

  • Comience con transformaciones simples y bien definidas antes de intentar realizar transformaciones complejas

  • Proporcione materiales de referencia completos que incluyen guías de migración y ejemplos de códigos

  • Realice pruebas en varias bases de código de muestra antes de publicarlas

  • Usa comandos deterministas de compilación o validación para permitir el aprendizaje continuo

  • Considera la posibilidad de dividir las transformaciones complejas en varios pasos más pequeños

  • Marque la información crucial con las letras «CRÍTICA» o «IMPORTANTE:» en sus definiciones de transformación para garantizar que el agente dé prioridad a estos requisitos

  • Cuando necesite cumplir los requisitos exactos (por ejemplo, usar un comando o un valor de cadena específicos), especifique explícitamente la cadena completa en sus definiciones de transformación. Puedes ponerlos entre comillas bash para indicar claramente que son comandos de terminal o cadenas literales, lo que reduce la variabilidad y garantiza una ejecución uniforme

Proporcionar materiales de referencia

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

Tipos de archivos de referencia recomendados:

  • Before/after código de ejemplo

  • Documentación sobre las API, las bibliotecas o las funciones involucradas

  • Human-readable guías de migración

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/
nota

Solo se admiten archivos basados en texto (.md, .html, .txt, archivos de código). Los archivos binarios, las imágenes y los archivos de texto enriquecido (por ejemplo, .pdf, .png, .docx) no son compatibles actualmente. A menudo es posible extraer el contenido del texto y usarlo como referencia. Si tiene muchos archivos de texto pequeños, considere la posibilidad de concatenarlos en unos pocos archivos con nombres descriptivos. Hay un límite total de 10 MB para todos los archivos.

Modificación de una transformación existente

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

Para modificar una transformación existente

  1. Inicie el AWS Transforme la CLI:

    atx
  2. Dígale al agente que desea modificar una transformación existente.

  3. Elija si desea:

    • Proporcione una ruta de archivo a una transformación almacenada localmente (es decir, no a un borrador guardado o publicado)

    • Solicite la lista de transformaciones al registro

  4. Si elige una opción del registro, seleccione la transformación que desea modificar.

  5. Trabaje con el agente para describir los cambios que desea realizar.

  6. Pruebe la transformación actualizada en una base de código de muestra.

  7. Publica tus actualizaciones en el registro si lo deseas.

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 una bandera y una versión con --tv bandera.

Para eliminar una definición de transformación:

atx custom def delete -n my-transformation
importante

Esto elimina permanentemente la definición de transformación especificada de su cuenta.

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.