PHPackages                             undergrace/laravel-mbc - 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. undergrace/laravel-mbc

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

undergrace/laravel-mbc
======================

Model Backend Controller - AI agent orchestration protocol for Laravel

v0.2.0(4mo ago)238MITPHPPHP ^8.3

Since Feb 21Pushed 4mo agoCompare

[ Source](https://github.com/etazza2025/laravel-mbc)[ Packagist](https://packagist.org/packages/undergrace/laravel-mbc)[ RSS](/packages/undergrace-laravel-mbc/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (12)Versions (3)Used By (0)

MBC — Model Backend Controller
==============================

[](#mbc--model-backend-controller)

**AI Agent Orchestration Protocol for Laravel**

MBC allows your Laravel backend to orchestrate AI agents as autonomous workers with tools, server-side — no desktop client needed.

🎬 **\[Watch Demo: 3 AI Agents Build a Website in 34s for $0.34\] ([https://youtu.be/A\_GiAqIWJxE](https://youtu.be/A_GiAqIWJxE))**

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

[](#installation)

```
composer require undergrace/laravel-mbc
```

Publish the configuration:

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

Run migrations:

```
php artisan migrate
```

Configuration
-------------

[](#configuration)

Add your API keys to `.env` depending on the provider you want to use:

```
# Default provider (anthropic, openai, or openrouter)
MBC_PROVIDER=anthropic

# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI (GPT-4o, o1, o3)
OPENAI_API_KEY=sk-...

# OpenRouter (200+ models: Claude, GPT, Gemini, Llama, Mistral, DeepSeek...)
OPENROUTER_API_KEY=sk-or-...
```

Supported Providers
-------------------

[](#supported-providers)

ProviderModelsTool UseConfig Key**Anthropic**Claude Sonnet 4.5, Opus 4, Haiku 3.5Native`anthropic`**OpenAI**GPT-4o, o1, o3, o3-miniNative`openai`**OpenRouter**200+ models from all providersOpenAI-compatible`openrouter`Set the default provider in `config/mbc.php`:

```
'default_provider' => env('MBC_PROVIDER', 'anthropic'),
```

Quick Start
-----------

[](#quick-start)

```
use Undergrace\Mbc\Facades\Mbc;

$session = Mbc::session('my-agent')
    ->systemPrompt('You are an assistant that helps organize data.')
    ->tools([
        ListItemsTool::class,
        CreateReportTool::class,
    ])
    ->context(['user_id' => 1, 'department' => 'sales'])
    ->config(maxTurns: 20, model: 'claude-sonnet-4-5-20250929')
    ->start('Analyze the sales data and create a summary report.');

$result = $session->result();
echo $result->finalMessage;
```

### Using Different Providers Per Session

[](#using-different-providers-per-session)

```
// Claude via Anthropic (direct)
Mbc::session('designer')
    ->config(model: 'claude-sonnet-4-5-20250929')
    ->start('Design the database schema.');

// GPT-4o via OpenAI
Mbc::session('copywriter')
    ->config(model: 'gpt-4o')
    ->start('Write compelling product descriptions.');

// Any model via OpenRouter
Mbc::session('analyst')
    ->config(model: 'anthropic/claude-sonnet-4')
    ->start('Analyze quarterly data.');

// Gemini via OpenRouter
Mbc::session('researcher')
    ->config(model: 'google/gemini-2.5-pro')
    ->start('Research market trends.');
```

Creating Tools
--------------

[](#creating-tools)

Generate a tool scaffold:

```
php artisan mbc:make-tool AnalyzeDataTool
```

Define tools with PHP Attributes:

```
use Undergrace\Mbc\Tools\Attributes\Tool;
use Undergrace\Mbc\Tools\Attributes\ToolParam;
use Undergrace\Mbc\Tools\BaseTool;

#[Tool(
    name: 'analyze_data',
    description: 'Analyzes data from the specified table and returns statistics'
)]
class AnalyzeDataTool extends BaseTool
{
    public function __construct(
        private DataRepository $dataRepo,
    ) {}

    #[ToolParam(name: 'table', type: 'string', description: 'Table name to analyze', required: true)]
    #[ToolParam(name: 'metric', type: 'string', description: 'Metric to calculate', enum: ['avg', 'sum', 'count'])]
    public function execute(array $input): mixed
    {
        return $this->dataRepo->analyze($input['table'], $input['metric']);
    }
}
```

Inter-Agent Communication
-------------------------

[](#inter-agent-communication)

MBC provides three patterns for multi-agent collaboration:

### Pipeline (Sequential Chaining)

[](#pipeline-sequential-chaining)

Each agent receives the previous agent's result as context. Ideal for workflows where Agent A's output feeds into Agent B.

```
use Undergrace\Mbc\Core\MbcPipeline;

$result = MbcPipeline::create()
    ->pipe($architectSession, 'Design the database schema')
    ->pipe($backendSession, 'Implement the API based on the schema')
    ->pipe($frontendSession, 'Create the UI components for the API')
    ->run();

if ($result->successful()) {
    echo $result->final()->finalMessage;
}

echo "Total cost: $" . $result->totalCost();
echo "Stages: " . $result->stageCount();
```

### Orchestrator (Parallel Execution)

[](#orchestrator-parallel-execution)

Run multiple agents simultaneously and collect results. Ideal for independent tasks that can execute in parallel.

```
use Undergrace\Mbc\Core\MbcOrchestrator;

// Async via queue
$orchestrator = MbcOrchestrator::create('build-site')
    ->agent($designerSession, 'Design the layout')
    ->agent($copywriterSession, 'Write the content')
    ->agent($seoSession, 'Optimize for search engines')
    ->dispatch();

// Check progress
$progress = $orchestrator->progress();
// ['total' => 3, 'completed' => 2, 'running' => 1, 'failed' => 0, 'pending' => 0]

// Collect when done
if ($orchestrator->isComplete()) {
    $results = $orchestrator->results();
    echo "Total cost: $" . $results->totalCost();
}

// Or run synchronously (blocking)
$results = MbcOrchestrator::create('quick-task')
    ->agent($agentA, 'Task A')
    ->agent($agentB, 'Task B')
    ->runSync();
```

### Sub-Agents (Spawn from within a Session)

[](#sub-agents-spawn-from-within-a-session)

An agent can spawn specialized sub-agents during execution using the built-in `SpawnAgentTool`.

```
use Undergrace\Mbc\Tools\SpawnAgentTool;

$spawnTool = new SpawnAgentTool();
$spawnTool
    ->register(
        name: 'researcher',
        systemPrompt: 'You research and gather information.',
        toolClasses: [WebSearchTool::class, ReadFileTool::class],
        maxTurns: 10,
    )
    ->register(
        name: 'writer',
        systemPrompt: 'You write content based on research.',
        toolClasses: [WriteFileTool::class],
        maxTurns: 15,
    );

$session = Mbc::session('coordinator')
    ->systemPrompt('You coordinate research and writing tasks. Use spawn_agent to delegate.')
    ->tools([
        $spawnTool,
        OtherTool::class,
    ])
    ->start('Research and write an article about Laravel.');
```

### Shared Context (Memory between Agents)

[](#shared-context-memory-between-agents)

Agents can share data through a key-value store backed by Laravel's cache system.

```
use Undergrace\Mbc\Core\MbcContext;

// In Agent A's tool
$ctx = new MbcContext('project-123');
$ctx->set('schema', $databaseSchema);
$ctx->push('decisions', 'Use PostgreSQL for main DB');

// In Agent B's tool (same namespace)
$ctx = new MbcContext('project-123');
$schema = $ctx->get('schema');
$decisions = $ctx->get('decisions'); // ['Use PostgreSQL for main DB']

// Get everything
$all = $ctx->all();

// Clean up when done
$ctx->flush();
```

Background Execution
--------------------

[](#background-execution)

```
use Undergrace\Mbc\Jobs\RunMbcSessionJob;

$session = Mbc::session('background-agent')
    ->systemPrompt('...')
    ->tools([...])
    ->context([...]);

RunMbcSessionJob::dispatch(
    $session->toSerializable(),
    'Your initial message here'
);
```

The job includes automatic retry logic (3 attempts with 10s, 30s, 60s backoff) and zombie session cleanup on failure.

Middleware
----------

[](#middleware)

MBC includes built-in middleware and supports custom middleware:

```
use Undergrace\Mbc\Middleware\LogTurns;
use Undergrace\Mbc\Middleware\CostTracker;
use Undergrace\Mbc\Middleware\RateLimiter;

$session = Mbc::session('with-middleware')
    ->middleware([
        LogTurns::class,
        CostTracker::class,
        RateLimiter::max(30),
    ])
    ->start('...');
```

MiddlewareDescription`LogTurns`Logs each turn's response metadata and optionally full text`CostTracker`Tracks cumulative token usage and estimated cost per session`RateLimiter`Throws exception if session exceeds max turns`VisualFeedback`Captures screenshots for visual feedback loopsGlobal middleware can be configured in `config/mbc.php`:

```
'middleware' => [
    LogTurns::class,
    CostTracker::class,
],
```

Scalability Features
--------------------

[](#scalability-features)

### Context Window Management

[](#context-window-management)

Sessions automatically trim old messages when approaching the context window limit, preserving the initial context and most recent turns:

```
$session = Mbc::session('long-task')
    ->config(
        maxTurns: 50,
        // Context window settings (defaults shown)
        // contextWindowLimit: 150000,
        // contextReserveTokens: 20000,
    )
    ->start('...');
```

### Concurrency Guard

[](#concurrency-guard)

Prevents overloading the system with too many simultaneous sessions:

```
// config/mbc.php
'limits' => [
    'max_concurrent_sessions' => 10,
],
```

### Zombie Session Cleanup

[](#zombie-session-cleanup)

Sessions stuck in RUNNING state are automatically handled:

```
# Mark sessions stuck for 60+ minutes as FAILED
php artisan mbc:cleanup

# Custom timeout
php artisan mbc:cleanup --timeout=30

# Also prune old sessions
php artisan mbc:cleanup --prune
```

Schedule it in your `routes/console.php` or kernel:

```
Schedule::command('mbc:cleanup --prune')->hourly();
```

### Dynamic Cost Tracking

[](#dynamic-cost-tracking)

Costs are estimated per model using `ModelPricing`, supporting all providers:

```
use Undergrace\Mbc\Core\ModelPricing;

$cost = ModelPricing::estimate('claude-sonnet-4-5-20250929', inputTokens: 50000, outputTokens: 10000);
// $0.30

$cost = ModelPricing::estimate('google/gemini-2.5-flash', inputTokens: 50000, outputTokens: 10000);
// $0.01
```

Persistence
-----------

[](#persistence)

All sessions and turns are stored in the database by default:

- **`mbc_sessions`** — Session metadata, status, cost, result
- **`mbc_turns`** — Each turn's content, tool calls, tool results, tokens

Configure in `config/mbc.php`:

```
'storage' => [
    'persist_sessions' => true,
    'persist_turns' => true,
    'prune_after_days' => 30,
],
```

Artisan Commands
----------------

[](#artisan-commands)

```
# Generate a new tool
php artisan mbc:make-tool {ToolName}

# Check session status
php artisan mbc:session-status {uuid}

# Replay a previous session
php artisan mbc:replay {uuid}

# Cleanup zombie sessions and prune old data
php artisan mbc:cleanup [--timeout=60] [--prune]
```

Real-time Broadcasting (WebSockets)
-----------------------------------

[](#real-time-broadcasting-websockets)

MBC broadcasts all agent events via Laravel's broadcasting system. Works with Reverb, Pusher, Ably, or any supported driver.

Enable in `.env`:

```
MBC_BROADCASTING_ENABLED=true
```

### Listening to a specific agent

[](#listening-to-a-specific-agent)

Channels are private — only authenticated users can subscribe:

```
Echo.private('mbc.sessions.' + uuid)
    .listen('MbcSessionStarted', (e) => {
        console.log('Agent started:', e.session_name);
    })
    .listen('MbcTurnCompleted', (e) => {
        console.log('Turn', e.turn_number, '- Stop:', e.stop_reason);
    })
    .listen('MbcToolExecuted', (e) => {
        console.log('Tool:', e.tool_name, '- Duration:', e.duration_ms + 'ms');
    })
    .listen('MbcSessionCompleted', (e) => {
        console.log('Done! Cost: $' + e.estimated_cost_usd);
    })
    .listen('MbcSessionFailed', (e) => {
        console.error('Session failed');
    });
```

### Monitoring all agents (dashboard)

[](#monitoring-all-agents-dashboard)

```
Echo.private('mbc.monitor')
    .listen('MbcSessionStarted', (e) => {
        // New agent started working
    })
    .listen('MbcSessionCompleted', (e) => {
        // Agent finished
    });
```

### Events broadcast data

[](#events-broadcast-data)

EventData`MbcSessionStarted`session\_uuid, session\_name, timestamp`MbcTurnCompleted`session\_uuid, turn\_number, type, stop\_reason, timestamp`MbcToolExecuted`session\_uuid, tool\_name, is\_error, duration\_ms, timestamp`MbcSessionCompleted`session\_uuid, status, final\_message, total\_turns, total\_tokens, estimated\_cost\_usd, timestamp`MbcSessionFailed`session\_uuid, timestampConfigure the channel prefix in `config/mbc.php`:

```
'broadcasting' => [
    'enabled' => env('MBC_BROADCASTING_ENABLED', false),
    'channel_prefix' => 'mbc',
],
```

REST API
--------

[](#rest-api)

Read-only API endpoints for querying sessions, turns, and stats. Enable in `.env`:

```
MBC_API_ENABLED=true
```

### Endpoints

[](#endpoints)

MethodURIDescriptionGET`/mbc/sessions`List sessions (filters: status, from, to, name, model)GET`/mbc/sessions/{uuid}`Session detail with turnsGET`/mbc/sessions/{uuid}/turns`Paginated turn timelineGET`/mbc/stats`Aggregate stats (costs, tokens, counts)GET`/mbc/agents/active`Currently running/pending sessions### Configuration

[](#configuration-1)

API endpoints are protected with `auth:sanctum` and rate limited (60 req/min) by default:

```
// config/mbc.php
'api' => [
    'enabled' => env('MBC_API_ENABLED', false),
    'prefix' => 'mbc',
    'middleware' => ['api', 'auth:sanctum', 'throttle:60,1'],
],
```

### Example requests

[](#example-requests)

```
# List running sessions
curl /mbc/sessions?status=running

# Get session detail with turns
curl /mbc/sessions/550e8400-e29b-41d4-a716-446655440000

# Get turns timeline
curl /mbc/sessions/550e8400.../turns?per_page=20

# Get aggregate stats for a date range
curl /mbc/stats?from=2026-02-01&to=2026-02-28

# Get active agents
curl /mbc/agents/active
```

Logging
-------

[](#logging)

MBC auto-registers its own log channel. Logs are written to `storage/logs/mbc.log`:

```
// config/mbc.php
'logging' => [
    'channel' => 'mbc',
    'log_prompts' => env('MBC_LOG_PROMPTS', false),
    'log_responses' => env('MBC_LOG_RESPONSES', false),
],
```

Security
--------

[](#security)

MBC includes several security measures:

- **Authenticated API** — All REST endpoints require `auth:sanctum` with rate limiting (60 req/min)
- **Private broadcast channels** — WebSocket channels require authenticated users
- **Sanitized error messages** — Internal errors are logged but not exposed to AI responses or broadcasts
- **API key validation** — Providers throw early if API keys are missing, preventing silent failures
- **Safe serialization** — Inter-process communication uses JSON instead of PHP `serialize/unserialize`
- **Filtered API responses** — Sensitive fields (`system_prompt`, `context`, raw `error`) are excluded from REST responses

### Reporting Vulnerabilities

[](#reporting-vulnerabilities)

If you discover a security vulnerability, please report it via GitHub Issues.

License
-------

[](#license)

MIT - UNDERGRACE LABS

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance76

Regular maintenance activity

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

2

Last Release

130d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8b8caeddd442e152d00f83e26f6d47521299c96566b374e160b018ae81a83259?d=identicon)[etazza2025](/maintainers/etazza2025)

---

Top Contributors

[![etazza2025](https://avatars.githubusercontent.com/u/232264171?v=4)](https://github.com/etazza2025 "etazza2025 (12 commits)")

---

Tags

antrophicantropiciaia-agentlaravelmulti-agentopenaiorchestrationphptool-use

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/undergrace-laravel-mbc/health.svg)

```
[![Health](https://phpackages.com/badges/undergrace-laravel-mbc/health.svg)](https://phpackages.com/packages/undergrace-laravel-mbc)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[api-platform/laravel

API Platform support for Laravel

58171.8k14](/packages/api-platform-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1235.9k20](/packages/fleetbase-core-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)