Uploading inputs
Upload files up front for the agent to work against, then list or download them.Getting inputs in front of an agent
Files travel outward by default. Uploading puts bytes in org storage; it does not put them in the agent’s computer, and a session takes nofiles[] — there is no create-time mount. What crosses the other way is the agent’s own fetch_file call: upload the input, name its fil_ id in the session’s first message, and the agent writes it into its own workspace when it needs the bytes. For anything small, put the content in the first message itself; for anything on the open web, let the agent fetch it with web_fetch or bash.
CLI
publish_file → in Files, durably.
Two kinds of storage
Scratch work belongs in the sandbox. Anything the agent should hand back belongs in Files.
Publishing an artifact
The built-inpublish_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.
path and returns the new published file’s id, name and size so the id can flow into a structured output or webhook. The file keeps the session_id as provenance but does not die with the session.
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.string
MIME type; the library’s
kind (image, video, audio, document, other) is derived from it.string
A human title for the asset library.
string[]
Labels to find it by later with
find_files.Name collisions
Names in Files are not unique keys — every publish creates a distinct file object with its own id, and a repeatedname is stored as-is, so both remain listed. Key off the returned id, not the display name.
Finding assets again
Everything in Files is also the organization’s asset library: every file carries akind, a source (who wrote it — an upload, a URL import, an image or video generation, a clip, a screenshot, a speech generation), optional title, description and tags, and an image’s pixel dimensions. An agent retrieves earlier assets with the built-in find_files tool:
fil_ id on, or the same filters drive vetta file list --kind --tag --search and client.files.list(). Bring an asset in from the web with vetta file import <url> (the API fetches it server-side, so private and local addresses are refused), and describe any file after the fact with vetta file update. See Files.
Bringing an asset back into the sandbox
find_files stops at the id, and so does every generator — a generate_video
render is saved from the provider straight to storage and never lands on the computer’s disk. The
built-in fetch_file tool is the inverse of publish_file: it writes files the organization
already holds into the session’s sandbox, by id, so the agent can work on the bytes.
publish_file the result as a new file. Up to eight ids a call and 64 MiB a file,
resolved against your organization’s library and nobody else’s; a session with no computer is
refused by name. See Tools.
Reading a session’s outputs
CLI
Next: tools & plugins
The extension point every capability plugs into.