File Read (FILE_READ)

Reads a file from a folder on the agent server, from AWS S3 or from Azure Blob Storage, and passes its content on. Use it as a step, or connect it to an Agent’s Tools port.

Category: Files · Deployed: yes · Tool-capable: yes

Ports

Port Kind Purpose

Trigger (in_trigger)

Input

Starts the read. What arrives here is not used. It is not the file name

Content (out_content)

Output

The content of the file (see Result)

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port to let the agent read the file itself

Properties

Field Required Meaning

Default Filename (filename)

As a step: yes. As a tool: no

The file to read, with its extension. As a step, the name can only come from here. The previous module cannot send one. As a tool, the file name the agent gives wins. Leave it empty when the agent should always name the file itself

File Type (fileType)

No

For example text/plain or application/json. It decides if the content is passed on as text or as encoded binary data. Empty → guessed from the file extension (see Result)

Description (tool use) (description)

No

Only used when an agent uses the module as a tool. Say what the file means, for example "the current price list". It is not used as a step

Storage Type

Yes

Local Filesystem, AWS S3 or Azure Blob Storage. Choose it first. The fields below appear after you choose

If Storage Type is empty, or a required field of the chosen storage is empty, the pipeline cannot be assigned to an agent, and the designer lists the missing field. If a saved pipeline is deployed anyway, the module is left out. A missing Default Filename is not checked when you save. It is an error only when the module runs.

Local Filesystem

Field Required Meaning

Base Path (local.basePath)

No

A folder inside the agent’s own file area, for example reports/2026. Empty → the file area itself. The agent never reads outside this area. A path such as /data is placed inside it, and a path with .. that leads out of it is refused. The file name is added automatically

AWS S3

Field Required Meaning

Access Key ID (aws.accessKey)

Yes

The access key ID of an AWS user that may read this bucket

Secret Access Key (aws.secretKey)

Yes

The secret key of that access key. The field is hidden like a password

Bucket Name (aws.bucketName)

Yes

The S3 bucket

Region (aws.region)

No

For example eu-central-1. Empty → us-east-1

S3 Prefix (aws.s3Prefix)

No

A folder in the bucket, for example uploads/. It is put in front of the file name, so end it with / if it is a folder

Azure Blob Storage

Field Required Meaning

Connection String (azure.connectionString)

Yes

The connection string of the storage account, from the Azure portal. The field is hidden like a password

Container Name (azure.containerName)

Yes

The container to read from

Account Name (azure.accountName)

No

Usually leave it empty. The connection string already holds the account

Blob Prefix (azure.blobPrefix)

No

A folder in the container, for example reports/. It is put in front of the file name, so end it with / if it is a folder

Result

  • Text files are passed on as plain text. A file counts as text when its type is text/…, or application/json, application/xml, application/javascript or application/x-yaml.

  • All other files are passed on as a JSON object: {"encoding": "base64", "data": "…", "filename": "…", "fileType": "…"}. File Write understands this object and writes the original file again.

  • File Type empty: the type is guessed from the extension. Known are txt, csv, json, xml, html, htm, md, yaml, yml, log, js, css, png, jpg, jpeg, gif, pdf, zip and gz. A file with any other extension, or none, is passed on as binary data. Set File Type if you want such a file read as text.

  • A missing file, wrong credentials or an unreachable storage make the step fail with a message that names the file and the storage.

As a tool

Connected to an Agent’s Tools port, the module becomes a function the agent can call. Its name is file_read_ plus the Default Filename (letters and digits only, at most 40 characters). It has one optional argument:

Argument Required Meaning

filename

Only if Default Filename is empty

The file to read. A plain name, no folder separators. Empty → the Default Filename

So the agent can call it with no arguments to read a fixed document. With an empty Default Filename the agent must name the file and can pick any file of the chosen folder, bucket prefix or container.

You do not write the tool text. It is made from the settings: where the file is, which file, and how text and binary files come back. The Description (tool use) is added at the end. Use it to say what the file means, for example "the current price list". Without it, the agent knows how to call the tool but not why.

The agent gets the result as values: success, path, fileType and the content. For a binary file, the content is encoded and encoding is base64.

Use cases

  • Ingestion chain: File Read → Text Splitter → Iterator → Embedding.

  • A prompt text from S3: Storage Type AWS S3, Default Filename system-prompt.txt, started by a Scheduler. The text can be changed without touching the pipeline.

  • Reference data: Default Filename product-catalog.csv, Content wired to an Agent that answers product questions.

  • As a tool: the agent reads a document when the conversation needs it.

Notes

  • Local Filesystem means the agent server’s own file area, not your computer. It works with Docker only (see below).

  • On Kubernetes, a pipeline with a File Read that uses Local Filesystem is refused by the agent server. Use AWS S3 or Azure Blob Storage there.

  • Files in the local file area do not survive a stop of the agent. Stopping an agent in this app removes its container, and the file area is not stored on a volume. Use S3 or Azure for files you need to keep.

  • The module reads the whole file into memory. Very large files make the agent slow. Split big data into smaller files.

  • The secret fields are not part of an export. Access Key ID is, but the Secret Access Key and the Azure Connection String are left out. Enter them again after an import.