Getting Started

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.

Building AI agents has never been easier! In just a few steps, you’ll have your own intelligent agent up and running.

Installation via Composer

Let’s kick things off! First, we’ll add Vizra ADK to your Laravel project:

Terminal

composer require vizra/vizra-adk

Running the Install Command

Now let’s set everything up with our magical installation command:

Terminal

php artisan vizra:install

This command publishes config, runs migrations, sets up the web interface, and creates example agents to get you started!

Setting Up Your AI Provider

Before your agents can start thinking, they need access to an AI provider. Add your preferred AI provider’s API key to your .env file:

.env

# Choose one (or add multiple!)
OPENAI_API_KEY=your-openai-api-key-here
ANTHROPIC_API_KEY=your-anthropic-api-key-here
GEMINI_API_KEY=your-gemini-api-key-here

OpenAI

GPT-4, GPT-3.5 TurboGet API Key

Anthropic

Claude 3 ModelsGet API Key

Google

Gemini Pro ModelsGet API Key

Which Provider Should I Choose?

OpenAI: Great all-around choice, GPT-4 for complex tasks, GPT-3.5 for speed
Anthropic: Claude excels at analysis, writing, and following instructions
Google: Gemini offers great performance and generous free tier

Don’t worry - you can switch providers anytime or use different ones for different agents!

Vizra ADK supports 10+ AI providers through Prism PHP, including DeepSeek, Mistral, Groq, and more. See all providers

5-Minute Quick Start: Build a Smart Assistant

Let’s build something real! In just 5 minutes, you’ll create an intelligent FAQ assistant that can answer questions about your product.

Step 1: Create the Agent

Terminal

php artisan vizra:make:agent ProductAssistant

Agent created at app/Agents/ProductAssistant.php

Step 2: Configure Your Agent

Open the agent file and give it some personality and knowledge:

app/Agents/ProductAssistant.php

<?php

namespace App\Agents;

use Vizra\VizraADK\Agents\BaseLlmAgent;

class ProductAssistant extends BaseLlmAgent
{
    protected string $name = 'product_assistant';

    protected string $description = 'Helps users understand our product features and pricing';

    protected string $instructions = "You are a helpful product assistant for AcmeApp.

        Key product information:
        - AcmeApp is a project management tool for teams
        - Pricing: Free for up to 5 users, $10/user/month for larger teams
        - Features: Task management, team collaboration, time tracking, reporting
        - Integrations: Slack, GitHub, Google Calendar

        Be friendly, concise, and always try to be helpful. If you don't know
        something, be honest about it.";

    // Use GPT-3.5 for quick responses
    protected string $model = 'gpt-3.5-turbo';
    protected ?float $temperature = 0.7;
}

Step 3: Test Your Agent

You have three ways to test your new agent:

Command Line
Web Interface
API Endpoints

Terminal

php artisan vizra:chat product_assistant

Visit http://your-app.test/vizra for a beautiful chat interface with trace debugging!

OpenAI-Compatible (use with any OpenAI tool!):

curl -X POST http://your-app.test/api/vizra-adk/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "product_assistant",
    "messages": [{"role": "user", "content": "What is AcmeApp?"}]
  }'

Native Vizra API:

curl -X POST http://your-app.test/api/vizra-adk/interact \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "product_assistant", "input": "What is AcmeApp?"}'

The web interface is perfect for development - you can see traces, debug tool calls, and test conversations visually!

Step 4: Use in Your Application

Use your assistant within Laravel:

routes/web.php

use App\Agents\ProductAssistant;

$response = ProductAssistant::run($request->input('message'))
    ->forUser(auth()->user())
    ->go();

Your agent automatically maintains conversation history per user!

Congratulations! You Did It!

In just 5 minutes, you’ve created an AI assistant that can answer questions about your product. But this is just the beginning! Your agent can do so much more:

Add custom tools to let it search databases, send emails, or call APIs
Delegate tasks to sub agents
Enable vector memory to give it knowledge from your documentation
Create workflows to handle complex multi-step processes
Run evaluations to ensure quality at scale

Common Issues & Quick Fixes

”Invalid API Key” or “Unauthorized” Errors

This is the most common issue! Here’s how to fix it:

Check your .env file has the correct API key (no extra spaces!)
Clear config cache: php artisan config:clear
Verify the API key is active in your provider’s dashboard
For OpenAI: Ensure you have billing set up (even for free tier)

“Agent Not Found” Errors

Make sure your agent class extends BaseLlmAgent
Agent file must be in app/Agents/ directory
Class name must match filename (PSR-4 autoloading)
Run composer dump-autoload if needed

Database/Migration Issues

If you see database errors:

Terminal

# Reset and re-run migrations
php artisan migrate:fresh
php artisan vizra:install

This will reset your database! Use with caution in production.

Next Steps

Configuration

Fine-tune Vizra ADK to match your project’s needs perfectly

Understanding Agents

Master the art of building intelligent AI agents

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

Examples

API Reference

Getting Started

Installation via Composer

Running the Install Command

Setting Up Your AI Provider

OpenAI

Anthropic

Google

Which Provider Should I Choose?

5-Minute Quick Start: Build a Smart Assistant

Step 1: Create the Agent

Step 2: Configure Your Agent

Step 3: Test Your Agent

Step 4: Use in Your Application

Congratulations! You Did It!

Common Issues & Quick Fixes

”Invalid API Key” or “Unauthorized” Errors

“Agent Not Found” Errors

Database/Migration Issues

Next Steps

Configuration

Understanding Agents

​Installation via Composer

​Running the Install Command

​Setting Up Your AI Provider

OpenAI

Anthropic

Google

​Which Provider Should I Choose?

​5-Minute Quick Start: Build a Smart Assistant

​Step 1: Create the Agent

​Step 2: Configure Your Agent

​Step 3: Test Your Agent

​Step 4: Use in Your Application

​Congratulations! You Did It!

​Common Issues & Quick Fixes

​”Invalid API Key” or “Unauthorized” Errors

​“Agent Not Found” Errors

​Database/Migration Issues

​Next Steps

Configuration

Understanding Agents

Installation via Composer

Running the Install Command

Setting Up Your AI Provider

Which Provider Should I Choose?

5-Minute Quick Start: Build a Smart Assistant

Step 1: Create the Agent

Step 2: Configure Your Agent

Step 3: Test Your Agent

Step 4: Use in Your Application

Congratulations! You Did It!

Common Issues & Quick Fixes

”Invalid API Key” or “Unauthorized” Errors

“Agent Not Found” Errors

Database/Migration Issues

Next Steps