PHPackages                             andmarruda/laravel-agents - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. andmarruda/laravel-agents

ActiveLibrary[Utility & Helpers](/categories/utility)

andmarruda/laravel-agents
=========================

Laravel-native AI agents, supervisor orchestration, tools, and model routing.

0.9(3w ago)19MITPHPPHP >=8.2

Since Jun 5Pushed 3w agoCompare

[ Source](https://github.com/andmarruda/laravel-agents)[ Packagist](https://packagist.org/packages/andmarruda/laravel-agents)[ RSS](/packages/andmarruda-laravel-agents/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (8)Used By (0)

Laravel Agents
==============

[](#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
--------------

[](#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
------------

[](#planned-next)

- Streaming and structured output helpers.

See [ROADMAP.md](ROADMAP.md) for the version plan.

RAG documentation: [English](docs/usage/rag-en.md) | [Português](docs/usage/rag-pt-BR.md).

Guardrails documentation: [English](docs/usage/guardrails-en.md) | [Português](docs/usage/guardrails-pt-BR.md).

Installation
------------

[](#installation)

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

```
composer require andmarruda/laravel-agents
```

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

```
{
    "repositories": [
        {
            "type": "path",
            "url": "../laravel-agents",
            "options": {
                "symlink": true
            }
        }
    ]
}
```

Then require it:

```
composer require andmarruda/laravel-agents:@dev
```

Publish the config:

```
php artisan vendor:publish --tag=agents-config
```

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

```
php artisan vendor:publish --tag=agents-migrations
php artisan migrate
```

Configure at least one provider:

```
AGENTS_DEFAULT_MODEL=openai/gpt-4.1-mini
AGENTS_MODEL_TIMEOUT=60
AGENTS_MODEL_RETRY_TIMES=2
AGENTS_MODEL_RETRY_SLEEP=250
AGENTS_IMAGE_MODEL=openai/gpt-image-1
AGENTS_IMAGE_SIZE=1024x1024
AGENTS_IMAGE_DISK=public
AGENTS_BILLING_PROVIDER=openai

OPENAI_API_KEY=
ANTHROPIC_API_KEY=
FIREWORKS_API_KEY=
```

Model Names
-----------

[](#model-names)

Use the `provider/model` format:

```
LaravelAgents::model('openai/gpt-4.1-mini');
LaravelAgents::model('anthropic/claude-sonnet-4');
LaravelAgents::model('fireworks/accounts/fireworks/models/llama-v3p1-70b-instruct');
```

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

- `OpenAiModelAdapter`
- `AnthropicModelAdapter`
- `FireworksModelAdapter`

Image Generation
----------------

[](#image-generation)

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

```
use Andmarruda\LaravelAgents\Data\ImageGenerationRequest;
use Andmarruda\LaravelAgents\Facades\LaravelAgents;

$response = LaravelAgents::image('openai/gpt-image-1')
    ->generate(new ImageGenerationRequest(
        prompt: 'A clean Laravel agent orchestration diagram',
        size: '1024x1024',
    ));

$url = $response->firstUrl();
$base64 = $response->firstBase64();
```

You can also go through the kernel:

```
$image = LaravelAgents::kernel()
    ->image()
    ->generate(new ImageGenerationRequest(prompt: 'A product launch illustration'));
```

Billing And Usage
-----------------

[](#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.

```
use Andmarruda\LaravelAgents\Data\Billing\BillingQuery;
use Andmarruda\LaravelAgents\Facades\LaravelAgents;

$costs = LaravelAgents::billing('openai')->costs(new BillingQuery(
    startTime: '2026-06-01',
    endTime: '2026-07-01',
    bucketWidth: '1d',
));

$completions = LaravelAgents::billing()->usage('completions', new BillingQuery(
    startTime: now()->subWeek(),
    endTime: now(),
    bucketWidth: '1d',
    groupBy: 'model',
));
```

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
------------

[](#worker-agent)

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

```