Files
Upload files, send them in a message, export a session's outputs, and read large tool results.
const uploaded = await client.artifacts.upload(fileBytes, {
name: "brief.pdf",
sessionId: session.id,
contentType: "application/pdf",
});
await session.inputParts(
[
{ type: "text", text: "Summarise this brief." },
{ type: "file", artifactId: uploaded.artifact.artifactId },
],
{ idempotencyKey },
);Any file may be sent, within the Tenant's artifact limits at upload. A message
has at most messageParts (32) parts, a Runtime limit. The
agent's harness decides how its model sees each file; see
What the model reads.
API
| Method | Role |
|---|---|
upload(body, { name, sessionId?, contentType?, labels? }) | Create an artifact. |
uploadVersion(id, body) | Add a version. |
list({ sessionId? }) | List artifacts, oldest first. |
page({ sessionId?, kind?, labels?, limit?, cursor? }) | Page artifact metadata, newest first. limit defaults to 50, at most 200. |
get(id) | Metadata and versions. |
download(id, { version?, range? }) | Bytes through the Runtime. |
link(id, { expiresIn? }) | Credential-free URL, 5 to 15 minutes. |
tree(id) / file(id, path) | Folder contents. |
diff(id, { version?, from? }) | Versions of a folder. |
zip(id) | Download a folder as a zip. |
delete(id) | Remove the artifact. |
Routes and schemas are on the Runtime API.
Each artifact names its owner: sessionId for a session's, agentId for the
folder that holds an Agent's
disk versions, and neither for one your app
uploaded without a session. A disk-version artifact changes only through the
Agent's snapshot and versions calls.
What the model reads
Every model reads text. It also reads image, pdf, office, audio, or
video when its catalog says so or the operator adds the input; the model's
inputs list says which. See Inputs.
Our harness decides how each file of the turn reaches the model:
| File | What the model gets |
|---|---|
| A type the model reads | The file itself, in its API's own block (below). |
| A text file | Its text, inlined as a <file> block. |
| Anything else | A note in its place: (File "name", type, is not shown: <why>.), such as a type no model reads, a type this model does not read, or a file larger than modelFileBytes (8 MiB). |
The Runtime converts and resizes nothing. A file the model reads goes in its API's own block:
| File | How it reaches the model |
|---|---|
| Image | An image input (PNG, JPEG, GIF, or WebP), on every API |
Anthropic document, OpenAI Responses input_file, OpenAI-compatible completions file part, or Google inlineData | |
| Office document | OpenAI Responses input_file |
| Audio | Completions input_audio (WAV and MP3 only), or Google inlineData |
| Video | Completions video_url, or Google inlineData |
The Model Gate only fetches and translates. A part the model or its API cannot
take fails the model call with unsupported_input, and a file it cannot fetch
(not the session's, missing, or past modelFileBytes) or a request the API
cannot carry, such as audio other than WAV or MP3 on completions, with
invalid_request, before anything is sent. Neither is retried. Our harness
sends only the types the model reads, so unsupported_input reaches a
custom harness that sends parts as they are. The bytes
are only in the provider request, never in the reported call or the
transcript.
After its turn
The model gets a file's bytes only in the turn that brought it. Later turns show a reference line in its place:
[Uploaded artifact "name" · <artifactId> v<n> · read_artifact to view]The model reads the file again with read_artifact, a tool our harness gives
every agent it runs (a custom harness offers its own). It takes the
artifactId and a version (default the latest). A file the model reads is
shown to it; a text file returns in pages; any other file fails with
artifact.unsupported. With a sandbox, it also takes path, which copies the
whole artifact into the sandbox for a command to use.
Files in AG-UI and A2A messages
The AG-UI and A2A endpoints take files inside the message.
The endpoints name an Agent by its id.
- AG-UI. A user message's image, audio, video, and document parts are
files. Bytes sent inline (a
datasource) are stored as an artifact of the thread's session. Afilesource with providernylorunnames an artifact the caller may read. A thread's messages give each file back as a media part whose source is{ type: "file", provider: "nylorun", value: <artifact id> }. - A2A. A message may carry
rawandurlfile parts beside its text. The Runtime fetches aurlpart itself, and stores each file the same way in the context's session. The Agent Card'sdefaultInputModesadd the media types the Tenant's model reads. The files a turn saves come back as A2A artifacts withurlparts; seefiles/v1.
| Limit | Value |
|---|---|
| One file | inlineFileBytes (20 MiB) |
| Request body | The base64 of one such file plus requestBodyBytes: about 27.7 MiB at the defaults |
| File by URL | AG-UI: refused with 400, and the Runtime fetches nothing. A2A: fetched by the Runtime within inlineFileBytes and 60 seconds, never from a private address unless it is in NYLORUN_A2A_PUSH_ALLOW_HOSTS; see files/v1. |
The message then goes through the session's usual path, and the harness
decides how the model sees each file, as for any message. When the message is
refused, the files it stored are deleted. A retried message (the same AG-UI
message id or A2A messageId) reuses the files it stored the first time.
CLI
npx nylorun artifacts upload brief.pdf --session <session-id>
npx nylorun sessions send <session-id> "Summarise this brief." --file <artifact-id>artifacts upload prints the new artifact's id; --to <id> adds a version
instead. sessions send takes --file <artifact>[@<version>] once per file.
nylorun artifacts also has list, get, download, tree, diff, zip,
link, and rm.
In Studio, attach any file to a message with the paperclip, a paste, or a drop onto the message card.
Session outputs
When the session's Agent has a sandbox (kind virtual or pod), our harness
gives the agent save_artifact, and when a turn completes, before it ends,
saves /workspace/outputs as the session's outputs folder artifact. Its
versions say source: "engine"; a turn that changed nothing adds none. The
folder holds at most folderEntries (10,000) files and 1 GiB, our harness's
outputs.maxBytes; a folder it skips or fails to save writes
artifact.export.skipped or artifact.export.failed. A custom harness saves
no outputs folder unless it writes one. Studio shows it, with the files sent
into the session, on the session's Record tab.
Files the agent makes
When the session's Agent has a sandbox, the agent reads its own files with
read. A text file returns numbered lines. An image, a PDF, or another file the
model reads, known by its extension, comes back as the file itself, so the
agent can look at a chart, a diagram, or a page it rendered:
- Shown to the model only. Our harness stores the file as an artifact with
audience: "model".get(id)returns it, butlistandpagenever do, and it is no file of an A2A task. Save a file for the person withsave_artifactor the outputs folder. - Honest failures. A model that can't read the kind fails with
sandbox.unreadablebefore anything is stored. A file that doesn't start like its type, or any other binary file, fails withsandbox.binary_file. - A cap per call. A model call carries at most the 6 newest files from tool
results as images or documents; older ones in the turn go as a note, and
read_artifactshows them again. Files a person sends are never capped.
Large tool results
Our harness stores a remote MCP or HTTP tool result over 32 KiB (as JSON) as
a file artifact of the session, with source: "engine". The tool result records
{ truncated: true, artifactId, version, contentType, size, preview }, and the
model sees the preview: the first 4 KiB and the last 1 KiB. Images, audio, and
blob resources in an MCP result become artifacts too; a model that reads images
also sees the image.
The model reads more with read_artifact { artifactId, version?, offset?, length? }, which returns up to 32 KiB of a text artifact per call, with
nextOffset while more remains. Every agent our harness runs has it, on an
Agent of any kind. It reaches the session's own artifacts and the Tenant-wide
ones the session's messages named, never another session's.
| Limit | Value |
|---|---|
| Result shown inline | 32 KiB |
| Preview of a stored result | First 4 KiB and last 1 KiB |
| Results of one model step | 256 KiB shared; past it, a result over 1 KiB is a stub naming its artifact |
read_artifact per call | 32 KiB |
| MCP or HTTP answer | toolAnswerBytes (8 MiB); a larger one fails with mcp.too-large (http.too-large for an HTTP tool) |
Stored results are ordinary artifacts of the session: list({ sessionId })
lists them, download(id) returns the whole result, and they count toward the
Tenant's artifact limits. When an artifact cannot be stored, for example because
those limits are reached, the preview stays and dropped says why the rest is
gone. A stored structured result is not checked against the tool's output
schema.