docs: refresh a2a-sdk migration guidance against current 1.0.x pin

[bokelley]

From the salesagent v3.12 → 4.x migration (SDK_FEEDBACK.md, item #5).

MIGRATION_v3_to_v4.md says:

a2a.utils.errors.ServerError → a2a.types.A2AError
a2a.types.DataPart → a2a.types.MessagePart

In a2a-sdk==1.0.1, none of those replacement targets exist:

• A2AError does not exist (only A2ARequest)
• MessagePart does not exist (only Part)
• a2a.server.apps (whole submodule path) does not exist

Adopter outcome:

salesagent/src/a2a_server/ is hand-rolled against a2a-sdk 0.3 and won't run on 1.0+. The migration guide pointed at replacements that also don't exist, so I gated the whole module behind an A2A_LEGACY_AVAILABLE flag and skipped 6 unit-test modules. The migration target for these is adcp.server.serve(transport="a2a") — but that's not what the guide says.

Proposal

Either:

1. Regenerate the a2a-sdk migration section against the current 1.0.x pin (correct symbol names), OR
2. Better: point readers directly at adcp.server.serve(transport="a2a") and explicitly acknowledge that hand-rolled a2a-sdk 0.3 servers don't have a mechanical migration path.

Option 2 is more honest about adopter reality. Option 1 still helps adopters who wrote against a2a-sdk directly rather than via our serve().

Acceptance

A salesagent-shaped adopter (hand-rolled 0.3 server) reads the guide and lands on a clear path: "delete the hand-rolled server, use adcp.server.serve(transport='a2a')."

[bokelley]

Triage

Classification: Bug (doc bug — wrong symbol paths in migration guide)
Bucket(s): docs
Status: drafting-pr

What the experts said:

• docs-expert: approved — two-subsection structure targets the right audiences; acceptance criterion met; a2a.utils.errors.A2AError correction is the key fix
• dx-expert: approved — restore symptom bullets (done), correct A2AError path (done), drop dangerous Value() example (done); serve(transport="a2a") landing point is clean

My take: The migration guide's one-liner told adopters to use a2a.types.A2AError and a2a.types.MessagePart, neither of which exist in the pinned a2a-sdk 1.0.1. The fix goes with Option 2 (as you suggested): hand-rolled 0.3 server adopters get a clear "delete it, use adcp.server.serve(transport='a2a')" directive; direct type importers get a correct symbol table with the right module paths.

Draft PR: #524

---

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

---

Generated by Claude Code