As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Fluxos de trabalho

Executando transformações

Esta seção descreve as diferentes formas de executar transformações e as opções para controlar o comportamento da execução.

Modos de execução

AWS O Transform custom oferece suporte a três modos de execução para acomodar diferentes fluxos de trabalho.

Modo conversacional interativo

Inicie a CLI com atx e peça ao agente que execute uma transformação por meio da linguagem natural. Esse modo permite que você tenha uma conversa completa com o agente, interrompa a execução a qualquer momento e forneça feedback durante o processo de transformação.

Use esse modo quando quiser o máximo controle e a capacidade de guiar o agente em cenários complexos.

Execução direta interativa

Use atx custom def exec -n <transformation-name> -p <path> para iniciar uma transformação específica de forma interativa. Esse modo permite que você revise e interaja com o agente no início, durante ou no final da execução. O agente fará uma pausa nos principais pontos de decisão e pedirá sua opinião.

Isso é ideal para testar e refinar transformações antes de executá-las de forma autônoma.

Você pode executar transformações no modo não interativo ou no modo headless. Non-interactive o modo suprime as solicitações durante uma transformação nomeada. O modo headless permite que você execute o agente com um prompt de texto sem formatação, ignorando totalmente a interface interativa.

Non-interactive modo

Use atx custom def exec -n <transformation-name> -p <path> -x -t para automação total. Adicione -x para executar no modo não interativo e -t para confiar em todas as ferramentas automaticamente sem aviso prévio.

Esse modo foi projetado para integração de CI/CD tubulações e execução em massa, onde nenhuma intervenção humana está disponível ou é desejada.

Modo sem cabeça

Para concluir tarefas sem interagir com o agente, execute atx -x "<prompt>" -t e forneça suas instruções em texto simples.

Execução de transformação sem interrupções

Use esse modo para aplicar uma definição de transformação existente à sua base de código. A transformação executa cada etapa automaticamente sem exigir sua aprovação.

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

Desenvolvimento de transformação sem cabeça

Crie ou modifique definições de transformação.

Para converter uma definição de transformação antiga para o novo formato de habilidade (SKILL.md + referências/), execute o seguinte comando:

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

Para criar uma nova definição de transformação, execute o seguinte comando:

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

Sinalizadores de comando comuns

Ao executar transformações comatx custom def exec, os seguintes sinalizadores são comumente usados:

Usando arquivos de configuração

AWS O Transform custom oferece suporte a arquivos de configuração opcionais no formato YAML ou JSON. Os arquivos de configuração permitem que você especifique parâmetros de execução e forneça contexto adicional ao agente.

Para usar um arquivo de configuração:

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

Você também pode fornecer a configuração como pares de valores-chave em linha:

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

Exemplo de arquivo de configuração (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

O additionalPlanContext parâmetro fornece contexto adicional para o plano de execução do agente. Isso é especialmente útil com transformações AWS gerenciadas para personalizar seu comportamento de acordo com suas necessidades específicas.

Comandos de compilação e validação

O comando de compilação ou validação é um parâmetro opcional que especifica como validar seu código durante o processo de transformação. AWS O Transform custom tentará inferir o melhor comando de construção com base na transformação, se não for especificado, embora seja recomendado que seja específico em termos de qualidade.

Exemplos de comandos de compilação e validação:

Mesmo para linguagens ou transformações que não exigem construção, fornecer um comando que valide os resultados e retorne problemas se a validação falhar é muito importante para melhorar a qualidade da transformação.

Se nenhuma compilação ou validação for necessária, omita da sua entrada.

Controlando o comportamento de aprendizagem

Por padrão, o AWS Transform custom extrai lições de cada execução de transformação. Você pode evitar o aprendizado para execuções específicas.

Para evitar o aprendizado com uma execução:

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

O --do-not-learn sinalizador -d or opta por não permitir a extração da lição da execução atual.

Retomando conversas

AWS O Transform custom permite que você retome conversas anteriores dentro de 30 dias após a criação.

Para retomar a conversa mais recente:

atx --resume

Para retomar uma conversa específica:

atx --conversation-id <conversation-id>

Minutos do agente de rastreamento

AWS O Transform custom rastreia os minutos do agente consumidos durante uma sessão de transformação. Os minutos do agente se acumulam durante todo o ciclo de vida da conversa e são exibidos quando a conversa termina:

Agent minutes used: 12.50

Os minutos do agente persistem em todas as interrupções. Se você interromper uma sessão com Ctrl+C e retomá-la posteriormente, os minutos acumulados anteriormente serão transferidos e continuarão sendo acumulados na sessão retomada.

Para verificar os minutos do agente durante uma sessão interativa:

Digite /usage no prompt de entrada para exibir os minutos atuais acumulados do agente sem encerrar a conversa.

Para definir um limite de orçamento de minutos do agente:

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

A --limit opção define um orçamento máximo de minutos do agente para a sessão. Os minutos do agente refletem o tempo de trabalho do agente ativo, não o horário do relógio de parede. Quando o limite é atingido, a CLI exibe uma mensagem e sai com instruções para continuar:

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

Você pode retomar a conversa mais tarde com um limite maior:

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

Aprendizagem contínua

Esta seção descreve como revisar e gerenciar as aulas criadas pelo aprendizado contínuo.

Entendendo as lições

O sistema de aprendizado contínuo extrai automaticamente as lições de execuções anteriores de uma transformação. O sistema os cria de forma assíncrona com base em:

As aulas se acumulam com o tempo à medida que você executa a transformação em diferentes bases de código. O sistema os aplica automaticamente para melhorar as execuções futuras. Cada lição pertence a uma categoria que contém todas as lições de um domínio similar para que vocês possam revisar as lições relacionadas em conjunto. Para aulas que você não gostaria de usar, você pode arquivar ou excluir totalmente a lição.

Visualizando e gerenciando aulas

Use o learnings comando para abrir uma sessão interativa para navegar e gerenciar as lições de uma definição de transformação.

Para abrir o visualizador de aulas:

atx custom def learnings -n my-transformation

O visualizador abre uma lista de categorias de aulas, cada uma mostrando quantas aulas ativas ela contém. Selecione uma categoria para ver suas aulas e, em seguida, selecione uma lição para ver todos os detalhes, incluindo o corpo da aula, seu impacto e quantas edições anteriores a consultaram.

Aulas de arquivamento e restauração

O sistema aplica as aulas automaticamente. Se você não quiser que o sistema aplique uma lição, você pode arquivá-la. O sistema retém as aulas arquivadas, mas não as aplica a futuras execuções. Todas as aulas arquivadas são agrupadas para que você possa revisá-las e restaurá-las para uso ativo.

Excluindo aulas

Remova permanentemente uma lição que não seja útil. A exclusão não pode ser desfeita e o sistema pode reaprender uma lição excluída em futuras execuções.

Uma lição deve ser arquivada antes de ser excluída.

Configuração avançada

Esta seção descreve os recursos avançados e as opções de configuração do AWS Transform custom.

Variáveis de ambiente

Você pode personalizar o comportamento da CLI usando variáveis de ambiente.

ATX_SHELL_TIMEOUT

Substitua o tempo limite padrão para comandos do shell (900 seconds/15 minutos).

Linux and macOS

export ATX_SHELL_TIMEOUT=1800  # 30 minutes

Windows (PowerShell)

$env:ATX_SHELL_TIMEOUT=1800  # 30 minutes

Isso é útil para grandes bases de código ou processos de compilação de longa duração.

ATX_DISABLE_UPDATE_CHECK

Desative as verificações automáticas de versão e as notificações de atualização durante a execução do comando.

Linux and macOS

export ATX_DISABLE_UPDATE_CHECK=true

Windows (PowerShell)

$env:ATX_DISABLE_UPDATE_CHECK="true"

ATX_GIT_COMMITTER_NAME e ATX_GIT_COMMITTER_EMAIL

Configure a identidade do autor usada para os commits do ponto de verificação que o AWS Transform custom cria em seu repositório à medida que aplica as alterações durante uma transformação. Quando essas variáveis não são definidas, as confirmações do ponto de verificação são atribuídas a uma identidade padrão ()ATX Bot <checkpoint@atx.bot>. Defina as duas variáveis para atribuir pontos de verificação a um 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"

Configurações de confiança

As configurações de confiança permitem que você pré-aprove ferramentas e comandos específicos para execução sem solicitações. Você também pode exigir permissão explícita para comandos específicos do shell, independentemente do nível de confiança. Essas configurações são definidas no arquivo ~/.aws/atx/trust-settings.yaml.

O arquivo contém três listas:

Ferramentas confiáveis padrão:

Editando configurações de confiança:

Você pode editar manualmente o arquivo trust-settings.yaml para adicionar ou remover ferramentas e comandos confiáveis. Ambos trustedShellCommands alwaysPromptCommands suportam padrões globais de curingas usando. *

O seguinte descreve cada lista de comandos e fornece exemplos:

Session-level confiança:

Durante os prompts interativos, você pode escolher:

Session-level as configurações de confiança são temporárias e são redefinidas quando a CLI é reiniciada, fornecendo aprovação temporária sem modificar permanentemente trust-settings.yaml.

Servidores do Model Context Protocol (MCP)

O AWS Transform CLI oferece suporte a servidores Model Context Protocol (MCP), que ampliam sua funcionalidade com ferramentas adicionais.

Configuração:

Configure os servidores MCP no ~/.aws/atx/mcp.json arquivo. O AWS Transform CLI suporta dois tipos de servidores MCP: servidores locais baseados em comandos e servidores HTTP remotos.

Servidores locais baseados em comandos:

Os servidores locais são executados como processos secundários em sua máquina. Configure-os com a command propriedade:

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

Servidores HTTP remotos:

Os servidores remotos se conectam aos servidores MCP hospedados em uma URL HTTP ou HTTPS. Configure-os com a url propriedade:

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

A headers propriedade é opcional e oferece suporte à expansão de variáveis de ambiente usando a ${VAR_NAME} sintaxe. Isso permite que você armazene valores confidenciais, como tokens de API, em variáveis de ambiente e não no arquivo de configuração.

Propriedades de configuração:

Os servidores locais baseados em comandos oferecem suporte às seguintes propriedades:

Os servidores HTTP remotos oferecem suporte às seguintes propriedades:

Gerenciando servidores MCP:

Veja a lista de servidores MCP configurados:

atx mcp tools

Liste as ferramentas disponíveis oferecidas por um servidor MCP específico:

atx mcp tools --server <server-name>

Rastreamento de uso:

A CLI rastreia automaticamente o uso da ferramenta MCP durante as execuções de transformação. As estatísticas de uso são mantidas, como mcp_usage.json no diretório de conversas ao ladometadata.json. O arquivo registra métricas por ferramenta para cada execução, incluindo:

Client-Side Habilidades

Client-side habilidades são recursos adicionais que ampliam o agente durante as execuções de transformação. Eles permitem que você forneça ferramentas, scripts e instruções personalizados que o agente pode usar junto com seus recursos integrados.

Diretórios de descoberta de habilidades:

As habilidades são descobertas em quatro diretórios em ordem de precedência. Se uma habilidade com o mesmo nome existir em vários diretórios, o primeiro diretório na lista terá prioridade:

Os .aws/atx/skills/ diretórios são específicos da CLI do AWS Transform. Os .agents/skills/ diretórios são multiclientes, o que significa que as habilidades colocadas lá estão disponíveis para qualquer ferramenta de agente compatível além da CLI do Transform AWS .

Estrutura do diretório de habilidades:

Cada habilidade é um diretório contendo um SKILL.md arquivo com o frontmatter 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...

O name campo deve corresponder ao nome do diretório principal.

Desativando uma habilidade:

Para evitar que uma habilidade seja carregada sem remover seus arquivos, adicione disable-model-invocation: true ao frontmatter:

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

Quando essa propriedade é definida, a CLI ignora a habilidade durante a descoberta. O agente não pode ver nem usar a habilidade, a menos que uma definição de transformação o instrua explicitamente a ler o arquivo de habilidade. Use isso para desativar temporariamente uma habilidade, marcá-la como trabalho em andamento ou manter o material de referência destinado somente a leitores humanos.

Disponibilidade de habilidades por modo de execução:

Verificando a descoberta de habilidades:

Verifique o registro de depuração da CLI após uma execução para verificar quais habilidades foram descobertas:

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

As habilidades que falham na validação são ignoradas com um aviso nos registros de depuração.

Escolhendo entre Project-Level e User-Level habilidades

O local onde você coloca uma habilidade determina quem se beneficia dela e quando ela é ativada.

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

Comprometa-os ao controle de versão para que cada membro da equipe que executa transformações no repositório os descubra automaticamente. Use habilidades em nível de projeto para:

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

Eles permanecem na sua máquina e são ativados durante todas as transformações, independentemente do repositório de destino. Use habilidades em nível de usuário para:

Dicas para habilidades eficazes:

Client-Side Exemplos de habilidades

Esses exemplos mostram dois padrões comuns: uma habilidade de validação baseada em script e uma habilidade somente de referência.

Exemplo: Dockerfile Compliance Checker () Script-Based

Essa habilidade valida os Dockerfiles em relação às melhores práticas operacionais e de segurança. Ele usa um script de validação que o agente executa antes e depois de fazer as alterações.

Estrutura de diretórios:

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

O script de validação verifica se há tags de imagem base não fixadas, executadas como raiz, segredos codificados em ENV diretivas e definições ausentes. HEALTHCHECK O agente executa o script, corrige violações usando padrões do arquivo de referência e executa novamente o script para confirmar a conformidade.

Exemplo: Auxiliar de depreciação da API () Reference-Only

Essa habilidade orienta o agente na substituição de chamadas de API obsoletas durante as transformações de upgrade. Ele usa somente arquivos de referência sem scripts.

Estrutura de diretórios:

.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

Os arquivos de referência contêm exemplos de código de antes e depois. Por exemplo, aws-sdk-v2-to-v3.md mapeia padrões como s3.putObject(params).promise() o equivalente modular v3 usando S3Client e. PutObjectCommand

Tags e organização

Você pode organizar transformações com tags para controle de acesso e categorização.

Para listar tags para uma transformação:

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

Para adicionar tags a uma transformação:

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

Para remover tags de uma transformação:

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

As tags podem ser usadas para controle de acesso agrupado nas políticas do IAM. Você pode criar políticas que concedam permissões para todas as transformações com tags específicas (por exemplo, todas as transformações marcadas com team:frontend ouenvironment:production).

Logs

AWS O Transform CLI mantém três tipos de registros para solução de problemas e depuração.

Registros de conversas:

Linux and macOS

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

Windows

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

Esses registros contêm o histórico completo de conversas de uma sessão específica.

Registros do subagente:

Linux and macOS

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

Windows

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

Esses registros contêm saídas de subagentes que o agente principal gera durante as transformações. Você não precisa gerenciar subagentes diretamente.

Registros de depuração do desenvolvedor:

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

Esses registros fornecem informações avançadas de solução de problemas para a própria CLI.

Atualizações da CLI

Mantenha sua CLI atualizada para acessar novos recursos e melhorias.

Para verificar se há atualizações:

atx update --check

Para atualizar para a versão mais recente:

atx update

Para atualizar para uma versão específica:

atx update --target-version <version>

Crie transformações personalizadas

Esta seção descreve como criar, modificar e gerenciar definições de transformação personalizadas.

Criando uma nova transformação

Use a CLI interativa para criar uma nova definição de transformação.

Para criar uma definição de transformação

Práticas recomendadas para criar transformações:

Fornecimento de materiais de referência

Você pode fornecer arquivos de referência ao AWS Transform custom especificando os caminhos dos arquivos durante a conversa. Esses arquivos são armazenados na references/ pasta da definição de transformação.

Tipos recomendados de arquivos de referência:

Para fornecer um arquivo de referência:

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

Você também pode fornecer um diretório contendo vários arquivos de referência:

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

Modificando uma transformação existente

Você pode modificar as transformações personalizadas antes e depois de salvá-las como rascunhos ou publicá-las. Você não pode modificar AWS transformações gerenciadas. Se precisar personalizá-los, você pode fornecer contexto adicional usando o arquivo de configuração.

Para modificar uma transformação existente

Publicando e gerenciando transformações

Você pode publicar e gerenciar suas transformações usando a experiência interativa ou com os seguintes comandos.

Para salvar uma transformação como rascunho:

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

Para publicar uma transformação:

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

Para listar as transformações disponíveis:

atx custom def list

Para baixar uma definição de transformação:

atx custom def get -n my-transformation

Isso baixa a definição de transformação para seu diretório de trabalho atual. Você pode especificar um diretório de destino com o --td sinalizador e uma versão com o --tv sinalizador.

Para excluir uma definição de transformação:

atx custom def delete -n my-transformation

Gerenciando versões de transformação

AWS O Transform custom mantém versões de suas definições de transformação. Você pode especificar uma versão ao executar ou baixar uma transformação.

Para executar uma versão específica:

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

Para baixar uma versão específica:

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

Se nenhuma versão for especificada, a versão mais recente será usada.