DataZen Documentation
DataZen User Guide

Send a File to an Agent

DataZen pipelines can send files or file references to an AI agent with CALL AGENT. The best technique depends on the file size, the agent’s API, and the file-input features supported by that agent.

File support varies by agent and model. Confirm which options, MIME types, file sizes, and URL-access requirements are supported by the target agent before choosing a technique.

Available Techniques

FILE_DATA and FILE_NAME

Use FILE_DATA to send file content directly in the agent request, and FILE_NAME to provide the corresponding file name when the agent supports these options. This approach avoids external storage, but increases the request size and is best suited to files within the target agent’s inline upload limits.

FILE_DATA normally requires Base64-encoded content with a leading data-URL decorator in this format: 

data:<mime-type>;base64,<base64-data>

For example, PDF content begins with data:application/pdf;base64,, while a PNG image begins with data:image/png;base64,. The decorator must appear immediately before the Base64 data.

Use the #tobase64() or @tobase64() DataZen function to transform a byte array into Base64 output. See DataZen Functions.

FILE_URL

Use FILE_URL when the agent supports retrieving a file from a URL. The URL must be reachable by the agent and must meet its authentication, expiration, and content-type requirements. This option keeps the file content out of the agent request while still using a dedicated file parameter.

File Link in the Prompt

When a dedicated file option is unavailable or behaves differently across agents, include a link to the file directly in the prompt and instruct the agent to retrieve and process it. DataZen can implement this with the file-based Claim Check pattern:

  1. Write the pipeline data to cloud storage or a shared drive with SINK INTO DRIVE.
  2. Use REPLACE to return the generated file location to the pipeline.
  3. Place that location in the agent prompt.
  4. Optionally use AUTO_DELETE to remove temporary files when the pipeline completes.

See Implement Claim Check Patterns: File-Based Claim Check for an end-to-end example.

Choosing an Approach

  • Use FILE_DATA + FILE_NAME for supported agents and reasonably sized files that can be sent inline.
  • Use FILE_URL when the agent supports URL-based file input and can access the file location.
  • Use a file link in the prompt when a cloud storage or shared drive location is available and the agent can retrieve files itself.

Because file capabilities and limits differ among agents, the file-based Claim Check pattern can be easier to implement when you have a cloud environment or shared drive available. It keeps large payloads outside the agent request and gives the prompt a simple reference to the data.

Related Topics