files/v1
The A2A extension that carries each file's path, version, size, and hash on the artifact a task wrote.
URI: https://docs.nylorun.com/a2a/files/v1
{
"artifactUpdate": {
"taskId": "t1.…",
"contextId": "ticket-4821",
"artifact": {
"artifactId": "af_01m663pz…:deepwiki-portal.zip",
"name": "deepwiki-portal.zip",
"parts": [
{
"url": "https://runtime.example.com/v1/a2a/files/af_01m663pz…/versions/2",
"mediaType": "application/zip",
"filename": "deepwiki-portal.zip"
}
],
"extensions": ["https://docs.nylorun.com/a2a/files/v1"],
"metadata": {
"https://docs.nylorun.com/a2a/files/v1": {
"kind": "file",
"path": "deepwiki-portal.zip",
"version": 2,
"size": 2394141,
"sha256": "a561e811…"
}
}
},
"append": false,
"lastChunk": true
}
}Each artifact the turn writes, or adds a version to,
becomes an A2A artifact with this extension: by push as an artifactUpdate,
and in the task's artifacts from GetTask, which lists the latest version of
each. Files the caller sent in are not listed. The turn's answer is a separate
artifact, output, without this extension.
The artifact's part is a url:
GET /v1/a2a/files/{artifactId}/versions/{version}
on the Runtime's public URL. It serves the version's bytes, with Range, or a
folder's version as a zip. Only the subject whose session wrote it may read it:
fetch it with the same key, Nylorun-Subject, and Nylorun-Scopes you called
the Agent with. Another subject gets 404.
| Field | Type | Meaning |
|---|---|---|
kind | file or folder | A file, or a folder served as its zip. |
path | string | The artifact's name, such as the path the agent saved it under. The same across versions. |
version | number | The version. A later write to the same artifact is a higher version. |
size | number | Bytes of the version. |
sha256 | string | The SHA-256 of the content, in hex. Two versions with the same hash have the same content. |
fileCount | number, folders only | The files in the folder's version. |
Index files by path and version. The same artifact can arrive more than
once, by push and by GetTask; the same path, version, and sha256 is the
same file.
Files into a task
A message can carry files as raw parts or as url parts. The Runtime fetches
a url part itself, within the Runtime limit inlineFileBytes (20 MiB by
default) and 60 seconds, and stores it like a raw part. It fetches only from
hosts a push may reach: a private, loopback, or link-local address is refused
unless the operator allows it (see Allowed hosts).
A URL that is refused or does not answer 2xx refuses the message. See
Files in AG-UI and A2A messages.