A2A Php Sdk Laravel Package

Getting Started

• Know what you're installing. This is a framework-agnostic PHP SDK for the A2A protocol (v1.0.0 protocol, v1.0.0 SDK), providing both a client (call other agents) and a server (expose your Laravel app as an agent). It is not a Laravel package: expect no service provider, no auto-discovery, no publishable config, no facade. All Laravel glue is yours to write.
• Check PHP 8.4 first. php -v on your local box, your CI matrix, your Docker base image, and Composer's platform config. Laravel 11/12 permit PHP 8.2, so 8.4 is a real floor that may force an upgrade before you write a line of integration code.
• Read the README in this order: requirements → transport selection (JSON-RPC vs REST vs native gRPC) → client example → server example → auth/principal/tenant → streaming. Transport choice drives everything else.
• Default to HTTP. JSON-RPC and REST need no ext-grpc and no OpenSwoole, which keeps you on standard FPM or Octane. Treat native gRPC as a deliberate later step, not the starting point.
• First use case: outbound client. Bind the client as a singleton, call it from a queued job, log the exchange. Do not start by exposing a server endpoint — that's the harder half and drags in auth, tenancy, and HTTP surface decisions at once.
• Verify before adopting: install into a scratch Laravel app, run the vendor's examples against a local/stub peer, and only then wire it into a real service. The attached ZIP is source only; runtime deps come from Composer.

Implementation Patterns

• Service provider + config. Bind the client (and server kernel) as singletons in a dedicated provider; put base URL, transport, credentials, tenant, and timeouts in config/a2a.php backed by env. Never construct the client inline in a controller.
• Outbound calls belong in jobs. Agent calls are network-bound, potentially long, and streamable. Use a dedicated queue with explicit timeout, tries, and backoff, and treat the call as an external side effect rather than a synchronous step in a request cycle.
• Inbound endpoint is a route + middleware stack. The SDK handles the protocol envelope; Laravel handles HTTP concerns: auth middleware, tenant resolution, rate limiting, body-size limits, and credential/signature verification. Keep the A2A route group thin and separate from your app's public API group.
• Derive the principal/tenant from the authenticated credential, not the payload. The SDK gives you isolation primitives and request validation; it does not know your authorization policy. This is the single most important place to write your own guard rails.
• Streaming: SSE maps to response()->stream() — turn off output buffering, set headers explicitly, and confirm through your real ingress that no proxy or middleware (compression, debug toolbars) buffers the stream. gRPC streaming needs a long-lived runtime (Octane/Swoole or a CLI worker), not classic FPM.
• Persistent tasks and worker leases → a dedicated worker. Run the SDK task worker in its own Laravel queue/consumer so lease timing isn't starved by unrelated jobs, and set the process timeout comfortably below the lease TTL.
• Make handlers idempotent. Webhook retries and lease expiry both mean "the same unit of work may arrive twice." Persist a delivery/event id and dedupe on it.
• PSR-3 logging: inject Laravel's logger, but route to a dedicated channel with structured context (task id, tenant, transport, direction). Protocol logs are verbose and will swamp your app log otherwise.
• Metrics: expose the Prometheus scrape endpoint on a separate, internal-only route/middleware group — never on the public A2A group.
• Testing: put your own interface in front of the client, bind a fake in the container, and assert on the calls your domain services make. Keep one integration test against a local agent stub rather than mocking protocol envelopes.
• Composition: wrap agent-to-agent calls in domain services, not controllers, so chains are testable and reusable from jobs and commands.

Gotchas and Tips

• PHP 8.4 is the adoption blocker. Audit CI, images, and any shared hosting before committing. Watch for Composer resolving against a different PHP than production via platform.
• You are writing the Laravel integration. No auto-discovery means provider, config, bindings, middleware, and error handling are all maintenance you own. Budget for it explicitly.
• TCK status — do not overclaim. The pinned official TCK shows 244 passed / 3 failed / 18 skipped; the three failures are attributed to an upstream CORE-SEND-003 expected-error defect, and with an isolated diagnostic correction the run is 247 / 0 / 18. The release explicitly does not claim full certification. If interop with third-party agents matters, re-run the TCK yourself and record the baseline you accept.
• "Optional native gRPC" — verify the HTTP path covers your operations first. Choosing gRPC later means ext-grpc/OpenSwoole in the image plus a long-running runtime; that's an infrastructure change, not a config flag.
• Transport error mapping is opinionated. Inspect which exception types surface and map them to your retry policy deliberately, or you will retry non-retryable client-side failures.
• Lease expiry × queue retries can double-process tasks. Prefer tries=1 with explicit re-dispatch for task work, and keep handlers idempotent regardless.
• Metrics cardinality: task ids and tenant ids as labels will explode your Prometheus series. Hash or drop them.
• Pin exactly and record provenance. Lock 1.0.0, commit the lockfile, and note the CI run and SHA256SUMS you reviewed. A 1.0.0 of a protocol SDK will move quickly.
• Inspect extension points before forking: transport interface, serializer/validation, logger/metrics injection, credential provider. If those aren't interfaces, wrapping the SDK cleanly becomes painful — worth five minutes before you build on it.
• Debugging: protocol-level errors are opaque from exception messages alone. Enable PSR-3 debug on a dedicated channel and log raw JSON-RPC envelopes with credentials redacted.