← Articles

A2A Renames "Blocking" to "Polling": Why Terminology Matters in Protocol Design

A2A Spec Breaking Change February 23, 2026 · ishymko · View proposal →

About the Proposal

This proposal from ishymko addresses a naming inconsistency in A2A V1.0. The blocking parameter doesn't actually cause the server to block — it tells the client to poll for updates. Post-V1.0 cleanup is focusing on these kinds of developer experience improvements.

The Problem

A2A's SendMessage operation accepts a blocking parameter. When you read "blocking=true," you'd reasonably assume the server holds the connection open until the task completes. That's how blocking I/O typically works.

But that's not what happens. Setting blocking=true tells the client to poll the task status endpoint until completion. The server returns immediately; the blocking happens client-side.

"The current name is actively misleading. Every developer who implements this will have to read the docs twice to understand why their 'blocking' call returns immediately." — Issue discussion

The Change

Before (V1.0)

blocking: true

Confusing — implies server-side blocking

After (Proposed)

polling: true

Clear — describes actual behavior

The new name accurately describes what happens: when polling=true, the client polls until completion. No ambiguity.

Why This Is a Breaking Change

Renaming a parameter in a protocol spec is inherently breaking. Implementations built against V1.0 use blocking; those parameters will need to change.

However, the A2A team is addressing this early in the V1.x cycle for good reasons:

Adoption is still early: Fixing terminology now affects fewer implementations than waiting
Documentation clarity: Every explanation of blocking requires a "note: this doesn't actually block" caveat
Future extensibility: If A2A ever adds true server-side blocking (long-polling, SSE), the name blocking would be needed for that semantically correct use

Migration Path

The proposal includes a graceful migration strategy:

// Servers SHOULD accept both during transition period
{
  "blocking": true,  // Deprecated, still works
  "polling": true    // Preferred
}

// If both present, polling takes precedence

This allows existing implementations to continue working while new code uses the clearer terminology.

The Broader Pattern

Post-1.0 specs often go through a terminology cleanup phase. The initial rush to ship prioritizes functionality; the refinement phase prioritizes developer experience. A2A is now in that refinement phase.

Related cleanup efforts in recent weeks include:

Correcting Part discriminator values in documentation
Fixing example code in "life-of-a-task" guides
Adding "What's New in V1" documentation
Combining duplicate config types (TaskPushNotificationConfig and PushNotificationConfig)

None of these are glamorous. All of them matter for adoption.

What's Next

The proposal is open for community feedback. If accepted, expect:

Spec update in V1.1 or a minor revision
SDK updates with deprecation warnings for blocking
Documentation refresh
A transition period (likely 6-12 months) before blocking is removed entirely

Small naming changes ripple through an ecosystem. Getting them right early pays dividends.