Error Handling

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.

Exception Types

The framework includes three specialized exception classes that extend PHP’s base \Exception class:

AgentNotFoundException

Thrown when attempting to access or execute an agent that doesn’t exist in the registry.

AgentRegistry.php

use Vizra\VizraADK\Exceptions\AgentNotFoundException;

// Example from AgentRegistry::getAgent()
if (!isset($this->registeredAgents[$name])) {
    throw new AgentNotFoundException("Agent '{$name}' is not registered.");
}

AgentConfigurationException

Thrown when there are issues with agent configuration, such as invalid settings or missing required parameters.

Configuration Validation

use Vizra\VizraADK\Exceptions\AgentConfigurationException;

// Example usage
if (!class_exists($config)) {
    throw new AgentConfigurationException(
        "Agent class '{$config}' does not exist."
    );
}

ToolExecutionException

Thrown when errors occur during tool execution, including invalid parameters or runtime failures.

Tool Execution

use Vizra\VizraADK\Exceptions\ToolExecutionException;

// Example in tool execution
try {
    $result = $tool->execute($arguments, $context);
} catch (\Exception $e) {
    throw new ToolExecutionException(
        "Tool '{$toolName}' failed: " . $e->getMessage()
    );
}

Handling Exceptions in Controllers

The AgentApiController demonstrates comprehensive exception handling:

AgentApiController.php

use Vizra\VizraADK\Facades\Agent;
use Vizra\VizraADK\Exceptions\AgentNotFoundException;
use Vizra\VizraADK\Exceptions\ToolExecutionException;
use Vizra\VizraADK\Exceptions\AgentConfigurationException;

class AgentApiController extends Controller
{
    public function handleAgentInteraction(Request $request): JsonResponse
    {
        try {
            // Check if agent exists
            if (!Agent::hasAgent($agentName)) {
                return response()->json([
                    'error' => "Agent '{$agentName}' is not registered or found.",
                    'message' => "Please ensure the agent is registered..."
                ], 404);
            }

            // Execute agent
            $response = Agent::run($agentName, $input, $sessionId);

            return response()->json([
                'agent_name' => $agentName,
                'session_id' => $sessionId,
                'response' => $response,
            ]);

        } catch (AgentNotFoundException $e) {
            logger()->error("Agent not found: " . $e->getMessage());
            return response()->json([
                'error' => "Agent '{$agentName}' could not be found or loaded.",
                'detail' => $e->getMessage()
            ], 404);

        } catch (ToolExecutionException $e) {
            logger()->error("Tool execution error for agent {$agentName}: " . $e->getMessage(), [
                'exception' => $e
            ]);
            return response()->json([
                'error' => 'A tool required by the agent failed to execute.',
                'detail' => $e->getMessage()
            ], 500);

        } catch (AgentConfigurationException $e) {
            logger()->error("Agent configuration error for agent {$agentName}: " . $e->getMessage(), [
                'exception' => $e
            ]);
            return response()->json([
                'error' => 'Agent configuration error.',
                'detail' => $e->getMessage()
            ], 500);

        } catch (\Throwable $e) {
            // Catch-all for unexpected errors
            logger()->error("Error during agent '{$agentName}' execution: " . $e->getMessage(), [
                'exception' => $e
            ]);
            return response()->json([
                'error' => 'An unexpected error occurred while processing your request.',
                'detail' => $e->getMessage()
            ], 500);
        }
    }
}

Error Handling in Commands

Artisan commands handle errors gracefully to provide helpful feedback:

RunEvalCommand.php

// Example from RunEvalCommand
try {
    $evaluation = $this->loadEvaluation($evaluationName);
    $results = $evaluation->run();
} catch (\Exception $e) {
    $this->error("Evaluation failed: " . $e->getMessage());
    return 1; // Return non-zero exit code
}

Error Handling in Services

Services like AgentRegistry validate configuration and throw appropriate exceptions:

AgentRegistry.php

public function getAgent(string $name): BaseAgent
{
    if (!isset($this->registeredAgents[$name])) {
        throw new AgentNotFoundException("Agent '{$name}' is not registered.");
    }

    $config = $this->registeredAgents[$name];

    if (is_string($config)) {
        if (!class_exists($config)) {
            throw new AgentConfigurationException(
                "Agent class '{$config}' does not exist."
            );
        }

        $agent = new $config();

        if (!$agent instanceof BaseAgent) {
            throw new AgentConfigurationException(
                "Agent class '{$config}' must extend BaseAgent."
            );
        }

        return $agent;
    }

    // Handle array configuration...
}

Best Practices

1. Use Specific Exception Types

Always throw the most specific exception type for the error scenario:

Exception Best Practices

// Good - specific exception
if (!$agent) {
    throw new AgentNotFoundException("Agent 'chatbot' not found");
}

// Avoid - generic exception
if (!$agent) {
    throw new \Exception("Agent not found");
}

2. Provide Meaningful Error Messages

Include context in error messages to help with debugging:

Descriptive Error Messages

throw new ToolExecutionException(
    "Weather tool failed for location '{$location}': API key not configured"
);

3. Log Errors with Context

Always log errors with relevant context for debugging:

Error Logging

catch (ToolExecutionException $e) {
    logger()->error("Tool execution failed", [
        'agent' => $agentName,
        'tool' => $e->getToolName(),
        'session_id' => $sessionId,
        'exception' => $e
    ]);
}

4. Handle Errors at the Right Level

Let exceptions bubble up to where they can be handled appropriately:

Error Handling Layers

// In a tool - let exception bubble up
public function execute(array $arguments, AgentContext $context): string
{
    if (!isset($arguments['location'])) {
        throw new ToolExecutionException("Location parameter is required");
    }

    // Tool logic...
}

// In the controller - handle and return appropriate response
try {
    $result = $agent->run($input);
} catch (ToolExecutionException $e) {
    return response()->json(['error' => $e->getMessage()], 400);
}

Creating Custom Exceptions

You can create custom exceptions for your specific use cases:

app/Exceptions/ApiRateLimitException.php

<?php

namespace App\Exceptions;

use Vizra\VizraADK\Exceptions\ToolExecutionException;

class ApiRateLimitException extends ToolExecutionException
{
    protected string $service;
    protected int $retryAfter;

    public function __construct(string $service, int $retryAfter)
    {
        $this->service = $service;
        $this->retryAfter = $retryAfter;

        parent::__construct(
            "Rate limit exceeded for {$service}. Retry after {$retryAfter} seconds."
        );
    }

    public function getRetryAfter(): int
    {
        return $this->retryAfter;
    }
}

Error Recovery Strategies

Graceful Degradation

Provide fallback behavior when non-critical operations fail:

Fallback Pattern

public function execute(array $arguments, AgentContext $context): string
{
    try {
        // Try to get weather from primary API
        $weather = $this->primaryApi->getWeather($location);
    } catch (ToolExecutionException $e) {
        logger()->warning("Primary weather API failed, using fallback", [
            'error' => $e->getMessage()
        ]);

        // Fallback to secondary API
        try {
            $weather = $this->fallbackApi->getWeather($location);
        } catch (ToolExecutionException $e) {
            // Return cached or default response
            return json_encode([
                'error' => 'Weather service temporarily unavailable',
                'cached' => true,
                'data' => $this->getCachedWeather($location)
            ]);
        }
    }

    return json_encode($weather);
}

Retry Logic

Implement retry logic for transient failures:

Retry with Exponential Backoff

use Illuminate\Support\Facades\Http;

public function executeWithRetry(callable $operation, int $maxAttempts = 3)
{
    $attempt = 1;

    while ($attempt <= $maxAttempts) {
        try {
            return $operation();
        } catch (ToolExecutionException $e) {
            if ($attempt === $maxAttempts) {
                throw $e;
            }

            logger()->warning("Operation failed, retrying", [
                'attempt' => $attempt,
                'max_attempts' => $maxAttempts,
                'error' => $e->getMessage()
            ]);

            sleep(pow(2, $attempt)); // Exponential backoff
            $attempt++;
        }
    }
}

Testing Error Handling

Always test your error handling paths:

tests/Feature/ErrorHandlingTest.php

use Vizra\VizraADK\Exceptions\AgentNotFoundException;

test('throws exception for non-existent agent', function () {
    $registry = app(AgentRegistry::class);

    expect(fn() => $registry->getAgent('non-existent'))
        ->toThrow(AgentNotFoundException::class, "Agent 'non-existent' is not registered.");
});

test('handles tool execution failure gracefully', function () {
    $response = $this->postJson('/api/vizra/interact', [
        'agent_name' => 'test_agent',
        'input' => 'trigger tool failure'
    ]);

    $response->assertStatus(500)
        ->assertJson([
            'error' => 'A tool required by the agent failed to execute.'
        ]);
});

Next Steps

Agent Class Reference

Agent class documentation

Tool Development

Build custom tools

Testing Strategies

Test your agents

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

Examples

API Reference

Error Handling

Exception Types

AgentNotFoundException

AgentConfigurationException

ToolExecutionException

Handling Exceptions in Controllers

Error Handling in Commands

Error Handling in Services

Best Practices

1. Use Specific Exception Types

2. Provide Meaningful Error Messages

3. Log Errors with Context

4. Handle Errors at the Right Level

Creating Custom Exceptions

Error Recovery Strategies

Graceful Degradation

Retry Logic

Testing Error Handling

Next Steps

Agent Class Reference

Tool Development

Testing Strategies

​Exception Types

​AgentNotFoundException

​AgentConfigurationException

​ToolExecutionException

​Handling Exceptions in Controllers

​Error Handling in Commands

​Error Handling in Services

​Best Practices

​1. Use Specific Exception Types

​2. Provide Meaningful Error Messages

​3. Log Errors with Context

​4. Handle Errors at the Right Level

​Creating Custom Exceptions

​Error Recovery Strategies

​Graceful Degradation

​Retry Logic

​Testing Error Handling

​Next Steps

Agent Class Reference

Tool Development

Testing Strategies

Exception Types

AgentNotFoundException

AgentConfigurationException

ToolExecutionException

Handling Exceptions in Controllers

Error Handling in Commands

Error Handling in Services

Best Practices

1. Use Specific Exception Types

2. Provide Meaningful Error Messages

3. Log Errors with Context

4. Handle Errors at the Right Level

Creating Custom Exceptions

Error Recovery Strategies

Graceful Degradation

Retry Logic

Testing Error Handling

Next Steps