A2A Php Sdk Laravel Package

Technical Evaluation

Architecture fit

• The SDK is a framework-agnostic PHP 8.4+ implementation of A2A protocol 1.0.0, offering both client and server roles. It is not a Laravel package: the release notes describe no service provider, config publishing, facade, or Laravel-native queue/event integration. Treat Laravel fit as "compatible but glue-required," not "drop-in."
• Dual client/server capability is the strategic value. We can both expose our own agents to external callers and consume third-party agents from inside our application, using one contract layer (typed protobuf messages, request validation, transport error mapping).
• Transport flexibility (JSON-RPC, REST, optional gRPC; SSE and gRPC streaming) means we can start on plain HTTP — explicitly documented as needing no native gRPC extensions or OpenSwoole — and defer the operational cost of gRPC/OpenSwoole until a concrete latency or streaming requirement appears.
• Native features that map onto real product needs: principal and tenant isolation, persistent tasks, worker leases, webhook retries, TLS/mTLS, PSR-3 logging, Prometheus metrics. That is a production-shaped feature set rather than a demo client, which raises confidence that the authors intend operational use.

Integration feasibility

• Composer-installable with runtime dependencies resolved by Composer; the attached ZIP is source only. CI includes a clean-consumer-project install, which is the single most useful signal for "will this break my build."
• PHP 8.4+ is a hard floor and the main feasibility gate. Confirm our Laravel version and hosting images run 8.4 before committing; where we cannot upgrade, this package is simply unavailable to us.
• PSR-3 logging composes cleanly with Laravel's Monolog channel configuration. Prometheus metrics do not — we will need an exporter bridge (e.g. a Prometheus client integration plus an /metrics endpoint) as our own work item.
• SSE streaming under PHP-FPM is achievable but requires output buffering disabled and long-running request budget; gRPC streaming realistically requires OpenSwoole or RoadRunner, which is an infrastructure decision, not a library decision.
• Worker leases and persistent tasks imply a durable store and a real worker process. Under Laravel that means queue workers (Horizon), not request-per-process execution — an architectural choice we must make early.

Technical risk

• Protocol immaturity (medium-high). A2A 1.0.0 is young; a 1.0 spec can still churn at the edges. Interop with non-PHP agents is the primary unknown and is not something the SDK's own tests can prove.
• TCK gap (medium). 244 passed / 3 failed / 18 skipped against the official TCK. The three failures are attributed to a documented upstream defect (CORE-SEND-003 expected-error) and disappear to 247/0/18 under an isolated diagnostic correction. This is a credible explanation, but it is not certification, and the vendor says so explicitly. We should not represent ourselves as TCK-certified downstream.
• Bus factor (medium). Effectively single-maintainer project. v1.0.0 is the first release, so there is no track record of responsive security patching.
• Scope creep into infrastructure (medium). Leases, retries, and tenant isolation are semantics we must operate correctly; getting them wrong produces duplicate task execution or cross-tenant leakage, which is a high-severity failure class.

Key questions

• Does the maintainer intend first-party Laravel support (service provider, config, queue driver), and is that on any roadmap?
• What is the persistence backend for tasks and leases — DB-agnostic via PSR interfaces, or opinionated?
• What is the expected maintenance cadence, and is there a security disclosure process?
• Can we get a written statement on the CORE-SEND-003 defect and its upstream tracking issue?
• What is the concurrency model assumed by worker leases (single worker per task? fencing tokens?), and does it hold under Laravel queue retries?
• Are the 18 skipped TCK tests skipped for transport or feature reasons that affect our chosen transport?

Integration Approach

Stack fit

• Target: Laravel on PHP 8.4, HTTP transport first. Defer gRPC and OpenSwoole entirely for the first integration; the release explicitly supports this path.
• Use the SDK as an infrastructure-layer dependency behind our own internal interfaces, so the rest of the application never imports SDK types directly. This contains blast radius if the protocol version moves.
• Wrap the client in a Laravel service bound to the container; expose configuration via a published config file we write ourselves. Do not expect the package to do this.
• Map PSR-3 logging to our existing channels; add a metrics exporter and /metrics route as a separate, small deliverable.

Migration path

• Greenfield: there is no incumbent A2A implementation to migrate from, and no prior assessment. v1.0.0 is the baseline, so we get semver guarantees from here forward.
• Pin to 1.0.* initially, and enable Composer's security advisory auditing in CI. Do not float ^1.0 on day one given the bus factor.
• If we later adopt gRPC, the migration is transport-level behind our wrapper, which is precisely why the wrapper matters.

Compatibility

• PHP 8.4 floor must be verified against our runtime images and any shared hosting constraints before estimation.
• No Laravel version constraint is published, which is an unknown to close in a spike, not an assumption to make.
• Verify the SHA256SUMS and provenance of the attached artifact against the linked CI run before the dependency enters our supply chain.

Sequencing

1. Spike (timeboxed): install into a clean Laravel app, one client call and one server endpoint over JSON-RPC.
2. Decision gate: PHP 8.4 feasibility, persistence backend for tasks/leases, and transport choice for streaming.
3. Build the wrapper layer plus config, logging, and metrics.
4. Build the queue-worker execution model for tasks and leases; test retry and duplicate-delivery behavior deliberately.
5. Add TLS/mTLS for any externally reachable endpoint.
6. Only then evaluate gRPC/OpenSwoole against a measured requirement.

Operational Impact

Maintenance

• We inherit ownership of all Laravel glue: config, container bindings, queue workers, metrics endpoint, and upgrade shims. Budget ongoing effort for this, not just initial integration.
• Track upstream releases closely; with a single maintainer, plan for the possibility of patching or forking. Keeping our wrapper thin is the insurance policy.
• Re-run the TCK baseline comparison on each upgrade so we notice regressions in the three known failures or the skipped set.

Support

• Expect community-only support from the upstream project. Our internal support model must therefore include an on-call path for agent-to-agent failures, and we should not commit to external SLA language around A2A interop.
• Do not market TCK certification. Internally, record the exact TCK result and the CORE-SEND-003 explanation so future audits have the context.

Scaling

• Stateless HTTP client calls scale normally behind load balancers.
• Server-side SSE streaming is the scaling pinch point: long-lived connections need buffering disabled, adequate PHP-FPM worker headroom, and either sticky sessions or a shared pub/sub backplane for subscriptions. Size this explicitly rather than discovering it under load.
• Persistent tasks and worker leases need a durable, low-latency store (Postgres/Redis) and a worker fleet sized independently of web traffic. Leases favor more, smaller workers with fast heartbeat intervals.
• Webhook retries add outbound egress and require idempotency on the receiving side; ensure our own endpoints are idempotent.

Failure modes

• Lease expiry under a stalled worker → duplicate task execution. Mitigate with idempotency keys and fencing on task state transitions; test by killing a worker mid-task.
• Transport errors are mapped by the SDK, but downstream semantics (retry vs. fail) are ours to define per operation. Define this for all 11 operations up front.
• gRPC extension absence on a host that expects it → hard failure at boot. Gate the gRPC path behind config and fail fast with a clear message.
• Metrics exporter failure should degrade observability, not the request path; isolate it.
• Upstream protocol drift breaking interop with third-party agents — detected only by contract tests against a real external agent, which we should stand up early.

Ramp-up

• Two distinct learning curves: A2A protocol concepts (tasks, subscriptions, streaming, agent cards) and protobuf-typed contracts. Engineers strong in Laravel but new to protobuf will need explicit ramp time.
• Recommend one engineer own the protocol layer and write a short internal guide covering the wrapper, retry semantics, and lease behavior before a second team consumes it.
• The clean-consumer install and PHPStan-clean CI lower the onboarding cost meaningfully; the README is cited as the entry point, so validate it end-to-end during the spike and record any gaps.