You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
A2A can miss decisioning AdcpError and emit a text-only failure under application import graphs #1088
MCP correctly preserves the same exception as structuredContent.adcp_error.
This is reproducible in our real ASGI app with a LazyPlatformRouter, middleware, and the SDK idempotency wrapper. The server traceback ends with the exact public decisioning class:
adcp.decisioning.types.AdcpError:
AdcpError[INVALID_REQUEST / correctable]: packages.0.bad_field: Extra inputs are not permitted
but ADCPAgentExecutor.execute() reaches the generic handler at a2a_server.py:454, not _send_adcp_error().
The same behavior occurs for decisioning errors raised by our idempotency and not-found paths, so it is not specific to Pydantic or exception chaining.
Suspected cause
adcp.server.a2a_server eagerly builds _DECISIONING_ADCP_ERROR_TYPES through an optional import at module load:
Catching every exception and caching an empty tuple makes the result import-order/circular-import sensitive in a large application graph. It also hides the reason the structured type was unavailable.
Expected
Every public adcp.decisioning.AdcpError raised from a platform method should produce an A2A failed Task containing DataPart.data.adcp_error, regardless of application import order. This should have parity with MCP.
Current adopter workaround
We had to define an error inheriting both public SDK bases and use it for all platform errors:
That restores the A2A adcp_error artifact while remaining catchable by decisioning/MCP dispatch. It would be better for the SDK to remove the eager optional-import dependency (or expose one shared server-side structured-error base/marker).
Classification: Bug Bucket(s): handlers (server-side execution / A2A transport binding) Status: ready-to-implement Milestone: omitted (no target version in issue)
What the experts said:
code-reviewer: Fix B (lazy import deferred to execute() call time, except Exception → except ImportError) is non-breaking. The same except Exception over-breadth exists at two other call sites (serve.py:2745, translate.py:129); those are already call-time imports so they don't exhibit the silent-empty-tuple bug, but both should also be narrowed to ImportError for consistency. Recommends @functools.lru_cache(maxsize=None) on the helper to eliminate sys.path traversal overhead on every request when the decisioning extra is not installed.
dx-expert: Blocker-level DX friction: failure is silent at module load (no log), manifests only under real ASGI import graphs that pass unit tests, and the downgraded error gives buyers zero actionable information. The WireAdcpError workaround is not acceptable as a supported pattern — it crosses disjoint hierarchies via diamond inheritance with no docs pointing to it. Recommends a logger.warning() inside the except ImportError at call time (not at the "not installed" branch). Wants a public crosswalk note in docs distinguishing adcp.decisioning.types.AdcpError (raised by platform methods) from adcp.exceptions.ADCPError (client-side transport errors).
My take: The root cause is confirmed: the module-level try/except Exception caches _DECISIONING_ADCP_ERROR_TYPES = () for the process lifetime whenever adcp.decisioning.types fails to import at a2a_server load time (which happens under circular-import-sensitive application graphs). The fix is clear and non-breaking: defer the import to request time so all modules are fully loaded before the check runs.
Implementation scope:
src/adcp/server/a2a_server.py (primary fix): Remove module-level _DECISIONING_ADCP_ERROR_TYPES block (lines 55–60). Add a @functools.lru_cache(maxsize=None) helper _get_decisioning_adcp_error_types() → tuple[type[BaseException], ...] that imports AdcpError lazily with except ImportError (not except Exception). Call the helper inside execute() when building structured_error_types. Update the comment on lines 47–54 to accurately describe the deferred-import approach.
src/adcp/server/serve.py (~line 2745) and src/adcp/server/translate.py (~line 129): Narrow their own except Exception import guards to except ImportError; no structural change needed since these are already call-time.
Tests: Extend tests/test_a2a_structured_error.py (or add a new test) that patches adcp.decisioning.types out of sys.modules before importing a2a_server and verifies that a subsequent execute() call still routes AdcpError to _send_adcp_error(). This guards against regression to module-level eager import.
Required checks before PR:pytest tests/ (relevant subset), mypy src/, ruff check ., black --check .
Non-breaking rationale: Changes only the import timing (call-time vs. module-load-time) and the except-clause breadth — no public symbols removed, no signatures changed, no default values altered. The observable behavior change is that AdcpError is now correctly routed to _send_adcp_error(), which is the documented and intended behavior.
Activity
bokelley commentedon Aug 25, 2026
Triage
Classification: Bug
Bucket(s): handlers (server-side execution / A2A transport binding)
Status: ready-to-implement
Milestone: omitted (no target version in issue)
What the experts said:
execute()call time,except Exception→except ImportError) is non-breaking. The sameexcept Exceptionover-breadth exists at two other call sites (serve.py:2745,translate.py:129); those are already call-time imports so they don't exhibit the silent-empty-tuple bug, but both should also be narrowed toImportErrorfor consistency. Recommends@functools.lru_cache(maxsize=None)on the helper to eliminate sys.path traversal overhead on every request when the decisioning extra is not installed.WireAdcpErrorworkaround is not acceptable as a supported pattern — it crosses disjoint hierarchies via diamond inheritance with no docs pointing to it. Recommends alogger.warning()inside theexcept ImportErrorat call time (not at the "not installed" branch). Wants a public crosswalk note in docs distinguishingadcp.decisioning.types.AdcpError(raised by platform methods) fromadcp.exceptions.ADCPError(client-side transport errors).My take: The root cause is confirmed: the module-level
try/except Exceptioncaches_DECISIONING_ADCP_ERROR_TYPES = ()for the process lifetime wheneveradcp.decisioning.typesfails to import ata2a_serverload time (which happens under circular-import-sensitive application graphs). The fix is clear and non-breaking: defer the import to request time so all modules are fully loaded before the check runs.Implementation scope:
src/adcp/server/a2a_server.py(primary fix): Remove module-level_DECISIONING_ADCP_ERROR_TYPESblock (lines 55–60). Add a@functools.lru_cache(maxsize=None)helper_get_decisioning_adcp_error_types() → tuple[type[BaseException], ...]that importsAdcpErrorlazily withexcept ImportError(notexcept Exception). Call the helper insideexecute()when buildingstructured_error_types. Update the comment on lines 47–54 to accurately describe the deferred-import approach.src/adcp/server/serve.py(~line 2745) andsrc/adcp/server/translate.py(~line 129): Narrow their ownexcept Exceptionimport guards toexcept ImportError; no structural change needed since these are already call-time.tests/test_a2a_structured_error.py(or add a new test) that patchesadcp.decisioning.typesout ofsys.modulesbefore importinga2a_serverand verifies that a subsequentexecute()call still routesAdcpErrorto_send_adcp_error(). This guards against regression to module-level eager import.pytest tests/(relevant subset),mypy src/,ruff check .,black --check .AdcpErroris now correctly routed to_send_adcp_error(), which is the documented and intended behavior.Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}
Generated by Claude Code