builtbyberry/laravel-swarm
Laravel Swarm is a package for building multi-agent AI workflows in Laravel. It lets you define agents, tools, and handoffs, then coordinate them through simple, testable PHP classes.
Architecture fit: laravel-swarm is a Laravel-native orchestration package for AI agent/swarm workflows, with route-plan schemas, hierarchical planning, persistent swarm memory, tool invocation, replay boundaries, and checkpoint semantics. v0.28.1 is a post-ship fix release against live-model behavior, which signals that the package is still maturing and that integration testing with real models is essential. It fits Laravel applications that can own an AI orchestration layer and absorb pre-1.0 API/behavior churn; it is a weaker fit where stable tool-result contracts, strict multi-tenant isolation, or long-term support guarantees are mandatory from day one.
Integration feasibility: Feasible for a Laravel/PHP team already familiar with config, service container, events, console commands, and model-driven tool execution. However, v0.28.1 includes behavior changes, not just additive fixes. Declined Remember writes now report as failed, capture-policy Skip writes now report as failed and fail the step, and frozen_view retry memory writes now persist under the default replay mode with no switch. The new agent-scope memory tools are opt-in and require both the swarm.memory.tools.agent_scope config key and explicit swarmMemoryTools(agentScope: true) or a custom forAgent() binding. Migration effort is moderate to high because tests, dashboards, alerts, and any logic that interprets nativeResult->tools, SwarmToolResult events, or memory-write success must be reviewed.
Technical risk: The main risk is behavioral instability in a patch release: existing Remember calls that previously read as succeeded will now read as failed when nothing was stored or the capture policy skipped the write. The frozen_view change alters documented default behavior with no toggle, saves are not atomic, successful retries emit ordinary memory events, and a write skipped by capture policy at save time fails the step. Agent-scope memory is off by default, but when enabled it is keyed by agent class and shared across runs and tenants of that class, which is a significant multi-tenancy and data-isolation consideration. Route-plan schema changes are mostly compatibility-safe for PHP-authored and scripted plans, but RoutePlanSchema::worker() now requires with_outputs and declares next as required nullable, so snapshot tests and schema consumers can break. Generated make:memory-tool --scope=agent classes need care: existing agent() overrides keep working but are not governed by the config key, and a null-returning placeholder must be removed before binding with forAgent().
Key questions: What Laravel and PHP versions are supported, and what is the support/SemVer policy for this pre-1.0 package? Which existing tool-result, event, and metric consumers will see Remember outcomes move from succeeded to failed? Is the non-atomic save-before-checkpoint behavior acceptable for our recovery model, or do we need compensating idempotency? Should agent-scope memory be disabled until tenant isolation, retention, and cross-run sharing are explicitly accepted? Are SwarmToolResult events and nativeResult->tools treated as stable integration contracts? What is the recommended observability for memory skips, failed writes, retries, and replay-boundary saves? Do we need to pin the package and gate upgrades behind a live-model regression suite?
TPM recommendation: Treat v0.28.1 as a pilot-grade upgrade requiring a controlled migration, not a routine patch. Adopt where the team can own AI orchestration semantics and instrument memory/tool behavior; defer broad production rollout until upgrade tests, tenant-isolation review, and runbook updates are complete.
Stack fit: The package aligns with Laravel conventions: configuration keys such as swarm.memory.tools.agent_scope, console tooling such as make:memory-tool, event emission through SwarmToolResult, and application-owned policies such as MemoryCapturePolicy. It is best introduced as an internal AI orchestration capability with a clear owner for planner schemas, memory policy, tool contracts, and observability.
Migration path: Before upgrading, read UPGRADING.md#upgrading-to-v0281. Baseline current behavior with tests that cover: Remember declined writes, capture-policy Skip, frozen_view retry and checkpoint failure, downstream reads after retry, and route-plan validation for worker() / node() / rollup() schemas. Update snapshot tests for the worker schema because with_outputs is now required and next is string-or-null. Audit MemoryCapturePolicy implementations and any metrics built on tool-call success. If enabling agent scope, set the config key and make the explicit swarmMemoryTools(agentScope: true) or custom forAgent() binding, then test cross-run and cross-tenant behavior. Regenerate or clean up make:memory-tool --scope=agent output; remove the null placeholder before using forAgent().
Compatibility: Existing valid PHP-authored route plans keep validating, scripted coordinators need no change, alias maps validate as before, and static plans may use the list form for with_outputs. The planner accepts a worker node that omits next or with_outputs in some cases, but the worker schema itself has changed, so schema snapshot tests will need updates. With agent scope left off, Recall and Remember behave as in v0.28.0 apart from declined writes now reading as failed. A SwarmMemory::put() or MemoryStore::put() returns a prospective entry that was not persisted; applications must not rely on its outcome metadata and should use MemoryWriteSkipped as the supported signal.
Sequencing: Pin v0.28.1 in a branch. Run the regression suite against a non-production environment with live-model or representative model calls. Update dashboards and alerts for the success-to-failed Remember outcome shift and for new memory events on retried steps. Validate the frozen_view retry save path with both checkpoint failure and capture-policy skip cases. Enable agent scope only after a tenant-isolation review and per-tenant retention decision. Canary one workflow before broad rollout. Keep a code-level rollback path because the frozen_view behavior has no runtime switch.
Maintenance: High-touch dependency. The package is pre-1.0 and v0.28.1 changes documented default behavior in a patch release. Assign an owner for Laravel package upgrades, UPGRADING.md review, route-schema snapshot maintenance, and memory-policy tests. Avoid floating version constraints; pin and upgrade deliberately.
Support: The release references GitHub issues and UPGRADING.md, indicating community/open-source style support rather than a commercial SLA. Expect to rely on internal Laravel/PHP expertise, upstream issue tracking, and contribution/backport capability for critical fixes. Budget time for reading release notes closely, especially around memory semantics and schema validation.
Scaling: Memory writes, SwarmToolResult events, retry saves, and checkpoint/replay boundaries add I/O and telemetry volume. The frozen_view fix means successful retries now save mutations and emit ordinary memory events, so write volume and event counts can rise after upgrade. Agent-scope memory keyed by agent class can accumulate shared state across runs and tenants; define retention, partitioning, and cleanup before enabling it.
Failure modes: Declined or skipped Remember writes now fail the tool call and may trigger model retries. A capture-policy Skip at save time fails the step. A frozen_view retry can save memory before a durable checkpoint, and the save is not atomic, so recovery must tolerate partial progress. Successful retries emitting ordinary memory events can distort metrics and alerts. Route-plan schema changes can fail validation or snapshot tests. Agent-scope memory can leak behavior across tenants if enabled without isolation controls. Generated tools with an agent() override can bypass the config key and win over a forAgent() binding.
Ramp-up: Medium for Laravel developers, higher for teams new to hierarchical planners, route schemas, replay boundaries, memory capture policies, and tool-result event contracts. Enablement should cover the difference between stored versus reported outcomes, the new failed Remember semantics, MemoryWriteSkipped, replay/checkpoint behavior, and agent-scope memory isolation. TPM should schedule a spike, update runbooks, and define acceptance tests around retry/checkpoint, capture-policy skip, route-schema generation, and tenant-scoped memory before production use.
How can I help you explore Laravel packages today?