Vizra ADK

Every tool implemented via ToolInterface automatically receives the agent's memory as the third parameter in the execute method. This allows tools to read from and write to the agent's persistent memory, enabling personalized experiences and cross-session state management.

Available Memory Methods

• addFact(string $content, float $confidence): Store immutable facts.
• addLearning(string $insight): Track insights discovered during interaction.
• addPreference(string $value, string $key = 'general'): Store user preferences.
• updateSummary(): Update the overall user profile summary.

public function execute(
    array $arguments,
    AgentContext $context,
    AgentMemory $memory  // Automatically provided
): string {
    // Example: Storing a fact
    $memory->addFact("User prefers dark mode", 1.0);
    
    // Example: Storing a preference
    $memory->addPreference("dark", "ui_theme");

    return json_encode(['success' => true]);
}

Implement lifecycle hooks to automatically inject context into prompts before an LLM call or to extract insights from the LLM response after it is generated.

beforeLlmCall(array $inputMessages, AgentContext $context): array

Use this hook to build a context summary (e.g., from current state) and inject it into the system message. This ensures the LLM is aware of the current session state before it generates a response.

afterLlmResponse(Response|Generator $response, AgentContext $context): mixed

Use this hook to parse the LLM's response and update the AgentContext. This is the ideal place to extract user preferences, update goals, or perform structured data extraction from the response text.

// Example: Injecting context before LLM call
public function beforeLlmCall(array $inputMessages, AgentContext $context): array
{
    $cart = $context->getState('cart', []);
    $budget = $context->getState('budget');
    $preferences = $context->getState('preferences', []);
    $totalSpent = $context->getState('total_spent', 0);

    $contextSummary = $this->buildContextSummary($cart, $budget, $preferences, $totalSpent);
    
    // Inject into the first message (usually the system instruction)
    $inputMessages[0]['content'] = $this->instructions . "\n\n" . $contextSummary;
    
    return $inputMessages;
}

// Example: Extracting insights after LLM response
public function afterLlmResponse(Response|Generator $response, AgentContext $context): mixed
{
    $responseText = $response->getContent(); // Assuming response provides content
    
    $this->extractAndStorePreferences($responseText, $context);
    $this->updateShoppingGoals($responseText, $context);
    
    return $response;
}

SubAgents allow you to build teams of specialized agents. A parent (manager) agent can delegate tasks to these specialists. When you define a $subAgents array on a BaseLlmAgent class, Vizra ADK automatically provides the DelegateToSubAgentTool, enabling the manager to route requests intelligently.

Best Practices:

• Provide a clear description property for each subAgent; the manager uses this description to decide which specialist is appropriate for a task.
• Use specialized tools within subAgents to maintain separation of concerns.
• Assign different LLM models to different agents (e.g., GPT-4 for the manager, GPT-3.5 for simple subAgents).

class CustomerServiceManager extends BaseLlmAgent
{
    protected string $name = 'customer_service_manager';

    protected string $instructions = "You are a customer service manager. Route technical questions to the technical support agent.";

    protected array $subAgents = [
        TechnicalSupportAgent::class,
        BillingSupportAgent::class,
    ];
}

For complex qualitative checks, use LlmJudgeAssertion or LlmComparativeAssertion to leverage LLMs as evaluators.

Basic Judge: Evaluates against a text-based criteria string. Detailed Rubric: Uses a multi-dimensional scoring system (e.g., Empathy, Accuracy) and a threshold to determine pass/fail. Comparative Judge: Compares the agent's response against a provided referenceResponse.

// Basic Judge
new LlmJudgeAssertion(
    criteria: 'The response should be helpful, accurate, and professional',
    model: 'gpt-4o'
)

// Detailed Rubric
new LlmJudgeAssertion(
    criteria: "Evaluate on: 1. Empathy (0-3), 2. Accuracy (0-3). Total score must be > 4.",
    model: 'gpt-4o',
    threshold: 0.75
)

// Comparative Judge
new LlmComparativeAssertion(
    referenceResponse: $idealResponse,
    criteria: 'Response should be as helpful as or better than the reference',
    model: 'gpt-4o'
)

Toolboxes support two primary authorization methods. If both are defined, the policy takes precedence.

Toolbox-Level Gates

Use the $gate property to specify a Laravel Gate name. If the gate fails, the entire toolbox is hidden.

Toolbox-Level Policies

Use the $policy property to specify a Laravel Policy class. You can also specify the $policyAbility to check (defaults to 'use').

// Example using a Gate
class AdminToolbox extends BaseToolbox
{
    protected string $name = 'admin';
    protected ?string $gate = 'admin-access'; // Defined in AuthServiceProvider
    protected array $tools = [...];
}

// Example using a Policy
class PremiumToolbox extends BaseToolbox
{
    protected string $name = 'premium';
    protected ?string $policy = SubscriptionPolicy::class;
    protected ?string $policyAbility = 'accessPremiumFeatures';
    protected array $tools = [...];
}