Skip to content

docs(adcp): fix a2a-sdk 1.0.x symbol guidance in v3→v4 migration guide#524

Merged
bokelley merged 1 commit into
mainfrom
claude/issue-514-fix-a2a-migration-guide-symbols
May 4, 2026
Merged

docs(adcp): fix a2a-sdk 1.0.x symbol guidance in v3→v4 migration guide#524
bokelley merged 1 commit into
mainfrom
claude/issue-514-fix-a2a-migration-guide-symbols

Conversation

@bokelley
Copy link
Copy Markdown
Contributor

@bokelley bokelley commented May 4, 2026

Closes #514

Summary

MIGRATION_v3_to_v4.md told adopters that a2a.utils.errors.ServerError migrates to a2a.types.A2AError and a2a.types.DataPart migrates to a2a.types.MessagePart. Neither a2a.types.A2AError nor a2a.types.MessagePart exist in a2a-sdk==1.0.1 (the version this SDK pins). A real adopter (salesagent v3→v4 migration) gated an entire module behind A2A_LEGACY_AVAILABLE and skipped 6 test modules because the guide pointed at dead symbols.

This PR replaces the one-liner "see release notes" with two concrete subsections:

  1. Hand-rolled a2a-sdk 0.3 servers — no mechanical migration path; the recommended path is to delete the hand-rolled server and use adcp.server.serve(transport="a2a").
  2. Direct a2a type imports — correct symbol table: DataPart/TextParta2a.types.Part; Part(root=...) wrapper → Part directly; ServerErrora2a.utils.errors.A2AError; and explicit note that a2a.types.A2AError and a2a.types.MessagePart do not exist.

Also corrects the version specifier in the prose from >=1.0.0 to >=1.0.1,<1.0.2 to match the actual pin.

What tested

  • Docs-only change — no Python build or pytest run required per triage protocol
  • A2AError path verified against src/adcp/server/translate.py:32
  • DataPart/TextPart/Part semantics verified against tests/a2a_compat_shim.py:116–129
  • a2a.server.routes + a2a.server.agent_execution paths verified against src/adcp/server/a2a_server.py:28–37
  • Version pin >=1.0.1,<1.0.2 and regression comment verified in pyproject.toml:51–57

Pre-PR review

  • code-reviewer: approved — all factual claims verified against codebase, no blockers; nit on version string staleness (cross-reference to pyproject.toml comment is accurate and sufficient)
  • docs-expert: approved — audience fit correct, acceptance criterion met; nit on heading framing (noted in PR body rather than changed — "no mechanical migration path" is accurate and intentionally direct)

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See adcp#3121
for context.

Session: https://claude.ai/code/session_015ztuszM5hAJG7N5NcA9acB


Generated by Claude Code

MIGRATION_v3_to_v4.md told adopters that `a2a.utils.errors.ServerError`
migrates to `a2a.types.A2AError` and `a2a.types.DataPart` migrates to
`a2a.types.MessagePart`. Neither `a2a.types.A2AError` nor
`a2a.types.MessagePart` exist in a2a-sdk 1.0.1 (the version this SDK
pins). The error base is at `a2a.utils.errors.A2AError`; `DataPart` and
`TextPart` are replaced by `a2a.types.Part` (a protobuf message with a
`content` oneof); `MessagePart` does not exist at all.

Replace the one-line "verify against your usage" punt with two concrete
subsections:
- Hand-rolled 0.3 servers: no mechanical migration path; recommend
  deleting the hand-rolled server and using
  `adcp.server.serve(transport="a2a")`.
- Direct `a2a` type imports: correct before/after for DataPart, TextPart,
  Part wrapper, and ServerError with proper module paths.

Also corrects the version specifier from `>=1.0.0` to `>=1.0.1,<1.0.2`
to match the actual pin in pyproject.toml.

Closes #514

https://claude.ai/code/session_015ztuszM5hAJG7N5NcA9acB
@bokelley bokelley marked this pull request as ready for review May 4, 2026 02:00
@bokelley bokelley merged commit 57cb4e5 into main May 4, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants