Proposal: official Swift SDK — survey of existing implementations and a path to one

[arkavo-com]

A2A has official SDKs for Python, Go, JS, Java, .NET, and Rust — but no Swift SDK, despite Swift being the path to every iOS/macOS/visionOS client and a growing server-side presence. Meanwhile the community has produced at least four independent Swift implementations. This is a proposal to consolidate that energy into one official SDK before fragmentation sets in, rather than a pitch for any one repo.

Survey of existing implementations

I went through the public Swift A2A codebases this week. Facts below are from reading the sources; corrections welcome — especially from the maintainers, whom I'd love to have in this thread: @tolgaki, @BBC6BAE9, @JamieScanlon.

	Protocol version	Scope	Dependencies	Notable
tolgaki/a2a-swift (+ a2a-swift-server)	v1.0 with v0.3 compat (PascalCase methods + legacy fallbacks)	Client SDK; server is a separate Hummingbird-based runtime package	Zero (client); Hummingbird (server)	Most mature client: ~119 tests, Linux CI (swift:6.0), 8 example executables, 20+ releases of its predecessor a2a-client-swift
BBC6BAE9/a2a-swift	v0.3-era (message/send methods)	Client + server + core	swift-protobuf	Active; server target included
JamieScanlon/SwiftAgentKit	v0.3-era	Agent toolkit (MCP + A2A + more), not an SDK per se	Vapor, NIO, swift-log	Broadest scope; A2A is one feature among several
arkavo-ai/a2a-swift (mine, published this week)	v1.0.1 only, mapped field-for-field to specification/a2a.proto	Client + transport-agnostic server dispatcher	Zero (all targets)	Swift 6 strict-concurrency language mode; typed JSONValue (no Any); CI on macOS + Linux (swift:6.3); golden vectors from the spec; cross-SDK interop verified against the Python a2a-sdk 1.1.0 sample server (SendMessage, GetTask, SSE streaming, error-code mapping)

There are also several smaller client experiments (no-problem-dev/swift-a2a, spprichard/swift-a2a-sdk, Victory-Apps/a2a-swift, tolgaki/a2a-swift-client), which mostly underlines the point: the demand is real and the effort is scattering.

The cost of fragmentation is concrete, not aesthetic

Two of these packages — tolgaki's and mine — are both named a2a-swift. SwiftPM resolves package identity from the name, so any dependency graph that transitively pulls both fails to resolve. Today that's unlikely; the moment two mid-size agent frameworks pick different Swift A2A SDKs, it's guaranteed. A small ecosystem can't afford N incompatible wire-type packages, and every month of parallel development makes converging harder.

What I think an official SDK needs (and where each effort helps)

1. Strict v1.0 conformance with the proto as source of truth. Both tolgaki's and my implementation are genuinely v1.0 (proto-name enums, oneof-as-single-key, tenant echoing, full §5.4 error table). Whether an official SDK should also carry v0.3 compat — which tolgaki's does and mine deliberately doesn't — is a real design question worth deciding here, not in parallel repos.
2. A server core that doesn't bless an HTTP framework. Swift has no default server stack — Vapor, Hummingbird, and bare NIO all have real constituencies. I'd argue the official SDK should ship a framework-agnostic dispatcher (Data in → Data out / SSE-framed stream out) with Vapor/Hummingbird adapters as examples or thin satellite packages, rather than a runtime bound to one framework.
3. Linux as a first-class citizen (CI-gated, corelibs-foundation quirks handled — e.g. URLSession.bytes is unreliable there; delegate-based streaming works on both).
4. Cross-SDK interop tests against the reference implementations, not just self-tests — this caught real spec-vs-practice gaps for me (e.g. proto3 serializers omit default-valued REQUIRED fields like AgentInterface.protocolVersion, which a strict decoder rejects).
5. Sustainable maintainership — which is exactly why this should be a merged effort, not a race.

Proposal

1. Maintainers of the existing implementations converge on one repo as the basis for an official a2aproject Swift SDK, merging the best pieces of the others (and crediting all contributors).
2. I'll donate arkavo-ai/a2a-swift to the a2aproject org outright if it's chosen as the base — same arrangement as the other official SDKs. No strings; I'd stay on as a maintainer. If the community converges on a different base, I'll contribute and help maintain there instead and retire my package name to end the SPM collision.
3. Whatever the base, the result targets the a2a-tck and the same conformance bar as the other official SDKs.

For the maintainers tagged above: would you be open to converging? And for the a2aproject steering folks: is there an established process for community SDKs entering the org (the Go and Rust SDKs presumably went through this), and what would you need to see?

[arkavo-com]

Human reviewed and approved.

[arkavo-com]

Follow-up with data: I spent today running a cross-SDK interop matrix rather than arguing features, since proven conformance seems like the axis that matters for an official SDK. Everything below ran against live servers over real HTTP/SSE today (2026-06-10), exercising agent-card resolution, SendMessage, GetTask, SSE streaming (SendStreamingMessage), and error-code mapping.

Client	Server	Result
arkavo-ai/a2a-swift 0.1.0	a2a-python 1.1.0 (official, helloworld sample)	✅ all checks: card → completed task → artifact echo → GetTask → 4-event SSE stream (working / artifact / completed) → -32002 on cancel → -32001 on unknown task
arkavo-ai/a2a-swift 0.1.0	a2a-js v1.0.0-alpha.0 (official, express + DefaultRequestHandler)	✅ all checks: same coverage as above
tolgaki/a2a-swift client	arkavo-ai/a2a-swift server (JSONRPCDispatcher behind a Hummingbird adapter)	✅ all checks: card fetch → completed task → artifact echo → GetTask → SSE stream consumed by tolgaki's parser → cancel correctly rejected with -32002
arkavo-ai/a2a-swift client	tolgaki/a2a-swift-server EchoAgent	⚠️ card resolution, interface selection, and error mapping (-32001, -32601) all interop; one divergence found (below)

The divergence, offered in the spirit of "this is exactly what consolidation fixes," not as a knock — @tolgaki, please correct me if I've misread something: the server's JSON-RPC SendMessage result comes back as a v0.3-style kind-discriminated object ({"kind":"message","messageId":...}) rather than the v1.0 oneof wrapper ({"message":{...}} / {"task":{...}}) that the proto JSON mapping defines and that a2a-python 1.1.0 and a2a-js 1.0-alpha both emit. tolgaki's own client accepts both shapes, which is precisely why same-SDK interop tests can't catch this class of issue — and why I'd want cross-SDK interop runs in CI for whatever SDK becomes official. (Happy to share the harness; it's small.)

Two updates on my own position after this exercise:

1. I was wrong to leave v0.3 compat out, and tolgaki had it right. Running against the ecosystem today makes it obvious how much deployed v0.3 there still is (a2a-js stable is 0.3.13). A merged SDK should adopt tolgaki's compat approach — legacy method-name fallbacks and lenient envelope decoding — on top of a strictly v1.0 wire encoder.

2. "Where does my server runtime come from?" — for Hummingbird users (or Vapor users) the answer is a thin adapter over a framework-agnostic core: the third matrix row above ran on a ~30-line Hummingbird adapter (card route + one POST route mapping the dispatcher outcome to JSON or SSE). tolgaki's Hummingbird runtime has the operational features an adapter doesn't (auth contexts, registries, webhooks) — in a merged SDK I'd want that layer preserved as the Hummingbird adapter package, with the dispatch core staying framework-neutral so Vapor/NIO users get the same protocol behavior.

The donation offer from the original post stands regardless of which codebase becomes the base. The matrix above is the case for converging: every divergence between Swift implementations is currently invisible until someone wires two of them together.

[arkavo-com]

Promised follow-up: the interop testing from my earlier comment is now a standing, vendor-neutral tool — arkavo-ai/a2a-conformance (Apache 2.0, donation offer applies to it as much as to the SDK).

It's a pairwise matrix: N client harnesses × M server harnesses, 29 declarative scenarios (every §5.4 error code, streaming, discovery, proto3-canonical edge cases), scripted servers for determinism, and a wire capture attached to every failure so disagreements are arguable from bytes, not vibes. It complements a2a-tck (one server vs. the spec) by testing implementation pairs against each other — the divergence class self-tests structurally cannot catch. Adding an SDK is two small binaries speaking an NDJSON stdio contract (CONTRACT.md).

First full run: 3×3 (a2a-rs × arkavo-swift × tolgaki-swift)

261 results: 196 pass / 41 fail / 24 honest skips / 0 harness errors — deterministic across reruns. The failures reduce to nine root causes, spread across all three SDKs including mine (FINDINGS.md has evidence and exact code locations; results.ndjson is the machine-readable record):

a2aproject/a2a-rs @ 7676ec9f

1. The client never transmits tenant — no injection path exists, so §8.3.2 rule 4 can't be satisfied. Fails tenant-echo against every server, including its own.
2. protojson decode rejects unknown fields, against §5.7's forward-compatibility SHOULD.
3. The SSE client discards an unterminated buffer at EOF, so a plain-JSON error envelope answering SubscribeToTask becomes a silently empty stream.

tolgaki/a2a-swift + a2a-swift-server @ pinned revisions
4. The v0.3-style flat result envelopes I mentioned in my last comment, now quantified: that single cause accounts for 14 of the failures (server-side and SSE frames). @tolgaki — this would be the highest-leverage single fix in the whole matrix.
5. The client also emits v0.3-flavored request shapes; a2a-rs's strict decoder rejects them with −32700 (my lenient decoder happens to accept most).
6. Client interface selection takes supportedInterfaces.first regardless of binding (§8.3.2) — fails even in the self-pair.
7. Undecodable params map to −32603 instead of −32602.
8. GetExtendedAgentCard is auth-gated with an off-spec −32010.

(Build-level, from CI rather than the matrix: the server stack doesn't compile on Linux — its a2a-client-swift 1.0.22 dependency lacks FoundationNetworking imports. The newer client repo has Linux CI; the server's pinned dependency predates it.)

arkavo-ai/a2a-swift (mine)
9. In 0.1.0, the streaming client dropped plain-JSON error envelopes: a plain-JSON error answering a streaming request yielded a silently empty stream — the same defect class as finding 3. Found by the matrix, fixed in 0.1.1, and the scenario is now green against a2a-rs — the harness's first end-to-end find→fix→verify loop, which is the workflow I'd want for every SDK in the matrix.

One genuine spec gap

Findings 3 and 9 share a root cause that isn't any SDK's fault: §9.4.2 doesn't specify how a pre-stream protocol error is delivered to a streaming request. a2a-rs answers with a plain application/json envelope; my server SSE-frames the error as an event; each choice breaks the other side's client. The spec should mandate one (or require clients to branch on Content-Type). Happy to open a spec issue if maintainers agree it's worth pinning down.

Standing offers

• @tolgaki: the adapter wrappers for your SDK live in adapters/tolgaki-swift/ — yours to own/upstream if you want them, and I'd welcome corrections if any finding mischaracterizes your code. The harness skips (never fails) anything your handler abstraction doesn't expose, and your SDK's lenient decode legitimately passes cells my strict decode would fail — the matrix cuts both ways.
• a2a-python as oracle is the planned next column/row — when two implementations disagree, the reference SDK breaks the tie.
• If the a2aproject maintainers see value, the scenario corpus (or the whole tool) can move upstream alongside a2a-tck — same donation terms as before.