Configuration

🎨

Configuration Made Simple!

Think of configuration as painting your masterpiece! 🖌️ With Vizra ADK, you have all the colors (options) at your fingertips. Let's make your AI agents work exactly how you want them to!

📁 Your Configuration Hub

After installing Vizra ADK, your shiny new configuration file lives at:

config/vizra-adk.php

💡 Pro tip: Haven't published it yet? No worries! Run this magic command:

php artisan vendor:publish --tag=vizra-adk-config

🤖 Choose Your AI Provider

🎯 Default Provider

Pick your favorite AI companion! Set it in your .env file:

VIZRA_ADK_DEFAULT_PROVIDER=openai

✨ Available Providers

Choose from these amazing AI providers:

✓ openai - GPT models

✓ anthropic - Claude models

✓ gemini - Google's finest

🎪 Pick Your Model

Choose the AI model that powers your agents' brilliance:

VIZRA_ADK_DEFAULT_MODEL=gemini-pro

🟢 OpenAI Models

gpt-4-turbo gpt-3.5-turbo

🟣 Anthropic Models

claude-3-opus-20240229 claude-3-sonnet-20240229

🔵 Google Models

gemini-pro gemini-1.5-pro

🎸 Fine-Tune Your AI's Personality

Adjust these dials to make your AI agents more creative or focused! 🎯

# Default generation parameters
VIZRA_ADK_DEFAULT_TEMPERATURE=0.7      # null uses provider default
VIZRA_ADK_DEFAULT_MAX_TOKENS=2000     # null uses provider default
VIZRA_ADK_DEFAULT_TOP_P=0.9           # null uses provider default

🌡️ Temperature

Controls creativity: 0 = focused, 1 = wild imagination!

📦 Max Tokens

Maximum response length. More tokens = longer answers!

🎩 Top P

Controls diversity. Lower = more focused responses!

🔑 Your API Keys

Time to connect to the AI magic! Add your provider API keys:

# OpenAI
OPENAI_API_KEY=your-openai-api-key

# Anthropic Claude
ANTHROPIC_API_KEY=your-anthropic-api-key

# Google Gemini
GOOGLE_API_KEY=your-google-api-key

🔒

Security First!

Never commit API keys to your repository! Keep them safe in your .env file and add it to .gitignore.

📄 The Complete Configuration Blueprint

Here's your complete configuration file in all its glory! 🎆

return [
    /**
     * Default LLM provider to use with Prism-PHP.
     * This can be overridden by specific agent configurations.
     * 
     * Supported providers:
     * - 'openai' - OpenAI (GPT-4, GPT-3.5, etc.)
     * - 'anthropic' - Anthropic (Claude models)
     * - 'gemini' or 'google' - Google Gemini
     * - 'deepseek' - DeepSeek AI
     * - 'ollama' - Ollama (local models like Llama, CodeLlama, Phi)
     * - 'mistral' - Mistral AI (Mistral, Mixtral models)
     * - 'groq' - Groq (Fast inference)
     * - 'xai' or 'grok' - xAI (Grok models)
     * - 'voyageai' or 'voyage' - Voyage AI (Embeddings)
     */
    'default_provider' => env('VIZRA_ADK_DEFAULT_PROVIDER', 'openai'),

    /**
     * Default LLM model to use with Prism-PHP.
     * This can be overridden by specific agent configurations.
     * Example: 'gemini-pro', 'gpt-4-turbo', 'claude-3-opus-20240229'
     */
    'default_model' => env('VIZRA_ADK_DEFAULT_MODEL', 'gemini-1.5-flash'),

    /**
     * Default generation parameters for LLM requests.
     * These can be overridden by specific agent configurations.
     */
    'default_generation_params' => [
        'temperature' => env('VIZRA_ADK_DEFAULT_TEMPERATURE', null), // null means use provider default
        'max_tokens' => env('VIZRA_ADK_DEFAULT_MAX_TOKENS', null),   // null means use provider default
        'top_p' => env('VIZRA_ADK_DEFAULT_TOP_P', null),             // null means use provider default
    ],

    /**
     * Sub-agent delegation settings.
     * Controls behavior of agent hierarchies and delegation.
     */
    'max_delegation_depth' => env('VIZRA_ADK_MAX_DELEGATION_DEPTH', 5), // Maximum depth for nested sub-agent delegation

    /**
     * Database table names used by the package.
     */
    'tables' => [
        'agent_sessions' => 'agent_sessions',
        'agent_messages' => 'agent_messages',
        'agent_memories' => 'agent_memories',
        'agent_vector_memories' => 'agent_vector_memories',
        'agent_trace_spans' => 'agent_trace_spans',
    ],

    /**
     * Tracing configuration.
     */
    'tracing' => [
        'enabled' => env('VIZRA_ADK_TRACING_ENABLED', true),
        'cleanup_days' => env('VIZRA_ADK_TRACING_CLEANUP_DAYS', 30),
    ],

    /**
     * Namespaces for user-defined classes.
     */
    'namespaces' => [
        'agents' => 'App\\Agents',
        'tools' => 'App\\Tools',
        'evaluations' => 'App\\Evaluations',
    ],

    /**
     * Routes configuration.
     */
    'routes' => [
        'enabled' => true,
        'prefix' => 'api/vizra-adk',
        'middleware' => ['api'],
        'web' => [
            'enabled' => env('VIZRA_ADK_WEB_ENABLED', true),
            'prefix' => 'vizra',
            'middleware' => ['web'],
        ],
    ],

    /**
     * OpenAI API Compatibility Configuration
     * Maps OpenAI model names to your agent names for the /chat/completions endpoint.
     */
    'openai_model_mapping' => [
        'gpt-4' => env('VIZRA_ADK_OPENAI_GPT4_AGENT', 'chat_agent'),
        'gpt-4-turbo' => env('VIZRA_ADK_OPENAI_GPT4_TURBO_AGENT', 'chat_agent'),
        'gpt-3.5-turbo' => env('VIZRA_ADK_OPENAI_GPT35_AGENT', 'chat_agent'),
        'gpt-4o' => env('VIZRA_ADK_OPENAI_GPT4O_AGENT', 'chat_agent'),
        'gpt-4o-mini' => env('VIZRA_ADK_OPENAI_GPT4O_MINI_AGENT', 'chat_agent'),
        // Add more mappings as needed
    ],

    /**
     * Default agent to use when no specific mapping is found
     */
    'default_chat_agent' => env('VIZRA_ADK_DEFAULT_CHAT_AGENT', 'chat_agent'),

    /**
     * Model Context Protocol (MCP) Configuration
     * Define MCP servers that agents can connect to for enhanced capabilities.
     * 
     * Each server configuration includes:
     * - command: The command to start the MCP server
     * - args: Arguments to pass to the server command
     * - enabled: Whether this server is enabled (default: true)
     * - timeout: Connection timeout in seconds (default: 30)
     */
    'mcp_servers' => [
        'filesystem' => [
            'command' => 'npx',
            'args' => [
                '@modelcontextprotocol/server-filesystem',
                env('MCP_FILESYSTEM_PATH', storage_path('app')),
            ],
            'enabled' => env('MCP_FILESYSTEM_ENABLED', false),
            'timeout' => 30,
        ],
        
        'github' => [
            'command' => 'npx',
            'args' => [
                '@modelcontextprotocol/server-github',
                '--token',
                env('GITHUB_TOKEN', ''),
            ],
            'enabled' => env('MCP_GITHUB_ENABLED', false) && !empty(env('GITHUB_TOKEN')),
            'timeout' => 45,
        ],
        
        'postgres' => [
            'command' => 'npx',
            'args' => [
                '@modelcontextprotocol/server-postgres',
                '--connection-string',
                env('MCP_POSTGRES_URL', env('DATABASE_URL', '')),
            ],
            'enabled' => env('MCP_POSTGRES_ENABLED', false) && !empty(env('DATABASE_URL')),
            'timeout' => 30,
        ],
        
        'brave_search' => [
            'command' => 'npx',
            'args' => [
                '@modelcontextprotocol/server-brave-search',
                '--api-key',
                env('BRAVE_API_KEY', ''),
            ],
            'enabled' => env('MCP_BRAVE_SEARCH_ENABLED', false) && !empty(env('BRAVE_API_KEY')),
            'timeout' => 30,
        ],
        
        'slack' => [
            'command' => 'npx',
            'args' => [
                '@modelcontextprotocol/server-slack',
                '--bot-token',
                env('SLACK_BOT_TOKEN', ''),
            ],
            'enabled' => env('MCP_SLACK_ENABLED', false) && !empty(env('SLACK_BOT_TOKEN')),
            'timeout' => 30,
        ],

        // Example custom MCP server
        // 'custom_api' => [
        //     'command' => 'python',
        //     'args' => ['/path/to/your/mcp-server.py'],
        //     'enabled' => true,
        //     'timeout' => 60,
        // ],
    ],
];

🤝 Agent Teamwork Settings

Let your agents work together! Control how deep the delegation rabbit hole goes:

# Maximum depth for nested sub-agent delegation
VIZRA_ADK_MAX_DELEGATION_DEPTH=5

🚫

Why This Matters

This clever safety net prevents your agents from playing endless "pass the task" — avoiding infinite loops and keeping your app responsive!

🗜️ Database Architecture

Vizra ADK organizes your AI data in these neat tables:

💬 `agent_sessions`

Keeps track of all your conversation sessions

✍️ `agent_messages`

Stores the complete message history

🧠 `agent_memories`

Your agents' long-term memories live here

🔍 `agent_vector_memories`

Vector embeddings for semantic search capabilities

📊 `agent_trace_spans`

Debug traces for when you need to investigate

💡 Tip: Got naming conflicts? No worries! You can customize these table names in your config file.

🔍 Debug Like a Detective

Turn on tracing to see exactly what your agents are thinking! 🕵️‍♂️

# Enable/disable tracing
VIZRA_ADK_TRACING_ENABLED=true

# Days to keep trace data before cleanup
VIZRA_ADK_TRACING_CLEANUP_DAYS=30

🧹 Spring Cleaning Command

Keep your database tidy by removing old traces:

php artisan vizra:trace:cleanup --days=7

🌐 Web Dashboard Settings

Toggle your beautiful web dashboard on or off:

# Enable/disable web interface
VIZRA_ADK_WEB_ENABLED=true

Your shiny dashboard lives at these URLs:

🏠 Main Dashboard

/vizra

💬 Chat Interface

/vizra/chat

🏆 Evaluation Runner

/vizra/eval

🔌 OpenAI API Compatibility

Make your Vizra agents work seamlessly with OpenAI-compatible clients! Map OpenAI model names to your custom agents:

'openai_model_mapping' => [
    'gpt-4' => env('VIZRA_ADK_OPENAI_GPT4_AGENT', 'chat_agent'),
    'gpt-4-turbo' => env('VIZRA_ADK_OPENAI_GPT4_TURBO_AGENT', 'chat_agent'),
    'gpt-3.5-turbo' => env('VIZRA_ADK_OPENAI_GPT35_AGENT', 'chat_agent'),
    'gpt-4o' => env('VIZRA_ADK_OPENAI_GPT4O_AGENT', 'chat_agent'),
    'gpt-4o-mini' => env('VIZRA_ADK_OPENAI_GPT4O_MINI_AGENT', 'chat_agent'),
],

// Default agent when no mapping matches
'default_chat_agent' => env('VIZRA_ADK_DEFAULT_CHAT_AGENT', 'chat_agent'),

🎭

Why This Is Awesome

This lets any OpenAI-compatible application use your Vizra agents! Just point them to your /api/vizra-adk/chat/completions endpoint.

🚀 Model Context Protocol (MCP) Servers

Supercharge your agents with MCP servers! These give your agents access to external tools and services:

📁 Filesystem Server

# Enable filesystem access
MCP_FILESYSTEM_ENABLED=true
MCP_FILESYSTEM_PATH=/path/to/allowed/dir

Let agents read and write files safely!

🐙 GitHub Server

# Connect to GitHub
MCP_GITHUB_ENABLED=true
GITHUB_TOKEN=your-github-token

Access repos, issues, and PRs!

🐘 PostgreSQL Server

# Database access
MCP_POSTGRES_ENABLED=true
MCP_POSTGRES_URL=postgresql://...

Query and manage databases!

🔍 Brave Search Server

# Web search capabilities
MCP_BRAVE_SEARCH_ENABLED=true
BRAVE_API_KEY=your-brave-api-key

Search the web for real-time info!

⚙️ Custom MCP Servers

You can even add your own MCP servers! Here's an example:

'custom_api' => [
    'command' => 'python',
    'args' => ['/path/to/your/mcp-server.py'],
    'enabled' => true,
    'timeout' => 60,
],

🏆 The Configuration Priority Game

🎯 Who Wins? The Priority Order!

When multiple configs compete, here's who takes the crown (from highest to lowest priority):

1st

Runtime Methods

$agent->setTemperature(0.2)

The boss! Always wins.

2nd

Agent Class Properties

protected ?float $temperature = 0.7;

The deputy! Steps in when the boss is away.

3rd

Environment Variables

VIZRA_ADK_DEFAULT_TEMPERATURE=0.5

The default go-to for most situations.

4th

Config File Defaults

config/vizra-adk.php

The fallback! Always there when needed.

📦 Organize Your Code

Keep your code neat and tidy with these default namespaces:

🤖 Agents

App\Agents

🔧 Tools

App\Tools

📊 Evaluations

App\Evaluations

🎨 Feeling creative? You can totally customize these namespaces in your config file to match your project's vibe!

🌍 Environment Magic

Different settings for different environments? We've got you covered! 🎩✨

💻 Local Development

# .env.local
VIZRA_ADK_TRACING_ENABLED=true
VIZRA_ADK_DEFAULT_MODEL=gpt-3.5-turbo
VIZRA_ADK_WEB_ENABLED=true

Debug everything, use cheaper models!

🚀 Production

# .env.production
VIZRA_ADK_TRACING_ENABLED=false
VIZRA_ADK_DEFAULT_MODEL=gpt-4-turbo
VIZRA_ADK_WEB_ENABLED=false

Optimized for performance & security!

🎉 You're All Set!

Congratulations! Your Vizra ADK is now perfectly configured. Time to build some amazing AI agents! Remember, configuration is just the beginning of your journey. Let's explore what's next...

🤖 Next: Build Your First Agent

Learn how to create intelligent agents that can think, remember, and solve problems!

Start building →

⚡ Master the CLI

Discover powerful Artisan commands to supercharge your development workflow!

Explore commands →