Download the PHP package twdnhfr/laravel-deepagents without Composer

Laravel Deep Agents

A deep-agent harness for the Laravel AI SDK — an owned, resumable agent loop with planning, sub-agents, human-in-the-loop approval, multi-turn conversations, memory and automatic context management, built on top of laravel/ai.

[!WARNING] Early work in progress. The runtime and core harness are built and tested — owned agent loop, human-in-the-loop, multi-turn, planning, sub-agents, memory and context management (summarization + tool-output offloading) over pluggable backends. Skills are planned; filesystem/shell tools and token streaming are out of scope for now (see docs/adr/). APIs may still change before 1.0.

[!NOTE] Not affiliated with or endorsed by LangChain. An independent reimplementation for Laravel, inspired by the deepagents project.

What is Laravel Deep Agents?

The Laravel AI SDK (laravel/ai) is an excellent engine: one unified, expressive API over many providers (OpenAI, Anthropic, Gemini, and more), with tool calling, structured output, streaming, embeddings and more. Point it at a model, hand it some tools, call prompt() — done.

But an engine is not an agent harness. The moment you ask an agent to do real, long-horizon work — research across many steps, read and write files, delegate subtasks to focused sub-agents, pause for your approval before doing something destructive, and later pick up exactly where it left off — you need a layer of opinionated machinery on top: planning, a virtual filesystem, sub-agents, automatic context management, human-in-the-loop, skills and memory.

In the Python/LangChain world that layer is deepagents — "the batteries-included agent harness", itself an attempt to distill what makes Claude Code general-purpose. There was no equivalent for Laravel.

Laravel Deep Agents is that layer. It builds on top of laravel/ai and brings the deepagents feature set to PHP:

The SDK stays the engine. This package adds the harness.

Why a custom loop?

laravel/ai runs its model↔tool loop inside the provider — great for a one-shot prompt(), but it gives you no place to step in between the model choosing a tool and that tool running. That in-between is exactly where approval gates, permission checks and context compaction live.

So this package owns the loop: it drives one model turn at a time and decides for itself when to run a tool, when to pause for a human, and when it's done. The entire state of a run is a plain, serializable value object — so a run can pause, be stored in your database or a queued job, and resume in a completely different request.

The how-and-why is recorded as Architecture Decision Records in docs/adr/.

Requirements

• PHP 8.3+
• Laravel 13
• laravel/ai ^0.9 (configured with at least one provider/API key)

Installation

The package auto-registers. Configure your provider and API key through the Laravel AI SDK as usual (e.g. ANTHROPIC_API_KEY in .env and the provider entry in config/ai.php).

Quickstart

Define a tool (the standard laravel/ai Tool contract), then build and run an agent:

By default the agent runs autonomously: it calls tools and loops until it has a final answer.

[!NOTE] One tool instance per agent. Built-in tools receive run-scoped state (the RunState, the storage backend) by injection right before execution — an instance shared between two agents (e.g. a parent and a sub-agent) would leak state between their runs. Construct tools fresh per agent, as in the example.

Planning with todos

Give the agent the built-in write_todos tool so it can keep a visible plan. The list lives on the run state:

Human-in-the-loop: approve before tools run

Opt into approval mode and the agent suspends before any tool call instead of executing it. The suspended run is fully serializable, so you can store it, show the pending action to a human, and resume later — in another request or a queued job:

The human does not have to wave everything through. Record a per-call decision on the state before resuming — approve as-is (the default), execute with corrected arguments, or reject with a reason the model gets back as the tool's result so it can adjust its plan:

Decisions are plain data on the RunState, so they survive toJson()/fromJson() — collect them in a controller, persist, and resume in a queued job. A rejected call is never executed; the model sees The user rejected this tool call: … and reacts. With edit(), the model's original arguments stay visible on the assistant message in the history, so the change is auditable.

Multi-turn conversations

run() starts a fresh run; continue() carries an existing run forward with the user's next message, so the agent keeps full prior context. The run state is serializable, so you can persist it between turns (session, DB, …):

A suspended run (pending tool approval) cannot be continue()d — it throws; resume() it first. Each continue() resets the maxTurns budget, which is otherwise tracked on the run state across suspend/resume.

Sub-agents: delegate to an isolated context

Register a sub-agent and the parent gets a task tool to delegate self-contained work to it. The sub-agent runs as its own DeepAgent to completion and hands back only its final text:

[!IMPORTANT] "Isolated" means the context, not the workspace. A sub-agent gets a fresh conversation — it never sees the parent's message history or todos, and only its final text returns to the parent. But it shares the parent's storage backend (artifacts/memory) by default, mirroring deepagents' shared virtual filesystem. So:

• Artifacts a sub-agent writes are readable by the parent and its siblings — they all hit the same store. Two agents writing the same path overwrite each other; there is no per-sub-agent sandbox.
• The exception is offloaded tool output (offloadLargeToolResults()): it is written under the run-scoped path runs/{runId}/tool/{callId}, so runs sharing a persistent backend never collide — and a host can clean up after a run via backend->list("runs/{$state->id}/").
• To give a sub-agent its own private store, set ->backend(...) on it explicitly — an explicit backend is always kept, never replaced by the parent's.

How it works

• DeepAgent — the fluent front door (make(), provider(), model(), instructions(), tool()/tools(), withTodos(), subAgent(), memory(), summarize(), requireApproval(), maxTurns(), run(), resume(), continue()).
• Runtime\Loop — drives the agent one model turn at a time using maxSteps: 0, the seam that returns the model's tool-call intention without executing it (verified across Anthropic, OpenAI and Gemini — see ADR-0002).
• Runtime\RunState — the serializable state of a run (history, pending tool calls, todos, status). The single source of truth that survives suspend → persist → resume.
• Contracts\Backend + Backends\StateBackend — the pluggable file-storage seam for the upcoming filesystem tools.

Security model

The package's trust boundary sits in your application, not inside the library. What that means in practice:

• A serialized RunState is trusted input. It carries the system prompt, the full history and the pending tool calls that resume() will execute — whoever can edit the blob can make the agent run any registered tool with any arguments. Persist it server-side (DB, cache, queue payload). Never round-trip it through a browser or any other client; if it must cross a trust boundary, sign it (e.g. HMAC) and verify before RunState::fromJson().
• resume() approves by default. A pending call without a recorded decision is executed — calling resume() is the approval in the simplest flow. reject() anything that must not run, and treat the endpoint or job that calls resume() as the security control: authenticate it and re-check there that the pending calls are ones this user may approve.
• A backend is a shared store, not a sandbox. The artifact tools read and write any path within the backend, and sub-agents inherit the parent's backend by design (a shared scratchpad). In a multi-tenant app, give each tenant its own scope — a separate filesystem root, cache prefix or database table — instead of pointing every agent at one shared persistent backend. The default state backend is in-memory and per-run, so it isolates by construction. FilesystemBackend refuses .. segments and paths that resolve (through symlinks) outside its root.
• Validate security-critical tool arguments inside the tool. The optional ValidateToolArgs middleware only checks parameter names (unknown/missing) against the schema — types, ranges and authorization are the tool's job.
• Tool exceptions are shown to the model. A throwing tool hands its exception message back as the tool result so the model can react — so don't put secrets or internal details into exception messages your tools throw.

Status & roadmap

The full plan lives in TODO.md.

Demo

See every feature run offline (no API keys), via a scripted provider:

It walks through autonomous tool use, planning, human-in-the-loop approval, context summarization and sub-agents. See examples/.

Example app: deepagents-chat

twdnhfr/deepagents-chat is a small Laravel chat app built on this package — a live, end-to-end example. It shows the owned loop in a real request cycle: a tool-call trace, the human-in-the-loop approval flow, multi-turn conversations, a DatabaseBackend with tool-output offloading, and Markdown-rendered replies.

Testing

Credits & inspiration

• langchain-ai/deepagents — the Python harness whose feature set and naming this package follows.
• laravel/ai — the SDK this package is built on.
• twdnhfr and all contributors.

License

The MIT License (MIT). See LICENSE.md.