Laravel Swarm Filament Laravel Package

Getting Started

• Install with composer require using the constraint that matches your app: this package admits Swarm core ^0.19 through ^0.28. If you are on Laravel AI 1.x, prefer the v0.28 lane.
• Start by reading config/swarm.php (or the package’s published config) and the service provider bindings. These show how agents, swarms, and the Laravel AI client are wired.
• Confirm your environment before writing application code: PHP 8.4/8.5 are the newly exercised lanes, and Laravel AI 1.x is the officially supported AI dependency on the v0.28 lane.
• First use case: define one small agent or swarm, resolve it from the container, and run a single prompt through Laravel’s AI facade. This verifies config, credentials, and the core version in one pass.
• Upgrade note for v0.4.0: there are no runtime, schema, or usage-accounting changes. The release is a compatibility expansion, so an existing v0.3.x integration should continue to work after a normal composer update.

Implementation Patterns

• Prefer container resolution over manual construction. Register agents/swarms in a service provider and resolve them in controllers, jobs, or commands. This keeps configuration and API keys out of call sites.
• Use the version lanes deliberately. If your application depends on native Laravel AI features from Swarm v0.28, pin the v0.28 lane and keep Laravel AI at 1.x. If you are still on an older core, retain the corresponding ^0.19–^0.27 constraint rather than floating blindly.
• Keep swarm definitions close to their use case. Small, named agents composed into a swarm are easier to test and observe than a single large prompt-building class.
• Use Laravel’s testing fakes around the AI boundary. Assert that the expected agent is resolved and invoked, and keep provider-level response assertions in a separate integration test.
• Queue long-running swarm work. Dispatch a job from the controller and resolve the swarm inside the job so retries and timeouts are handled by Laravel’s queue system.
• Leverage native Laravel AI access on v0.28. Where the package exposes Laravel AI features directly, use those bindings instead of maintaining a parallel client wrapper. This reduces duplication and keeps usage accounting consistent with the core.
• Pin in CI. Maintain a matrix that covers your production PHP version and at least one adjacent lane. The v0.4.0 release explicitly adds PHP 8.4/8.5 lanes, so treat those as first-class test targets if you deploy there.

Gotchas and Tips

• A v0.28 lane can still resolve older cores if constraints are loose. The release notes call out a control that rejects a v0.27 core on the v0.28 lane. If you maintain your own compatibility tests, add the same discriminating assertion: on the v0.28 lane, assert the installed core is actually ^0.28.
• No schema or usage-accounting changes does not mean no dependency drift. composer update can still move Swarm within its admitted range. Lock the core version in composer.lock and review the lock diff in CI.
• Clear config cache after changing swarm settings. php artisan config:clear is the usual fix when agent registration or credentials appear stale.
• Debug at the boundary. Log the resolved agent name, the core version, and the Laravel AI driver before logging prompts. This separates “wrong agent wired” from “provider returned an error.”
• Watch for version-dependent behavior in tests. If a test passes on ^0.19 but fails on ^0.28, do not assume the package is broken; check whether the test relies on a core behavior that changed between those lines.
• Extension points are the safer customization route. Prefer custom agents, middleware, or container bindings over subclassing internals. The v0.4.0 release is compatibility-only, so internal APIs should not be treated as newly stable.
• PHP 8.4/8.5 users should verify the full stack, not just this package. Laravel AI 1.x and Swarm v0.28 are exercised together in this release, but other dependencies may still emit deprecations on newer PHP versions. Run the application test suite, not only the package’s tests.