Usar o Google Antigravity para transcodificar e migrar dados

Nesta página, explicamos como usar os recursos de agente no Mainframe Connector para transcodificar e migrar automaticamente os dados do mainframe.

Principais benefícios da integração de agentes

O Mainframe Connector oferece uma superfície de agente que pode ser usada para a modernização de dados. É possível usar agentes em combinação com o Mainframe Connector para modernizar os dados do mainframe no Cloud Storage e localmente. Também é possível usar ambientes de agente, como o Google Antigravity, para criar as configurações do Mainframe Connector necessárias para transcodificar e migrar os dados do mainframe.

Automatizar a transcodificação e a migração de dados

A gravação manual de configurações de transcodificação pode ser propensa a erros e complexa devido à incompatibilidade entre as estruturas COBOL legadas (como REDEFINES, COMP-3 e PIC X) e os bancos de dados modernos da nuvem (como o BigQuery). Essa complexidade geralmente leva a erros no mapeamento de tipos de dados, no alinhamento de bytes e na tradução decimal compactada.

Para simplificar esse processo, o Mainframe Connector oferece recursos de agente, um conjunto de ferramentas focadas (endpoints de API e CLI) e um arquivo de habilidades dedicado, projetado para uso por agentes com tecnologia LLM, como o Google Antigravity. Essa integração permite que um agente crie, valide, corrija e teste arquivos de configuração de transcodificação de forma autônoma. Em seguida, o agente pode migrar os dados atuais do Cloud Storage ou de um armazenamento local para o BigQuery ou outros bancos de dados usando as configurações geradas.

O uso de recursos de agente no Mainframe Connector oferece os seguintes benefícios:

  • Criação automatizada:o Google Antigravity pode gerar a configuração inicial com base em um copybook COBOL e em regras de negócios definidas pelo usuário.
  • Loops de feedback rápidos:as ferramentas de validação integradas permitem que o agente teste rapidamente as configurações e corrija erros antes de processar os dados.
  • Inspeção no nível de byte:o agente pode inspecionar dados binários brutos para diagnosticar problemas de alinhamento e codificação.
  • Testes determinísticos:comandos leves e de linha única fornecem um ambiente de teste confiável para o processo de raciocínio do agente.

Antes de começar

  • Para usar os recursos de agente, instale a versão mais recente do Mainframe Connector. Os recursos de agente estão disponíveis a partir da versão 5.20.
  • Para executar as habilidades do agente, instale uma CLI ou um ambiente de agente, como o Google Antigravity, na mesma máquina em que você instalou o Mainframe Connector.

  • Extraia o arquivo de habilidades do agente para a pasta de habilidades do ambiente com o seguinte comando:

    java -jar mainframe-connector.jar agent skill-file --output-dir SKILLS_FOLDER_PATH

Como funciona a integração de agentes

O arquivo de habilidades do Mainframe Connector contém todas as informações necessárias para permitir que um agente crie, valide e teste o copybook do mainframe de configuração de transcodificação e arquivos de dados. Ele abstrai os comandos da CLI do Mainframe Connector e oferece uma interface simplificada para o agente interagir com o produto.

Quando você solicita o agente usando o arquivo de habilidades, ele executa versões otimizadas por IA dos comandos do Mainframe Connector. Se você fornecer o copybook e os dados de amostra, o agente poderá criar o arquivo de configuração de transcodificação e validá-lo com dados reais. No prompt, forneça ao agente o contexto e as regras especiais a serem aplicadas na transcodificação.

Fluxo de trabalho de agente

O fluxo de trabalho de agente consiste em cinco fases, permitindo que o agente avance da solicitação inicial do usuário para uma configuração validada e funcional. Após o prompt do usuário, o agente pode concluir as etapas a seguir de forma autônoma.

Fase Descrição
Iniciação O usuário solicita que o agente crie um arquivo de configuração de transcodificação. Opcionalmente, o usuário pode fornecer um copybook COBOL, regras de negócios personalizadas (como "descartar todos os campos FILLER") e dados EBCDIC de amostra opcionais.
Criação O agente lê a referência configuration-doc para entender as regras de formatação e gera o arquivo de configuração de rascunho.
Validação O agente valida a sintaxe e a estrutura do rascunho executando validate-configuration, corrigindo erros e verificando o projeto estrutural.
Testes Se os dados de amostra forem fornecidos, o agente testará a configuração executando simple-encode ou simple-decode, e usará inspect-data para verificar se a saída corresponde às expectativas.
Finalizar O agente gera o DDL de destino usando generate-target-ddl, e apresenta a configuração e o DDL de trabalho ao usuário.

Casos de uso

Os exemplos a seguir ilustram como usar os recursos de agente para transcodificar e migrar seus dados.

Exemplo 1: gerar esquemas de dados para o BigQuery usando um copybook

O exemplo de prompt a seguir mostra como usar os recursos de agente para transcodificar os dados de um copybook do mainframe e gerar uma tabela do BigQuery.

Exemplo de prompt

Your task is to produce a transcode configuration file and target DDL for a
mainframe dataset using the Mainframe Connector skill.

You are migrating a master file from a European subsidiary's mainframe into
BigQuery. Each record holds a customer name, a city, and a price.
The source is an EBCDIC extract from a German z/OS system; the system metadata
gives its CCSID as 1140.

The data is staged here in this directory:

- `copybook.cpy`: the COBOL layout.
- `input.dat`: the binary extract itself (CCSID 1140 - the German Euro-enabled
  EBCDIC code page).

Produce two artifacts here:

1. `config.json`: the transcode configuration that correctly decodes this file.
2. `schema.sql`: the BigQuery `CREATE TABLE` DDL for the destination.

Exemplo 2: fazer upload dos dados para o BigQuery após a transcodificação

O prompt a seguir mostra como usar os recursos de agente para fazer upload dos dados transcodificados do exemplo anterior para o BigQuery.

Exemplo de prompt

Using the Mainframe Connector skill and the config.json and schema.sql files
you created before, migrate the data to BigQuery at
`table_name.dataset_name.project_id`.

Exemplo 3: implantar em um banco de dados PostgreSQL com controles de privacidade

O prompt a seguir mostra como usar os recursos de agente para implantar os dados transcodificados do exemplo anterior no PostgreSQL, removendo os dados PII.

Exemplo de prompt

Using the Mainframe Connector skill, migrate the data to Cloud SQL for
PostgreSQL at `table_name.schema_name.host_name`.

Compliance constraint: `CUST-NAME` and `CITY` are classified as
personally identifying or residency restricted information. They must NOT
appear in the PostgreSQL CSV staging file, must NOT decode into a JSM
string at any point, and must NOT appear in the Postgres table DDL.
Only `PRICE-TEXT` should appear.

Deliverables in the current working directory:

1. `config-postgres.json`: a NEW transcode configuration (do not overwrite
the BigQuery config.json).
2. `schema-postgres.sql`: the PostgreSQL `CREATE TABLE` DDL for the
   destination.
3. `copy-postgres.sql`: the PostgreSQL `COPY FROM` command to load the
   data into the table.

Pacote de comandos de agente

Os comandos a seguir foram projetados para agentes LLM.

agent configuration-doc

Gera o documento de configuração para agentes LLM para stdout.

Synopsis

agent configuration-doc [-h]

Sinalizações e argumentos

O comando agent configuration-doc usa as seguintes sinalizações e argumentos:

--help ou -h
(Opcional) Mostra esta mensagem de ajuda.

agent inspect-data

Lê um único registro lógico começando em um deslocamento de byte específico e imprime o despejo hexadecimal e a representação de texto.

Synopsis

agent inspect-data [-h] [--byte-offset=BYTEOFFSET]
                          --input=INPUTPATH

Sinalizações e argumentos

O comando agent inspect-data usa as seguintes sinalizações e argumentos:

--byte-offset=BYTEOFFSET
(Opcional) Especifica o deslocamento de byte absoluto no arquivo para começar a leitura. O valor padrão é 0.
--help ou -h
(Opcional) Mostra esta mensagem de ajuda.
--input=INPUTPATH : DataPath
Especifica o caminho dos dados de entrada.

agent simple-decode

Decodifica algumas linhas de um arquivo do mainframe para stdout para depuração do agente.

Synopsis

agent simple-decode [-h] [--byte-offset=BYTEOFFSET]
                           --copybook=COPYBOOKPATH
                           --input=INPUTPATH
                           [--limit=LIMIT]
                           [--output=OUTPUTPATH]
                           --transcode-configuration=CONFIGPATH

Sinalizações e argumentos

O comando agent simple-decode usa as seguintes sinalizações e argumentos:

--byte-offset=BYTEOFFSET
(Opcional) Especifica o deslocamento de byte absoluto no arquivo de entrada para começar a leitura. O valor padrão é 0.
--copybook=COPYBOOKPATH : DataPath
Especifica o caminho dos dados do copybook.
--help ou -h
(Opcional) Mostra esta mensagem de ajuda.
--input=INPUTPATH : DataPath
Especifica o caminho dos dados de entrada.
--limit=LIMIT
(Opcional) Especifica o número máximo de registros a serem decodificados. Os registros descartados por record_filter_condition ainda contam nesse limite. O valor padrão é 5.
--output=OUTPUTPATH : DataPath
(Opcional) Especifica o destino da saída JSON decodificada. Se não for fornecido, o padrão será stdout.
--transcode-configuration=CONFIGPATH : DataPath
Especifica o caminho dos dados da configuração de transcodificação. Para mais informações sobre o formato de configuração do transcodificador, consulte Configuração do transcodificador.

agent simple-encode

Codifica um arquivo JSON de volta para dados binários EBCDIC do mainframe.

Synopsis

agent simple-encode [-h] --copybook=COPYBOOKPATH
                           --input=INPUTPATH
                           --output=OUTPUTPATH
                           --transcode-configuration=CONFIGPATH

Sinalizações e argumentos

O comando agent simple-encode usa as seguintes sinalizações e argumentos:

--copybook=COPYBOOKPATH : DataPath
Especifica o caminho dos dados do copybook.
--help ou -h
(Opcional) Mostra esta mensagem de ajuda.
--input=INPUTPATH : DataPath
Especifica o caminho dos dados JSON de entrada.
--output=OUTPUTPATH : DataPath
Especifica o caminho dos dados binários de saída.
--transcode-configuration=CONFIGPATH : DataPath
Especifica o caminho dos dados da configuração de transcodificação. Para mais informações sobre o formato de configuração do transcodificador, consulte Configuração do transcodificador.

agent validate-configuration

Valida uma configuração de transcodificador em relação a um copybook e regras de banco de dados.

Synopsis

agent validate-configuration [-h] --copybook=COPYBOOKPATH
                                    --database=DATABASE
                                    --transcode-configuration=CONFIGPATH

Sinalizações e argumentos

O comando agent validate-configuration usa as seguintes sinalizações e argumentos:

--copybook=COPYBOOKPATH : DataPath
Especifica o caminho dos dados do copybook.
--database=DATABASE
Especifica o banco de dados de destino (por exemplo, BIGQUERY, POSTGRES, MYSQL).
--help ou -h
(Opcional) Mostra esta mensagem de ajuda.
--transcode-configuration=CONFIGPATH : DataPath
Especifica o caminho dos dados que contém a configuração de transcodificação de rascunho. Para mais informações sobre o formato de configuração do transcodificador, consulte Configuração do transcodificador.