A2A Symfony Bundle Laravel Package

Getting Started

This is a Symfony bundle that exposes an A2A (Agent-to-Agent) endpoint for your application. Day one is short:

1. composer require the bundle (v1.0.2 or later — see Gotchas for why the patch matters).
2. Register it in config/bundles.php if Flex doesn't do it for you.
3. Create a route file that imports the bundle's A2A routes with type: a2a, alongside the rest of your routing config.
4. Add the minimal A2A configuration (agent card / agent services) under your bundle's config key.
5. Run bin/console debug:router and confirm the A2A routes appear.

Look first at debug:router — it is the fastest signal that the route loader is wired up and that your config is being picked up. Second, look at your bundle config reference for the agent service definitions; nothing is active until those are configured, which is deliberate.

The first realistic use case: stand up a single A2A agent with one skill so another agent (or your own test client) can fetch the agent card and invoke it locally, then point it at your real service.

Implementation Patterns

Route import first, config second. v1.0.2 makes this safe: the bundle always registers its route loader. If A2A isn't configured, the loader returns an empty collection rather than throwing. This means you can commit the route file as part of your standard routing scaffold and let environments opt in via config.

Environment-scoped agent activation. Because unconfigured agents are simply inactive, a clean pattern is to define agent services only in the envs where they belong (config/packages/*_dev.yaml vs prod). The route file stays identical; the collection stays empty where you don't want exposure.

Route file as the contract boundary. Keep the type: a2a import in a dedicated file (e.g. config/routes/a2a.yaml) rather than inlining it into routes.yaml. This makes it trivial to include/exclude in tests, to inspect in isolation, and to reason about during upgrades — the v1.0.2 regression existed precisely because the loader wasn't resolvable at import time.

Cache-warming discipline in CI/deploy. The route loader runs at cache warmup. Run cache:clear then debug:router in both dev and prod as a smoke test — the upstream CI does exactly this against a fresh skeleton. Mirror it: your deploy pipeline should verify routes in the same env it ships.

Test the negative case. A useful integration test asserts that with no A2A config, the router still builds and A2A routes are absent. That is the exact scenario v1.0.2 fixed, and it's cheap insurance against a future loader regression.

Persistence checks. If you use the bundled PostgreSQL persistence path, keep a CI job that boots against a real Postgres. The project validates this upstream; your app should too, since persistence is where config drift hides.

Gotchas and Tips

Upgrade to v1.0.2 if you ship a type: a2a route file. In v1.0.1 and earlier, importing A2A routes before configuring the bundle caused Symfony to fail outright because the route loader wasn't registered. If you worked around this by ordering config before routing, or by conditionally including the route file, you can now remove that workaround.

"Routes missing" is usually "not configured", not "broken". The loader registers unconditionally and returns an empty collection without config. Don't chase routing bugs — check your agent service configuration first.

Empty router output is silent. There's no warning when A2A is unconfigured. Add an assertion in your own boot/health check if a missing agent endpoint would be a production incident rather than a benign dev default.

Clear caches after upgrading. The loader registration and route collection are compiled into the container/router cache. A stale cache can make the fix appear not to have landed. bin/console cache:clear in each env, then re-run debug:router.

Fresh-skeleton installs are the compatibility canary. Upstream CI installs into a Symfony 8.0 skeleton with Flex and Composer scripts enabled and the route file already present. If you pin Symfony versions or disable Flex plugins, you're outside that tested path — verify the route file import order yourself.

Prefer the tagged archive + SHA256SUMS for lockfile-pinned deploys. The v1.0.2 artifact comes from the CI run and ships with a checksum; verifying it is free supply-chain hygiene if you vendor or mirror packages.

Version pinning. This is a young package (1.0.x) with behavior changing between patches. Pin to ^1.0.2 at minimum and read patch notes before bumping — the route-loader semantics changed in a patch release, which is a useful signal about how conservative the versioning will be.