Files

Files is durable, organization-scoped storage: where inputs you upload and artifacts an agent chooses to keep live, independent of any single session’s lifetime. Scratch work stays in the session sandbox; anything the agent should hand back goes to Files, where it persists until you delete it.

Uploading inputs

Upload files up front for the agent to work against, then list or download them.

vetta file upload ./data/orders.csv --name orders.csv
vetta file list
vetta file download <file_id> > ./out/orders.csv

const file = await vetta.files.upload({ path: "./data/orders.csv", name: "orders.csv" });
const list = await vetta.files.list();
await vetta.files.download(file.id, "./out/orders.csv");

Getting inputs in front of an agent

Files travel outward. Uploading puts bytes in org storage; it does not put them in the agent’s computer, and a session takes no files[] — there is no create-time mount. To hand an agent an input today, put it in the session’s first message, or let the agent fetch it itself with web_fetch or bash.

CLI

vetta session create --agent Analyst \
  --message "Reconcile these orders against last month's ledger: $(cat ./data/orders.csv)"

The loop a session completes is therefore agent works → publish_file → in Files, durably.

Two kinds of storage

Where	Scope	Lifetime
Session sandbox	The session’s computer filesystem	Deleted when the session is deleted
Files API	Your organization	Persists until you delete it

Scratch work belongs in the sandbox. Anything the agent should hand back belongs in Files.

Publishing an artifact

The built-in publish_file tool promotes a file from the session sandbox into the persistent Files store. It is not the only writer: what generate_image or generate_video produces also lands here, and the session is told the new fil_ id. This is how a finished session leaves deliverables behind without a mandatory “deliver” step — the session simply goes idle and its published files remain.

# from inside the agent's reasoning, it calls:
publish_file(path="/workspace/report.pdf", name="Q3-refund-report.pdf")

The tool takes a sandbox path and returns the new persistent file object ({ id, name, size, created_at }) so the id can flow into a structured output or webhook:

string

required

Absolute path of the artifact in the session sandbox, e.g. /workspace/report.pdf.

string

The name to store it under in Files. Defaults to the basename of path.

boolean

default:"false"

How to handle a name that already exists in the org (see the collision rule below).

Name collisions

Names in Files are not unique keys — every publish creates a distinct file object with its own id. When name matches a file that already exists in the organization:

overwrite: false (default) — the new file is stored under a suffixed name (report.pdf → report-2.pdf) so nothing is clobbered and both are retrievable.
overwrite: true — the existing file’s contents are replaced in place, keeping the same id so any prior reference still resolves.

Because ids are stable and unique, consumers should key off the returned id, not the display name.

Reading a session’s outputs

CLI

vetta file list --session $SID           # session-scoped + published

Deleting a session permanently removes files it produced in the sandbox. Files promoted with publish_file or uploaded through the Files API are organization-scoped and survive. Download anything you need before deleting a session. See Session operations.

Next: tools & plugins

The extension point every capability plugs into.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Uploading inputs

Getting inputs in front of an agent

Two kinds of storage

Publishing an artifact

Name collisions

Reading a session’s outputs

Next: tools & plugins

​Uploading inputs

​Getting inputs in front of an agent

​Two kinds of storage

​Publishing an artifact

​Name collisions

​Reading a session’s outputs

Next: tools & plugins

Uploading inputs

Getting inputs in front of an agent

Two kinds of storage

Publishing an artifact

Name collisions

Reading a session’s outputs