File part (A2A)

A file part is an A2A Part that carries a file, either inline as base64-encoded bytes in the raw member or by reference as a link in the url member.

Two forms. A part holds exactly one content member, so a file part uses raw or url, never both. Both forms can add filename and mediaType. Based on the specification’s file exchange example, which sends an image inline and receives a processed image by link (bytes shortened):

[
  {"raw": "iVBORw0KGgoAAAANSUhEUgAAAAUA", "filename": "input_image.png", "mediaType": "image/png"},
  {"url": "https://storage.example.com/processed/task-bbb/output.png?token=xyz", "filename": "output.png", "mediaType": "image/png"}
]

In JSON, raw is a standard base64 string, the ProtoJSON encoding of protobuf bytes. Base64 turns every 3 bytes into 4 characters, so inline files grow by about a third and count against whatever request size limit the server sets.

Choosing a form. Inline bytes suit small files and avoid a second fetch. A URL suits large files and outputs the agent stores elsewhere, and it can point to a short-lived signed link, as in the example above. A URL also means the receiver must fetch content from an address the other party chose.

Security. Section 14.1.1 of the specification requires file references in A2A messages to be validated to prevent server-side request forgery (SSRF). Its webhook guidance in section 13.2 shows what that looks like: reject private IP ranges, localhost and link-local addresses, and use allowlists where they fit. Files from another agent are untrusted input, so the receiver should also check that the content matches the declared mediaType.

What changed from v0.3. Version 0.3 wrapped file content in a file object with "kind": "file" and used name, mimeType, and either bytes or uri. Version 1.0 flattens this into the part itself as raw or url, filename and mediaType. The specification’s migration appendix shows the legacy inline field as fileWithBytes, but the v0.3.0 schema names it bytes.

Neighbouring terms. Text parts carry prose and data parts carry JSON. An artifact’s parts hold a task’s outputs, often files.