NylorunDocsBeta
RunSessions

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

MethodRole
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:

FileWhat the model gets
A type the model readsThe file itself, in its API's own block (below).
A text fileIts text, inlined as a <file> block.
Anything elseA 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:

FileHow it reaches the model
ImageAn image input (PNG, JPEG, GIF, or WebP), on every API
PDFAnthropic document, OpenAI Responses input_file, OpenAI-compatible completions file part, or Google inlineData
Office documentOpenAI Responses input_file
AudioCompletions input_audio (WAV and MP3 only), or Google inlineData
VideoCompletions 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 data source) are stored as an artifact of the thread's session. A file source with provider nylorun names 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 raw and url file parts beside its text. The Runtime fetches a url part itself, and stores each file the same way in the context's session. The Agent Card's defaultInputModes add the media types the Tenant's model reads. The files a turn saves come back as A2A artifacts with url parts; see files/v1.
LimitValue
One fileinlineFileBytes (20 MiB)
Request bodyThe base64 of one such file plus requestBodyBytes: about 27.7 MiB at the defaults
File by URLAG-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, but list and page never do, and it is no file of an A2A task. Save a file for the person with save_artifact or the outputs folder.
  • Honest failures. A model that can't read the kind fails with sandbox.unreadable before anything is stored. A file that doesn't start like its type, or any other binary file, fails with sandbox.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_artifact shows 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.

LimitValue
Result shown inline32 KiB
Preview of a stored resultFirst 4 KiB and last 1 KiB
Results of one model step256 KiB shared; past it, a result over 1 KiB is a stub naming its artifact
read_artifact per call32 KiB
MCP or HTTP answertoolAnswerBytes (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.

Next step

On this page