Batch-Transformation

The Batch Transform tool enables agents to process CSV files in bulk using just‑in‑time (JIT) data sources. It is designed for scenarios where you want to apply the same transformation logic across every row or record in a CSV file without setting up storage buckets or indexes ahead of time.

Batch Transform takes an input CSV file provided at runtime and applies a user-defined transformation task to it. The tool processes the file row by row and produces one or more output files that include the original data along with any additional columns or rows generated by the transformation logic.

Typical use cases include:

• Enriching CSV files with model-generated scores, labels, or classifications
• Applying business rules or decision logic to large datasets
• Producing explanations or justifications alongside automated decisions

Datenquellen

• Batch Transform supports JIT data sources only.
• Only CSV files are supported as input.
• Files are passed directly through agent inputs and resolved automatically at runtime.
• No external storage configuration or index creation is required.

Configuring Batch Transform

Add the Batch Transform tool

1. Open your agent in design mode.
2. From the built-in tools list, add Batch Transform to the agent.

Once added, the Batch Transform tool appears as a dedicated tool node that you can configure from the right-side panel.

Configure inputs

At design time, you specify how the tool should receive its input:

• Source file: The source is a file input (for example, input-csv). At runtime, this resolves automatically to the file provided when the agent runs.

  Hinweis:

  You must configure a file type argument in Data manager.

• Batch Transform task - The tool-specific instruction that defines how the batch transform should be performed. Use this field to tell the tool exactly how to process the input file, including:

  • What new columns or rows to generate
  • How each row should be processed
  • Any rules, criteria, or decision logic to apply

  For example, you might instruct the tool to generate two new columns such as a score and a recommendation flag based on the contents of each row. This is not an agent prompt. The agent should only include a high-level instruction for when to invoke the batch transform and what the final output should look like.

  

• Output columns — Define the schema for any new columns generated by the batch transform. For each column, specify:

  • The column name
  • A description of what the column represents and how its values should be interpreted

  You can add new output columns, edit existing column names or descriptions, or remove columns as needed. The Batch Transform task should describe the logic used to populate these configured columns.

Enable web search grounding (optional)

The Batch Transform tool includes an optional web search grounding setting that controls whether the model is allowed to use web search results when generating transformations.

• When enabled, the model can supplement the input file data with information retrieved from the web while processing each row.
• When disabled, the transformation is performed strictly using the contents of the input file, the instructions defined in the task, and any context explicitly provided to the agent.

Running Batch Transform

When you run or debug the agent, the Batch Transform tool executes as part of the agent run:

• The input file is passed into the tool at runtime.
• The tool processes the file row by row.
• A transformed output file is generated.
• The output file is returned as part of the agent output.

During execution, Batch Transform appears in the Execution Trace as a dedicated tool call. You can expand this step to inspect detailed runtime information.

Inspecting execution details

From the execution trace, you can review details surfaced in the tool call output and, when applicable, the agent output:

• Inputs - The input file used by the tool, including file name, type, and metadata (visible in the tool call output).
• Outputs - The generated output file, including file ID, file name, and MIME type (shown in the tool call output when a file output is defined).
• Prompt context - The system and user prompts used during the agent run, which help explain how the transformation task was executed.

You can download both the input and output files directly from the execution trace for validation or troubleshooting.

When a file output is defined, the final agent output typically includes a confirmation message indicating that the transformed file was generated and providing the output file name.

Evaluating batch transformations

Evaluations allow you to measure the quality and correctness of batch‑processed outputs. In addition to evaluating results at the file level, agents support line‑by‑line evaluation, which is especially useful for structured outputs like CSV files.

Line‑by‑line evaluation

Line-by-line evaluation evaluates each row in an output file independently instead of evaluating the file as a single unit. This provides granular visibility into how individual records perform against your evaluation criteria. This mode is particularly useful when:

• Each row represents an independent decision or classification.
• You need granular pass/fail metrics across large files.
• You want to drill down into individual failures.

Configuring line‑by‑line evaluation

Line‑by‑line evaluation is configured in the evaluation set settings:

1. Enable line‑by‑line evaluation in the evaluation set configuration.
2. Select the output file to evaluate. This is required when an agent produces multiple output files.
3. Specify the file type (for example, CSV) that the evaluator should operate on.

Once configured, evaluations will be performed on each row of the selected output file.

CSV Column Exact Match evaluator

To support structured file evaluation, a deterministic evaluator called CSV Column Exact Match Evaluator is available. For details, refer to Agent evaluations.

This evaluator:

• Compares one or more specified columns between expected and actual outputs
• Performs an exact string match
• Returns pass/fail results per row

CSV Column Exact Match Evaluator is well suited for validating categorical outputs such as labels, match types, or status fields.

Running and reviewing evaluations

After configuring the evaluation set:

1. Create an evaluation run using an input file and the corresponding Batch Transform output file.
2. Schedule or run the evaluation.
3. Review results at two levels:
   • File‑level summary, showing how many rows passed or failed overall.
   • Line‑level drill‑down, showing pass/fail status, values, and metadata for each individual row.

For example, an evaluation might show that 141 out of 199 rows passed an exact match check on a specific column. From there, you can drill down to inspect individual failed rows, compare expected versus actual values, and review execution details such as per‑row latency.

Line‑by‑line evaluation provides:

• Clear visibility into which records succeeded or failed.
• Faster debugging of transformation logic.
• Quantitative metrics to track improvements over time.