Batch Transform

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

Data sources

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

For details, refer to Best practices for DeepRAG and Batch Transform: JIT vs. index-based strategies.

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.

  Note:

  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.

Note:

Batch Transform with Web Search requires an LLM configuration for Gemini models.

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.