Weave Code
Ai Laravel Package
durable-workflow/ai
Durable Workflow AI brings resilient, long-running AI workflows to Laravel. Define multi-step agents and pipelines in PHP with automatic retries, persisted state, and human-in-the-loop approvals, so AI tasks survive failures and run reliably in the background.
Durable sandbox lifecycle orchestration for AI agents built on Durable Workflow.
Frequently asked questions about Ai
- How do I install durable-workflow/ai in a Laravel application?
- Install it with composer require durable-workflow/ai, then publish the package config and migrations and run php artisan migrate. The service provider is auto-discovered, and the migrations create the workflow, run history, and sandbox records the runtime needs. Because the package is pre-GA, pin an exact version instead of using a floating constraint. Check the repository README for the current release candidate you should target.
- Which Laravel and PHP versions does durable-workflow/ai support?
- No version matrix has been published yet, so treat the package's composer.json as the source of truth and test against your target Laravel and PHP versions before committing. It is built on Laravel queues, events, and facades, so it expects a queue-capable application on a supported PHP runtime. Ask the maintainers for a support matrix if you need a firm guarantee for an upgrade path.
- What happens to a running agent if the queue worker dies mid-run?
- State is persisted after each LLM call and tool call, and the workflow replays from the last completed step when the job is retried. Completed steps re-execute idempotently rather than repeating side effects blindly, provided each activity derives a stable idempotency key. In practice a multi-step agent resumes where it left off instead of restarting from the first prompt.
- Why do my durable workflows fail with replay or non-determinism errors?
- Workflow bodies must be deterministic: calling now(), rand(), config() with changing values, or reading fresh Eloquent data inside workflow code produces history that diverges on replay. Move every non-deterministic read and every side effect into an activity and pass the result back as a recorded value. This is the classic adoption failure and it often surfaces weeks after launch, so make it an explicit code review rule.
- Is 2.0.0-rc.8 stable enough to run in production?
- Treat it as a release candidate, not a GA release: it exists primarily to validate against Durable Workflow 2.0, which is itself pre-GA. Upgrades must happen in lockstep with the parent runtime, and since no changelog or migration notes are published, every bump deserves a source diff review. Start with a non-critical workflow and expect API churn before 2.0 GA.
- How should I derive idempotency keys for tool calls and LLM prompts?
- Derive the key from stable workflow data such as the run id, the step name, and the arguments that determine the side effect, so a replay produces the identical key and the activity can detect an already-applied operation. Keep the derivation inside the activity rather than the workflow body. Never derive it from timestamps, random values, or auto-increment database IDs.
- Can durable-workflow/ai execute untrusted code or drive a browser in a sandbox?
- The package orchestrates sandbox lifecycle, covering provision, snapshot, restore, lease, and reclaim, behind a pluggable sandbox provider interface, so supported backends like Docker, Firecracker, E2B, or browser providers depend on what ships and whether that interface is still pre-1.0. It coordinates security but does not enforce it for you. Scope credentials to activities and providers only, control egress, and set hard caps on iterations, wall-clock time, and spend.
- Where does durable-workflow/ai persist workflow state?
- Durable state is persisted through the package's published migrations, which cover workflow and run history plus sandbox records, so plan for those tables in your application database. Queue routing is separated for workflow tasks versus activities, letting orchestrator work and side-effecting work scale independently. Confirm the required drivers and connection details in the package README before designing your infrastructure.
- How do I test a durable AI workflow locally?
- Use Laravel's normal testing tools with a fake AI client and a sync or database queue, then assert against the recorded run history the package exposes. Deterministic replay lets you inspect a run step by step, so failure-injection tests that throw inside an activity and assert the resume point give the most value. Add a test that replays each workflow body twice to catch non-determinism early.
- How does durable-workflow/ai compare to plain Laravel queue jobs or Horizon?
- Horizon and plain queued jobs give you retries and monitoring but lose in-process progress when a worker dies mid-job, which is exactly what a long agent run hits. A durable execution engine persists each step and replays deterministically, a structurally different guarantee and a larger architectural commitment. If your agent fits comfortably in a single job with a timeout, plain queues are simpler; adopt a durable runtime only when runs genuinely span multiple calls, approvals, and teardowns.
Weaver
How can I help you explore Laravel packages today?