File Write (FILE_WRITE)

Writes content to a file in a folder on the agent server, in AWS S3 or in Azure Blob Storage. 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

Content (in_content)

Input

The content to write. It is the whole output of the previous module

Result (out_result)

Output

A short JSON report of the write (see Result)

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port to let the agent write files itself

Properties

Field Required Meaning

Default Filename (filename)

No

The file to write, with its extension, when nothing else names one. A file name from the agent, or a field filename from the previous module, wins. Leave it empty when the name always comes from there (see Writing a different file per run)

File Type (fileType)

No

For example text/plain. Empty → guessed from the file extension. It is stored with the module but does not change what is written

Description (tool use) (description)

No

Only used when an agent uses the module as a tool. Say what writing here means, for example "the outbox the team picks up". 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

Write Mode (writeMode)

No

What happens when the file already exists. OVERWRITE replaces it. APPEND adds the new text at the end, for example for a log. FAIL_IF_EXISTS stops with an error, so nothing is ever replaced. Empty → OVERWRITE

Allow empty content (allowEmptyContent)

No

Off (default): the step fails when there is no content, so an empty file is never written by mistake. On: an empty file is written instead

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 file name is not checked when you save, because the name may arrive at run time. If no name arrives, the step fails with a message that names the three ways to supply one.

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. Folders that do not exist are created. The agent never writes 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 and write 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 reports/. 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 write to. It must already exist

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

Writing a different file per run

By default the incoming text is the content, and the Default Filename is the target. A File Write inside an Iterator therefore writes the same file every time, and you keep only the last item (with OVERWRITE).

To change the target, send the module a JSON object, for example from a Template:

{ "filename": "chunk-3.txt", "content": "…the text to write…" }

Either key may be left out. Without filename, the Default Filename is used. Without content, the content is empty, which is then refused unless Allow empty content is on.

What arrives What is written

Plain text

The text, as UTF-8, to the Default Filename

{"encoding": "base64", "data": "…"}

The decoded bytes, as a binary file. This is what File Read passes on for binary files

{"filename": "…", "content": "…"}

The content to the file named in filename. If content is itself JSON, its text is written

A JSON object with neither filename nor content

The text of the object, unchanged

Watch out: a JSON object that has a field called content or filename is always read as this envelope, even if you meant to write it as it is.

The file name is checked. Folder separators (/ and \) and .. are refused, because the name often comes from a model. Folders come from Base Path, S3 Prefix or Blob Prefix. If you leave Default Filename empty, this cannot be checked when you save the pipeline, because the designer cannot know what an earlier module will send.

Result

As a step, the Result port sends a JSON object: success, path (where the file went), bytesWritten, storageType, writeMode and filenameFromEnvelope (true when the name came from the previous module).

As a tool

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

Argument Required Meaning

content

Yes

The text to write. A tool call has no earlier module to take it from

filename

Only if Default Filename is empty

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

You do not write the tool text. It is made from the settings: where the file goes, which file, whether it is replaced or added to, and which arguments are optional. The Description (tool use) is added at the end. Use it to say what the file means, for example "the outbox the team picks up". The agent gets the result as values: success, path, bytesWritten, storageType and writeMode.

Choose the Write Mode with care. An agent can call the tool several times in one answer. With OVERWRITE, a second call with the same file name replaces the first. Either tell the agent to use a different name each time, or use FAIL_IF_EXISTS, so a clash shows up as an error.

Use cases

  • Scheduled report: Scheduler → SQL Database → Agent → File Write puts a Markdown report into S3.

  • As a tool: the agent decides when a result is worth saving, and under which name.

  • A result for people or other systems to pick up.

  • Audit trail: write each run to a file with its own name.

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 Write 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 anything you need to keep.

  • APPEND is a real append only on the local file area. S3 objects and Azure blobs cannot be extended. There, the module downloads the old file, adds the new text and uploads everything again. This is slow for big files, and two writes at the same time can lose data. For many small outputs, a different file name per item is better than appending in a loop.

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