A2A can miss decisioning AdcpError and emit a text-only failure under application import graphs

[bokelley]

Version

adcp==8.0.0b9

Problem

The A2A executor can route an adcp.decisioning.types.AdcpError through its generic except Exception branch and emit only:

{"kind":"text","text":"Skill execution failed: update_media_buy"}

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:

try:
    from adcp.decisioning.types import AdcpError as _DecisioningAdcpError
except Exception:
    _DECISIONING_ADCP_ERROR_TYPES = ()

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:

from adcp.decisioning import AdcpError as DecisioningAdcpError
from adcp.exceptions import ADCPError as ClientAdcpError

class WireAdcpError(DecisioningAdcpError, ClientAdcpError):
    pass

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).

[bokelley]

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:

• 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.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code