Download the PHP package andmarruda/laravel-agents without Composer

Laravel Agents

Laravel-native AI agents inspired by Mastra, built around a small multimodal kernel: model routing, image generation, worker agents, supervisor orchestration, tools, and provider adapters.

This package is in early alpha. The current implementation is intentionally focused on useful orchestration primitives: running agents, letting a supervisor decide which worker should act next, and running deterministic workflows when a process should be explicit and repeatable.

What Works Now

• Model routing with provider/model names.
• OpenAI, Anthropic/Claude, and Fireworks AI model adapters.
• Image generation routing with an OpenAI image adapter.
• Billing and usage routing with an OpenAI billing adapter.
• A small AgentKernel for text and image capabilities.
• Worker agents using the base Agent class.
• Manager-style orchestration using SupervisorAgent.
• Basic AgentResponse metadata and supervisor step history.
• Tool definitions and JSON-based tool execution loops.
• Deterministic workflows with steps, branches, parallel fan-out, loops, and forEach processing.
• Workflow input/output schemas, queued jobs, suspend/resume snapshots, and human approval steps.
• Production observability with traces, spans, model usage, cost metadata, lifecycle events, storage, and optional JSON dashboard routes.
• Input, output, and tool guardrails with validation, correction retries, permissions, redaction, and human approval.
• Retrieval-augmented generation with loaders, deterministic chunking, OpenAI embeddings, pgvector, Qdrant, retriever tools, and workflow steps.
• Production RAG with content-aware chunking, embedding cache, relevance thresholds, queued indexing, streaming loaders, and metadata validation.
• Ports & Adapters boundary for model providers.
• Laravel package auto-discovery and publishable config.

Planned Next

• Streaming and structured output helpers.

See ROADMAP.md for the version plan.

RAG documentation: Português.

Guardrails documentation: Português.

Installation

If the package is already available through Composer/Packagist, require it in a Laravel app:

For local alpha testing, add a path repository to your Laravel app composer.json:

Then require it:

Publish the config:

Publish and run the package migrations when using memory or observability storage:

Configure at least one provider:

Model Names

Use the provider/model format:

The model router depends on the ModelPort interface. Provider integrations live in adapters:

• OpenAiModelAdapter
• AnthropicModelAdapter
• FireworksModelAdapter

Image Generation

Image generation is exposed as a capability instead of pretending images are just text:

You can also go through the kernel:

Billing And Usage

Billing uses a ports-and-adapters boundary, so the application asks for a provider and the provider adapter decides how to talk to the external API.

OpenAI billing currently supports cost buckets through /organization/costs and resource usage through /organization/usage/{resource}. Use usage('completions', ...) for model inference usage, and pass OpenAI filters such as model, project_ids, user_ids, api_key_ids, or group_by through BillingQuery.

Worker Agent

Create a worker agent in your Laravel app, for example app/Agents/ResearchAgent.php:

Run it:

Supervisor Agent

A supervisor coordinates worker agents. It asks the model for a strict JSON decision on every step:

• delegate to a worker;
• or return the final answer.

Run it:

The supervisor expects one of these JSON shapes from the model:

Passing Context

You can pass runtime context to an agent:

For supervisor runs, context is also passed down to worker agents along with previous_steps.

Tool Execution

Agents with tools can ask the kernel to execute a real action by returning strict JSON:

The agent executes the tool, injects the tool result into the next model call, and then continues until it returns a normal final answer or reaches the tool-step limit.

Observability

Observability is opt-in. Agent runs, direct model calls, tool calls, supervisor delegation, and workflow nodes emit traces and spans when enabled. Responses include trace_id metadata when tracing is active:

Configure storage and the optional JSON dashboard in config/agents.php:

The dashboard exposes:

• GET /agents/observability/traces
• GET /agents/observability/traces/{traceId}

The package also dispatches Laravel lifecycle events for agent, model, tool, and workflow activity, and includes an OpenTelemetry-shaped exporter contract for forwarding traces to your own telemetry pipeline.

RAG

Index Laravel-friendly document loaders into memory, PostgreSQL/pgvector, Qdrant, or a custom vector store:

Publish the dedicated PostgreSQL/pgvector migration only when using that store:

See the complete RAG usage guide for loaders, metadata filters, retriever tools, workflow steps, pgvector, Qdrant, and custom adapters.

Deterministic Workflows

Use workflows when a process should follow known steps instead of asking a model to choose the next action. Workflows run synchronously in this first slice and return structured output, step history, and final context.

Reusable step classes implement Andmarruda\LaravelAgents\Workflows\Step:

Available flow helpers:

• then() for one deterministic step after another.
• branch() for named paths.
• parallel() for deterministic fan-out/fan-in in declaration order.
• loopUntil() for bounded loops.
• forEach() for processing iterable items.
• approval() for human-in-the-loop suspension and resume.

Workflows can validate input and output payloads:

Human approval steps suspend the workflow and return a resumable snapshot:

Class-based workflows can be queued. The job implements Laravel's ShouldQueue contract:

Current Limitations

• Closure-based workflow steps are best for synchronous runs; class-based workflows are the safest option for queued execution.
• InMemoryWorkflowStore is useful for tests and local examples. Production apps should bind a persistent WorkflowStore.
• Streaming is not implemented yet.
• Image generation currently ships with an OpenAI adapter only.
• Billing currently ships with an OpenAI adapter only.
• Supervisor decisions rely on the model returning valid JSON.

These are deliberate alpha constraints. The current core is meant to validate the package shape inside a real Laravel project before adding heavier modules.

Testing

Run the automated test suite:

The initial suite covers model routing, image routing, DTOs, tools, worker agents, deterministic workflows, kernel capability routing, and supervisor orchestration without calling external AI APIs.

Documentation

• Portuguese usage guide: docs/usage/pt-BR.md
• English usage guide: docs/usage/en.md
• Memory (English): docs/usage/memory-en.md
• Memory (Português): docs/usage/memory-pt-BR.md
• Architecture notes: docs/architecture/evolutionary-architecture.md
• Roadmap: ROADMAP.md

Support This Project

Laravel Agents is open-source and free to use. If this package saves you time, helps you ship faster, or simply sparks an idea, consider buying a coffee — it keeps the project alive and motivates new features, adapters, and documentation.