Macros & Mixins

Vizra ADK is in maintenance mode. It continues to work and receives compatibility fixes, but no new features are planned. For evaluating AI agents — now built on the official Laravel AI SDK — check out Vizra Evals, its successor for the evaluation use-case. Coming from ADK? See the migration guide.

What are Macros?

Macros allow you to add custom methods to classes at runtime. This is a powerful extensibility pattern borrowed from Laravel that lets you extend Vizra ADK’s functionality without modifying the core code.

Custom Tracking

Add analytics and tracking to your agents

Third-party Integrations

Integrate with external services seamlessly

Domain Logic

Add business-specific functionality

Reusable Patterns

Create patterns you can use across your app

Supported Classes

The following Vizra ADK classes support macros:

Class	Access	Description
`AgentManager`	`Agent` facade	Central agent management
`AgentBuilder`	Fluent builder	Agent configuration and registration
`WorkflowManager`	`Workflow` facade	Workflow orchestration

Basic Usage

Registering a Macro

app/Providers/AppServiceProvider.php

<?php

namespace App\Providers;

use Vizra\VizraADK\Services\AgentBuilder;
use Vizra\VizraADK\Facades\Agent;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Add a tracking macro for analytics
        AgentBuilder::macro('track', function (Model $model) {
            $this->trackedModel = $model;
            return $this; // Return $this for method chaining
        });
    }
}

Using Your Macro

use App\Models\Unit;
use Vizra\VizraADK\Facades\Agent;

// Step 1: Use the macro when registering the agent
Agent::build(CustomerSupportAgent::class)
    ->track(Unit::find(12))
    ->register();

// Step 2: Run the agent using the executor API
$response = CustomerSupportAgent::run('User input')
    ->forUser($user)
    ->go();

Always return $this from your macros to maintain the fluent interface and enable method chaining.

Real-World Examples

Analytics Tracking

Track which models are using AI features:

use Vizra\VizraADK\Services\AgentBuilder;
use Illuminate\Database\Eloquent\Model;

AgentBuilder::macro('track', function (Model $model) {
    $this->trackedModel = $model;
    $this->trackedModelType = get_class($model);
    $this->trackedModelId = $model->getKey();
    return $this;
});

// Usage
Agent::build(MyAgent::class)
    ->track(Unit::find(12))
    ->register();

// Then run the agent
MyAgent::run('User input')
    ->forUser($user)
    ->go();

Conditional Execution

Add conditional logic to your builder:

AgentBuilder::macro('whenCondition', function ($condition, callable $callback) {
    if ($condition) {
        $callback($this);
    }
    return $this;
});

// Usage
$agentName = Agent::define('conditional-agent')
    ->whenCondition($user->isPremium(), function ($builder) {
        $builder->model('gpt-4o');
    })
    ->whenCondition(!$user->isPremium(), function ($builder) {
        $builder->model('gpt-4o-mini');
    })
    ->register();

// Run the defined agent
Agent::named($agentName)->run('User input')->go();

Metadata Tagging

Add metadata for logging or debugging:

AgentBuilder::macro('withTags', function (array $tags) {
    $this->tags = $tags;
    return $this;
});

AgentBuilder::macro('withPriority', function (string $priority) {
    $this->priority = $priority;
    return $this;
});

// Usage
$agentName = Agent::define('support-agent')
    ->withTags(['customer-facing', 'urgent'])
    ->withPriority('high')
    ->register();

// Run the agent
Agent::named($agentName)->run('User input')->go();

Cost Tracking

Track estimated costs for budget monitoring:

AgentBuilder::macro('trackCost', function (string $costCenter) {
    $this->costCenter = $costCenter;
    $this->trackTokenUsage = true;
    return $this;
});

// Usage
Agent::build(AnalyticsAgent::class)
    ->trackCost('DEPT-001')
    ->register();

// Run the agent
AnalyticsAgent::run('User input')->go();

Using Mixins

Mixins allow you to add multiple macros at once by grouping related functionality in a class:

app/Mixins/AnalyticsMixin.php

<?php

namespace App\Mixins;

use Illuminate\Database\Eloquent\Model;

class AnalyticsMixin
{
    public function track()
    {
        return function (Model $model) {
            $this->trackedModel = $model;
            return $this;
        };
    }

    public function recordActivity()
    {
        return function ($activity) {
            $this->activityLog[] = $activity;
            return $this;
        };
    }

    public function getActivityLog()
    {
        return function () {
            return $this->activityLog ?? [];
        };
    }
}

app/Providers/AppServiceProvider.php

use Vizra\VizraADK\Services\AgentBuilder;
use App\Mixins\AnalyticsMixin;

public function boot(): void
{
    AgentBuilder::mixin(new AnalyticsMixin());
}

Now use all the mixed-in methods:

$agentName = Agent::define('analytics-agent')
    ->track($unit)
    ->recordActivity('agent_created')
    ->recordActivity('agent_configured')
    ->register();

// Run the agent
Agent::named($agentName)->run('User input')->go();

Mixins are ideal when you have a group of related macros that logically belong together, such as analytics, auditing, or domain-specific operations.

Advanced Patterns

Integration with Events

Combine macros with Laravel events for powerful side effects:

use App\Events\AgentTracked;

AgentBuilder::macro('trackWithEvent', function (Model $model) {
    $this->trackedModel = $model;

    // Fire an event when the agent is used
    event(new AgentTracked($model, $this));

    return $this;
});

Dynamic Configuration

Load configuration dynamically from your models:

AgentBuilder::macro('configureFor', function (Model $model) {
    // Load model-specific configuration
    $config = $model->agentConfiguration ?? [];

    if (isset($config['model'])) {
        $this->model($config['model']);
    }

    if (isset($config['instructions'])) {
        $this->instructions($config['instructions']);
    }

    return $this;
});

// Usage
Agent::build(MyAgent::class)
    ->configureFor($tenant)
    ->register();

// Run the agent
MyAgent::run('User input')->go();

Workflow Macros

Add custom workflow types using the WorkflowManager:

use Vizra\VizraADK\Facades\Workflow;
use Vizra\VizraADK\Services\WorkflowManager;

WorkflowManager::macro('retryable', function (string $agentClass, int $maxRetries = 3) {
    $retries = $maxRetries;
    return Workflow::loop($agentClass)
        ->until(function ($result) use (&$retries) {
            return $result->success || $retries-- <= 0;
        });
});

// Usage
$result = Workflow::retryable(UnreliableAgent::class, 5)->go();

Best Practices

Return $this

Always return $this to maintain the fluent interface

Register Early

Descriptive Names

Use clear, descriptive names for your macros

Document Well

Document macros for other developers on your team

Additional tips:

Consider scope - Macros are global, so namespace them if needed to avoid conflicts
Test your macros - Write tests to ensure macros work as expected
Group related macros - Use mixins to organize related functionality

Testing Macros

Test your macros using Pest or PHPUnit:

tests/Feature/MacroTest.php

use Vizra\VizraADK\Services\AgentBuilder;
use Vizra\VizraADK\Facades\Agent;
use App\Models\Unit;

it('can track models with macro', function () {
    AgentBuilder::macro('track', function (Model $model) {
        $this->trackedModel = $model;
        return $this;
    });

    $model = Unit::factory()->create();
    $builder = Agent::define('test-agent')->track($model);

    expect($builder->trackedModel)->toBe($model);
});

The full test suite for macro support is available at tests/Feature/MacroSupportTest.php with 10 comprehensive tests covering all major use cases.

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

Examples

API Reference

Macros & Mixins

What are Macros?

Custom Tracking

Third-party Integrations

Domain Logic

Reusable Patterns

Supported Classes

Basic Usage

Registering a Macro

Using Your Macro

Real-World Examples

Analytics Tracking

Conditional Execution

Metadata Tagging

Cost Tracking

Using Mixins

Advanced Patterns

Integration with Events

Dynamic Configuration

Workflow Macros

Best Practices

Return $this

Register Early

Descriptive Names

Document Well

Testing Macros

Learn More

Laravel Macros Docs

Agent Builder API

​What are Macros?

Custom Tracking

Third-party Integrations

Domain Logic

Reusable Patterns

​Supported Classes

​Basic Usage

​Registering a Macro

​Using Your Macro

​Real-World Examples

​Analytics Tracking

​Conditional Execution

​Metadata Tagging

​Cost Tracking

​Using Mixins

​Advanced Patterns

​Integration with Events

​Dynamic Configuration

​Workflow Macros

​Best Practices

Return $this

Register Early

Descriptive Names

Document Well

​Testing Macros

​Learn More

Laravel Macros Docs

Agent Builder API

What are Macros?

Supported Classes

Basic Usage

Registering a Macro

Using Your Macro

Real-World Examples

Analytics Tracking

Conditional Execution

Metadata Tagging

Cost Tracking

Using Mixins

Advanced Patterns

Integration with Events

Dynamic Configuration

Workflow Macros

Best Practices

Testing Macros

Learn More