本頁面說明如何使用 Mainframe Connector 中的代理能力，自動轉碼及遷移大型主機資料。
代理式整合的主要優點
Mainframe Connector 支援代理程式介面，可用於資料現代化。您可以搭配使用代理程式和 Mainframe Connector，在 Cloud Storage 和本機上將現有大型主機資料現代化。您也可以使用 Google Antigravity 等代理環境，建立轉碼及遷移大型主機資料所需的 Mainframe Connector 設定。
自動轉碼及遷移資料
由於舊版 COBOL 結構 (例如 REDEFINES、COMP-3 和 PIC X) 與現代雲端資料庫 (例如 BigQuery) 不相容，因此手動編寫轉碼設定時容易出錯，而且相當複雜。這種複雜性通常會導致資料型別對應、位元組對齊和封裝十進位轉換發生錯誤。
為簡化這項程序，Mainframe Connector 支援代理程式功能，包括一組專用工具 (API 和 CLI 端點) 和專屬技能檔案，供 Google Antigravity 等 LLM 驅動的代理程式使用。這項整合功能可讓代理程式自主草擬、嚴格驗證、自我修正及測試轉碼設定檔。然後，代理程式會使用產生的設定，將現有資料從 Cloud Storage 或本機儲存空間遷移至 BigQuery 或其他資料庫。
在 Mainframe Connector 中使用 AI 虛擬服務各項能力，可享有下列優點：
- 自動草擬：Google Antigravity 可根據 COBOL 副本和使用者定義的業務規則，產生初始設定。
- 快速回饋迴路：內建驗證工具可讓代理程式快速測試設定，並在處理資料前自行修正錯誤。
- 位元組層級檢查：代理程式可以檢查原始二進位資料，診斷對齊和編碼問題。
- 決定性測試：輕量級的單一執行緒指令可為代理程式的推論程序提供可靠的測試環境。
事前準備
- 如要使用代理能力，請務必安裝最新版 Mainframe Connector。代理能力自 5.20 版開始提供。
- 如要執行代理程式技能，您必須在安裝 Mainframe Connector 的同一部電腦上，安裝代理程式 CLI 或環境，例如 Google Antigravity。
使用下列指令，將代理程式技能檔案解壓縮至環境的 skills 資料夾：
java -jar mainframe-connector.jar agent skill-file --output-dir SKILLS_FOLDER_PATH
代理整合的運作方式
Mainframe Connector 技能檔案包含所有必要資訊，可讓代理程式建立、驗證及測試轉碼設定，以及大型主機副本和資料檔案。這項工具會抽象化基礎的 Mainframe Connector CLI 指令，並提供簡化的介面，供代理程式與產品互動。
使用技能檔案提示代理程式時，代理程式會執行 Mainframe Connector 指令的 AI 最佳化版本。如果您提供副本和範例資料，代理程式可以建立轉碼設定檔，並根據實際資料驗證該檔案。在提示中，請務必提供代理程式背景資訊和轉碼時要套用的特殊規則。
代理式工作流程
代理工作流程分為五個階段，讓代理程式從初始使用者要求逐步完成並驗證設定。使用者發出提示後，代理程式即可自動完成下列步驟。
| 階段 | 說明 |
|---|---|
| 啟動 | 使用者提示代理程式建立轉碼設定檔。 使用者可以選擇提供 COBOL 副本、自訂業務規則 (例如「捨棄所有 FILLER 欄位」)，以及選用的 EBCDIC 資料樣本。 |
| 草擬 |
代理會讀取 configuration-doc 參考資料，瞭解格式規則，然後生成設定檔草稿。 |
| 驗證 |
代理程式會執行 validate-configuration 驗證草稿的語法和結構、修正錯誤，並驗證結構藍圖。 |
| 測試 |
如果提供範例資料，代理程式會執行 simple-encode 或 simple-decode 來測試設定，並使用 inspect-data 驗證輸出內容是否符合預期。
|
| 完成 |
代理程式會使用 generate-target-ddl 生成目標 DDL，並向使用者顯示工作設定和 DDL。 |
用途
以下範例說明如何使用代理能力轉碼及遷移資料。
範例 1：使用副本產生 BigQuery 的資料結構定義
以下範例提示說明如何使用代理能力，轉碼大型主機副本簿中的資料，並產生 BigQuery 資料表。
提示範例
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.
範例 2：轉碼後將資料上傳至 BigQuery
以下提示說明如何使用代理能力，將上一個範例中轉碼的資料上傳至 BigQuery。
提示範例
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`.
範例 3：部署至 PostgreSQL 資料庫，並啟用隱私權控管機制
以下提示說明如何使用代理能力，將上一個範例中轉碼的資料部署至 PostgreSQL，同時移除 PII 資料。
提示範例
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.
代理指令套件
下列指令適用於 LLM 代理程式。
agent configuration-doc
將 LLM 代理程式的設定文件輸出至 stdout。
劇情概要
agent configuration-doc [-h]
旗標和引數
agent configuration-doc 指令會使用下列旗標和引數：
--help或-h- (選用) 顯示這則說明訊息。
agent inspect-data
從特定位元組偏移量開始讀取單一邏輯記錄，然後列印其十六進位傾印和文字表示法。
劇情概要
agent inspect-data [-h] [--byte-offset=BYTEOFFSET]
--input=INPUTPATH
旗標和引數
agent inspect-data 指令會使用下列旗標和引數：
--byte-offset=BYTEOFFSET- (選用) 指定檔案中的絕對位元組偏移，從該處開始讀取。預設值為 0。
--help或-h- (選用) 顯示這則說明訊息。
--input=INPUTPATH : DataPath- 指定輸入資料路徑。
agent simple-decode
將主機檔案的幾列解碼至 stdout，以進行代理程式偵錯。
劇情概要
agent simple-decode [-h] [--byte-offset=BYTEOFFSET]
--copybook=COPYBOOKPATH
--input=INPUTPATH
[--limit=LIMIT]
[--output=OUTPUTPATH]
--transcode-configuration=CONFIGPATH
旗標和引數
agent simple-decode 指令會使用下列旗標和引數：
--byte-offset=BYTEOFFSET- (選用) 指定輸入檔案中的絕對位元組偏移，從該處開始讀取。預設值為 0。
--copybook=COPYBOOKPATH : DataPath- 指定副本的資料路徑。
--help或-h- (選用) 顯示這則說明訊息。
--input=INPUTPATH : DataPath- 指定輸入資料路徑。
--limit=LIMIT- (選用) 指定要嘗試解碼的記錄數量上限。即使
record_filter_condition捨棄記錄，仍會計入這項限制。預設值為 5。 --output=OUTPUTPATH : DataPath- (選用) 指定已解碼 JSON 輸出內容的目的地。如未提供，則預設為
stdout。 --transcode-configuration=CONFIGPATH : DataPath- 指定轉碼設定的資料路徑。如要進一步瞭解轉碼器設定格式，請參閱轉碼器設定。
agent simple-encode
將 JSON 檔案編碼回大型主機 EBCDIC 二進位資料。
劇情概要
agent simple-encode [-h] --copybook=COPYBOOKPATH
--input=INPUTPATH
--output=OUTPUTPATH
--transcode-configuration=CONFIGPATH
旗標和引數
agent simple-encode 指令會使用下列旗標和引數：
--copybook=COPYBOOKPATH : DataPath- 指定副本的資料路徑。
--help或-h- (選用) 顯示這則說明訊息。
--input=INPUTPATH : DataPath- 指定輸入 JSON 資料路徑。
--output=OUTPUTPATH : DataPath- 指定輸出二進位資料路徑。
--transcode-configuration=CONFIGPATH : DataPath- 指定轉碼設定的資料路徑。如要進一步瞭解轉碼器設定格式，請參閱轉碼器設定。
agent validate-configuration
根據副本和資料庫規則驗證 轉碼器設定。
劇情概要
agent validate-configuration [-h] --copybook=COPYBOOKPATH
--database=DATABASE
--transcode-configuration=CONFIGPATH
旗標和引數
agent validate-configuration 指令會使用下列旗標和引數：
--copybook=COPYBOOKPATH : DataPath- 指定副本的資料路徑。
--database=DATABASE- 指定目標資料庫 (例如
BIGQUERY、POSTGRES、MYSQL)。 --help或-h- (選用) 顯示這則說明訊息。
--transcode-configuration=CONFIGPATH : DataPath- 指定包含轉碼設定草稿的資料路徑。如要進一步瞭解轉碼器設定格式，請參閱「轉碼器設定」。