r2luna/brain
Brain is an AI agent framework for Laravel. Build LLM-powered agents with tools, memory, and multi-step workflows using simple PHP classes, then connect them to your app's data, services, and existing Laravel features.
Brain models a multi-step business process as a workflow made of actions and events. You declare intent with PHP attributes on your own classes, and Brain handles execution, queueing, persistence and run history.
Start here, in order:
#[Sensitive] section of the README first — even if you have no secrets yet. Redaction is workflow-wide and inherited, so it shapes how you name and structure properties from day one. Retrofitting it is more work than designing for it.#[OnQueue] and brain:migrate docs, then install:
brain:migrate to create the run-history tables.brain:migrate is the command to reach for when you upgrade — check it after every release, not just on first install.brain:show on a trivial workflow to see how Brain renders a process. It's the fastest way to build a mental model of how actions, events and transitions are wired before you write anything real.APP_KEY strategy — see Gotchas. Sensitive values in queued jobs are encrypted with APP_KEY as of 4.1.4.First use case: a queued workflow with one genuinely sensitive input. Something like an account-provisioning flow where an action receives a password or API token, marks it sensitive, and later actions send email and write an audit record. This exercises the three things that matter most day to day: attribute declaration, queue dispatch, and redaction across every event in the workflow.
Attribute-first workflow definitions. Actions and events are ordinary classes; behaviour is declared with attributes (#[Sensitive], #[OnQueue]) rather than configured in a service provider. Keep action classes small and single-purpose — that matches how the package itself is structured and keeps brain:show output readable.
Declare sensitive keys on the action that owns the domain concept, not on every action that touches it. Since 4.1.4, keys declared by any action apply to the whole workflow. This is the intended design: you declare password once and earlier, skipped and cancelled events, validation errors and failure messages all redact it. Use dot notation for nested payloads (user.password, payload.card.number) rather than hand-rolling accessors.
Rely on class inheritance for shared sensitivity. #[Sensitive] is inherited from parent classes, so put credentials on a base action or a shared DTO and every subclass inherits the redaction. This is the cleanest way to keep a family of actions consistent.
Validate real values. rules() runs against the actual value, not the redacted placeholder — so standard Laravel validation rules work normally on sensitive fields, and validation error messages are redacted for you. Don't add defensive "is this redacted?" branches in your rules.
Compose with nested workflows. A nested workflow merges its parent's sensitive keys, so a child workflow invoked from a sensitive parent is automatically covered. Prefer nesting over duplicating key lists; the merge is the mechanism that keeps redaction correct as workflows grow.
Use brain:run as your interactive driver and debugger. It prompts for sensitive values with hidden input and masks them in previews, result tables and run history. This makes it the right tool for manually kicking off a workflow in staging or reproducing a production run locally — you get the full trace without secrets landing in your terminal scrollback or your shell history.
Wire failure handling through events, not try/catch. Sensitive values are redacted from exception messages in failure events and in brain:run. Capture failure context by reading the failure event, and treat the exception message as safe-to-log — but still avoid dump()-ing whole payloads (see Gotchas).
Queue long-running workflows deliberately. Put #[OnQueue] on workflows that make network calls or take more than a request's worth of time. The queue is where encryption-at-rest and payload compatibility matter, so anything queued deserves a note in your runbook.
APP_KEY rotation is now a breaking operational concern. Jobs queued under 4.1.4+ contain #[Sensitive] values encrypted with APP_KEY. Rotate the key and in-flight jobs become undecryptable. Always set APP_PREVIOUS_KEYS to include the outgoing key, and only remove it once the queue is drained of jobs queued before the rotation. Put this in your key-rotation runbook explicitly — it's the kind of thing that surfaces as a mystery failure at 2am, not at deploy time.
Don't rely on APP_PREVIOUS_KEYS forever. It's a drain window, not a permanent safety net. Prune old keys once queue depth and job age confirm nothing predates the rotation.
Mixed-version queues are safe but transitional. Jobs queued before 4.1.4 still run, and pre-encryption SensitiveValue payloads remain readable. That means you can deploy without draining first — but it also means a stale worker fleet will keep producing plaintext payloads. Deploy workers and web together, and verify no old workers are still consuming.
Redaction is workflow-wide, which can over-redact. Declaring password on one action redacts that key everywhere in the workflow, including places you might have wanted it visible for debugging. Choose key names that are unambiguous (api_token, card_number) rather than generic ones like value or secret that may collide with non-sensitive fields.
SensitiveValue is an object, not a string. It's hidden from VarDumper output, which is deliberate — but it means dump(), dd(), ray() and Telescope-style introspection of a payload will show something opaque rather than the value. Don't write tests or assertions that depend on the dumped representation. If you need the real value inside an action, unwrap it the way the package documents rather than string-casting.
brain:run is interactive. Hidden-input prompting is great locally and in a TTY, but it won't help you in CI or a cron context. For non-interactive runs, drive the workflow programmatically and supply sensitive values from your secret store (env, Vault, etc.) — never from committed fixtures.
Sensitive values never appear in run history. Previews, result tables and history all mask them. If you need to correlate a run to a specific credential later, store a non-sensitive fingerprint (e.g. a hash or a last-four) as a separate, non-sensitive field — don't expect to recover the value from the run record.
Contributing? Expect tight internal gates. The package enforces cyclomatic complexity ≤ 10, CRAP ≤ 30, and 100% test coverage via a pre-commit hook. Write the test first and keep methods short; large Workflow/Process methods will fail the gate. This also tells you something about the codebase quality you're depending on — the internal refactors in this release (splitting Workflow, Process and the brain:show printer) are housekeeping, not behaviour changes.
Check brain:migrate on upgrade. The run-history schema evolves; running the command after composer update is cheap insurance and is documented alongside #[OnQueue] in the README and Boost guidelines.
Upgrading from 4.1.3 is low risk. No API removals or deprecations in 4.1.4 — it's a security and correctness release. The behaviour change to be aware of is that redaction is now broader than before, so any test asserting an unredacted sensitive value in a failure event, validation error or brain:run output will need updating. That's a test fix, not a production risk.
How can I help you explore Laravel packages today?