feat(server): expose `request_handler=` on `create_a2a_server()`

[numarasSigmaSoftware]

---

create_a2a_server() constructs DefaultRequestHandler internally and offers no way to supply a different one, so an adopter with an existing a2a.server.request_handlers.RequestHandler implementation cannot use the factory at all — it is all-or-nothing.

The value is already a local variable that gets threaded into the JSON-RPC routes, so exposing it is additive:

# adcp/server/a2a_server.py (6.6.0 and v7.0.0-rc, identical)
1182:        request_handler = DefaultRequestHandler(
1188:        jsonrpc_kwargs["request_handler"] = request_handler
1227:        request_handler = DefaultRequestHandler(   # v0.3 compat branch
1233:        jsonrpc_kwargs["request_handler"] = request_handler

Proposed change — add a keyword-only parameter, default None, preserving today's behavior:

def create_a2a_server(
    handler: ADCPHandler[Any],
    *,
    ...,
    request_handler: RequestHandler | None = None,
) -> Any:

When supplied, use it for both the 1.0 and v0.3 compat branches instead of constructing DefaultRequestHandler. When None, behavior is unchanged.

Why it matters. task_store= and push_config_store= already let adopters own persistence, but some request-level semantics live in the handler rather than the store — most visibly tasks/cancel, which DefaultRequestHandler resolves against its in-process active-task registry and therefore cannot cancel a task issued by a previous process or a sibling worker. Multi-worker deployments cannot express durable cancel through any currently-exposed seam.

Concretely, this blocks incremental adoption. We maintain a seller agent with a mature RequestHandler implementation and would like to adopt the SDK's executor, middleware chain, error translation, and validation while keeping our request-handler layer during migration. Today the only options are "adopt everything" or "adopt nothing"; this kwarg makes a staged migration possible.

Compatibility: additive, keyword-only, default preserves current behavior.

We are happy to open the PR if the direction is acceptable.

[bokelley]

Thanks for filing!

Triage

Classification: Feature request
Bucket(s): handlers
Status: ready-to-implement

What the experts said:

• code-reviewer: Supports the feature; two blockers — task_store/push_config_store would be silently discarded with no diagnostic, and serve.py call sites must also be updated (the feature is unreachable via the primary serve() entrypoint otherwise).
• dx-expert: Supports the feature; flags that executor-construction params (middleware=, validation=) are disconnected from any pre-built custom handler, recommends a create_a2a_executor() helper to make the stated staged-migration goal achievable, and notes that multi-worker cancellation is already solvable via task_store= with a durable backend — the docstring should redirect adopters there first.

My take: The escape hatch is the right call for genuine staged migration. Implementation scope is wider than the two-line change the issue proposes — serve.py, ServeConfig, type imports, local-variable renames, and a potential new executor factory all need attention alongside a2a_server.py.

• src/adcp/server/a2a_server.py — Add request_handler: RequestHandler | None = None (keyword-only); import RequestHandler under the TYPE_CHECKING guard; raise ValueError at entry when request_handler is not None and task_store or push_config_store is also supplied (they are forwarded to DefaultRequestHandler, which is bypassed); rename local request_handler = DefaultRequestHandler(...) variables in both branches (e.g. _rpc_handler) to avoid shadowing the parameter; gate InMemoryTaskStore fallback and fallback_card construction on request_handler is None; add docstring redirect: "For cross-worker task persistence and cancellation, prefer task_store= with a durable backend before reaching for request_handler=."
• src/adcp/server/serve.py — Thread request_handler= through _start_a2a_server (line 1689) and _build_mcp_and_a2a_app (line 1852); add field to ServeConfig and its A2A-only __post_init__ validation list; expose via serve().
• Consider adding create_a2a_executor() to src/adcp/server/__init__.py — A public factory that returns a configured ADCPAgentExecutor with the same defaults as create_a2a_server(). Without it, the stated "keep our handler, adopt the SDK's executor/middleware/validation" story has no clean entry point: adopters would need to know ADCPAgentExecutor's internal constructor signature to wire the executor into their custom handler at construction time.
• Tests (tests/test_a2a_server.py) — Three new cases: custom handler wired through on the static-card path; custom handler wired through on the callable-public_url path; request_handler= + task_store= raises ValueError. Non-breaking rationale: keyword-only, default None, all existing call sites unchanged.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01SjCFMtaxadkfU2tpUTkBoA

---

Generated by Claude Code