Laravel Swarm Laravel Package

Getting Started

• Install the package and publish its config (config/swarm.php). For v0.28.1, read UPGRADING.md first — the frozen_view retry save and memory-tool failure reporting changes affect existing runs.
• Decide whether you need agent-scoped memory tools. They are off by default. To enable them, set SWARM_MEMORY_TOOLS_AGENT_SCOPE=true and call swarmMemoryTools(agentScope: true) in your agent, or bind a custom tool with forAgent().
• Add memory tools to an agent via HasSwarmMemoryTools. A simple first use case is: an agent recalls a prior entry with Recall, writes a new entry with Remember, then runs a small hierarchical plan built with RoutePlanSchema::worker() / node() / rollup().
• If you generate memory tools, use make:memory-tool. For agent-scoped tools, use --scope=agent only after confirming you have both the agent_scope config key and a forAgent() binding.

Implementation Patterns

• Agent-scoped memory: Bind Remember / Recall to an agent with forAgent(), or use swarmMemoryTools(agentScope: true). Agent memory is keyed by agent class, so it is shared across runs and tenants of that class — do not treat it as per-run storage.
• Write/read separation: A bound Remember stores under any propagation policy. A bound Recall only returns the entry when the policy includes the agent scope. Configure the propagation policy with that asymmetry in mind.
• Tool outcome handling: Treat nativeResult->tools and SwarmToolResult events as authoritative. Declined Remember writes (empty key, reserved swarm: prefix, unknown scope, unaddressable scope) now report as failed. Capture-policy Skip also reports as failed and tells the model not to retry. The run continues so the model can correct or retry where allowed.
• frozen_view retries: Under the default replay mode, a Run-scope SwarmMemory put/forget made through the replay view, including Remember, is saved after the retried step’s invocation, guardrails, and step recording succeed — before the durable checkpoint. Later steps can read the value. A retry that fails before that point saves nothing.
• Route-plan schemas: Use RoutePlanSchema::worker() for worker nodes. with_outputs is now required (may be empty), and next is required but nullable. rollup() / node() plans may use with_outputs as a list of node ids or as an alias map. Plain worker branches may omit next when it names the join of every parallel group that owns the branch; the planner treats it as redundant.
• Parallel fan-outs: Helper-typed parallel fan-outs and terminal workers now validate. A plain worker branch whose next names its group’s join no longer throws. A model constrained by worker() may return next: null.
• Generated tools: New make:memory-tool --scope=agent stubs warn that a forAgent() binding and the agent_scope key are required, and they no longer generate an agent() override. Existing generated classes that override agent() still work, but remove the null-returning placeholder before binding with forAgent().

Gotchas and Tips

• frozen_view retry writes are now saved by default and there is no switch. The save is not atomic. A successful retry now emits ordinary memory events, and a write the capture policy skips at save time fails the step. If you depend on the old discard behavior, read UPGRADING.md before upgrading.
• Tool success metrics will move. Declined Remember writes and capture-policy Skip writes previously looked successful; they now appear as failed in nativeResult->tools and as unsuccessful SwarmToolResult events. Applications building metrics on those results will see a shift even though storage behavior is unchanged.
• Direct memory writes are not a success signal. SwarmMemory::put() and MemoryStore::put() can return a prospective entry that was not persisted. Do not rely on its outcome metadata. Use the MemoryWriteSkipped event as the supported application signal for skipped writes.
• Agent scope needs both switches. The swarm.memory.tools.agent_scope config key (SWARM_MEMORY_TOOLS_AGENT_SCOPE, default false) and a forAgent() binding (or swarmMemoryTools(agentScope: true)) are both required. With either missing, tools behave as in v0.28.0 apart from failure reporting.
• Subclass overrides win. A subclass that overrides agent() is not governed by the agent_scope key, and an agent() override wins over a forAgent() binding. Remove old generated agent() placeholders before binding with forAgent().
• Schema snapshot tests may need updates. RoutePlanSchema::worker() now declares with_outputs as required and changes next from string to string-or-null. The planner still accepts worker nodes that omit next, so scripted coordinators and PHP-authored plans usually need no change. Static plans may use the list form for with_outputs.
• Debugging tool outcomes: Inspect nativeResult->tools and the SwarmToolResult event. For a skipped write, the model sees The entry [key] was not stored. Do not retry this write. The policy’s reason is not shown to the model.
• Extension points: Custom memory tools can implement forAgent(). MemoryCapturePolicy controls skips and now surfaces skipped writes as failures for tool calls. RoutePlanSchema helpers and the hierarchical planner remain the main integration surface for plan validation.