Type-clean EventQueue successor: abstract base makes EventQueue() unusable for mypy users

[bokelley]

Problem

PR #944 split EventQueue into an abstract base + concrete EventQueueLegacy, with EventQueue.__new__ redirecting EventQueue(...) to EventQueueLegacy(...) at runtime for backwards compatibility. The docstring of EventQueue shows queue = EventQueue() as typical usage.

However, mypy correctly flags this pattern as an error because EventQueue is declared abstract via ABC + @abstractmethod on enqueue_event:

error: Cannot instantiate abstract class "EventQueue" with abstract attribute "enqueue_event"  [abstract]
error: "EventQueue" has no attribute "dequeue_event"; maybe "enqueue_event"?  [attr-defined]

The methods dequeue_event, tap, close, task_done, is_closed only exist on EventQueueLegacy, not on the abstract EventQueue interface.

Result: downstream type-checked codebases (we ship a Python SDK that strict-mode-mypys every commit across 3.10–3.13) must keep importing EventQueueLegacy explicitly — the class name advertises its own deprecation, but it remains the only typeable option in a2a-sdk 1.0.1.

a2a-sdk 1.0.1 internal usage

Even a2a-sdk's own modules never instantiate EventQueue() — they all use EventQueueLegacy():

• a2a/server/events/in_memory_queue_manager.py: queue = EventQueueLegacy()
• a2a/server/events/queue_manager.py: typed as EventQueueLegacy
• a2a/server/events/event_consumer.py: typed as EventQueueLegacy
• a2a/server/request_handlers/default_request_handler.py: queue = EventQueueLegacy()

Only the docstring of EventQueue itself shows queue = EventQueue().

Requested

One of:

1. Promote EventQueue to a concrete (non-abstract) class that owns the full method surface (dequeue_event, tap, close, task_done, is_closed), making EventQueueLegacy a thin alias for the deprecation window.
2. Add a DefaultEventQueue (or similar) concrete class that downstream users can import and instantiate without the *Legacy name, with the same method surface as EventQueueLegacy.
3. Document that EventQueueLegacy is the supported instantiation surface for the foreseeable future and update the EventQueue docstring's queue = EventQueue() example accordingly so users (and type-checkers) aren't misled.

We don't have a preference on which path — any of the three unblocks the rename downstream.

Downstream tracking

adcontextprotocol/adcp-client-python#699 (left a TODO in our harness pointing at this issue).

[ishymko]

Hi @bokelley, thanks for reporting!

EventQueueLegacy with a full interface is now only used by the legacy machinery (LegacyRequestHandler and other places used by this handler you mentioned in the issue) which will be removed in the next major release. The new interface was limited to the enqueue_event as it's the only method which should be used by the AgentExecutor implementations (previously it had access to other methods, but using them there was mostly undefined behavior).

This was an oversight to keep this __new__ hack and removing it at this point will be a breaking change unfortunately, I'll fix the docstring and will add a warning when the hack path is taken.

In 1.0 EventQueue is a public interface which only has enqueue_event, internal implementations which expose more methods are not meant to be extension points in 1.0. Based on the fact that you need to instantiate an EventQueue I assume that you're using your agent executor outside of the SDK flow (not via a request handler). In this case the best way is to create your own implementation which covers your use-case.

[bokelley]

Thanks for the quick response @ishymko, that's clarifying. To close the loop on my end:

On our specific path — our pain came in transitively via the @adcontextprotocol/adcp-client-python library (we ship a sales agent built on it). The adcp library shipped its own migration off EventQueueLegacy in 5.5.0, so our downstream type-checked surface no longer trips on this. Not blocking us.

On the broader design point — your distinction between the public EventQueue interface (just enqueue_event for AgentExecutor implementations) and the legacy machinery makes sense, and I respect not wanting to introduce a breaking change to remove the __new__ hack. The docstring fix + runtime warning you mentioned would resolve the user-facing trap — the example queue = EventQueue() is what led me here, and replacing it with the explicit EventQueueLegacy() (or guidance to write a custom implementation) is the high-value piece.

One small suggestion for the docstring update if helpful: alongside the example fix, a short paragraph in the EventQueue class docstring stating "implementations needing dequeue_event / tap / close are outside the public SDK surface — write your own concrete subclass or use EventQueueLegacy directly" would short-circuit the same investigation for the next adopter who hits this.

Happy to close this once you have the docstring/warning PR up, or close now if you prefer to track the docstring change separately.