Tool Class Reference

Think of the ToolInterface as your agent’s superhero training academy. Every tool you build expands what your agents can do - from simple calculations to complex integrations.

The Simple Yet Powerful Interface

The beauty of Vizra tools lies in their simplicity. Just two methods to implement, and your agent gains a whole new superpower. Here’s the elegant contract:

The ToolInterface Contract

namespace Vizra\VizraADK\Contracts;

use Vizra\VizraADK\System\AgentContext;
use Vizra\VizraADK\Memory\AgentMemory;

interface ToolInterface
{
    public function definition(): array;
    public function execute(array $arguments, AgentContext $context, AgentMemory $memory): string;
}

The Two Magical Methods

Just two methods stand between you and tool mastery. Each serves a crucial purpose in making your agent interactions seamless and powerful.

definition()

The blueprint method. Tell the AI exactly how to use your tool with a JSON Schema definition. It’s like writing a user manual that AI can understand perfectly.

public function definition(): array

execute()

The action hero. This is where the magic happens - take the AI’s parameters and make something amazing occur. Database queries, API calls, calculations - you name it.

public function execute(array $arguments, AgentContext $context, AgentMemory $memory): string

definition() - Teaching AI How to Use Your Tool

This method returns a JSON Schema that’s like a detailed instruction manual for AI. Here’s how to write one that makes your tool shine:

Perfect Tool Definition

public function definition(): array
{
    return [
        'name' => 'order_lookup',
        'description' => 'Look up order information by ID',
        'parameters' => [
            'type' => 'object',
            'properties' => [
                'order_id' => [
                    'type' => 'string',
                    'description' => 'The order ID to look up',
                ],
                'include_items' => [
                    'type' => 'boolean',
                    'description' => 'Include order items in response',
                ],
            ],
            'required' => ['order_id'],
        ],
    ];
}

execute()

public function execute(array $arguments, AgentContext $context, AgentMemory $memory): string

Execute the tool with provided arguments, context, and agent memory. Must return a JSON-encoded string.

public function execute(array $arguments, AgentContext $context): string
{
    $order = Order::find($arguments['order_id']);

    if (!$order) {
        return json_encode([
            'status' => 'error',
            'message' => 'Order not found',
        ]);
    }

    return json_encode([
        'status' => 'success',
        'order' => $order->toArray(),
    ]);
}

Parameter Schema Examples

Basic Parameter Types

'parameters' => [
    'type' => 'object',
    'properties' => [
        'name' => [
            'type' => 'string',
            'description' => 'User name',
        ],
        'age' => [
            'type' => 'integer',
            'description' => 'User age',
            'minimum' => 0,
            'maximum' => 150,
        ],
        'active' => [
            'type' => 'boolean',
            'description' => 'Whether user is active',
        ],
        'price' => [
            'type' => 'number',
            'description' => 'Product price',
            'minimum' => 0,
        ],
    ],
    'required' => ['name'],
]

Complex Parameter Types

'parameters' => [
    'type' => 'object',
    'properties' => [
        'status' => [
            'type' => 'string',
            'enum' => ['pending', 'processing', 'completed'],
            'description' => 'Order status',
        ],
        'tags' => [
            'type' => 'array',
            'description' => 'List of tags',
            'items' => [
                'type' => 'string',
            ],
        ],
        'address' => [
            'type' => 'object',
            'description' => 'User address',
            'properties' => [
                'street' => ['type' => 'string'],
                'city' => ['type' => 'string'],
                'zip' => ['type' => 'string'],
            ],
        ],
    ],
    'required' => [],
]

Return Value Format

Tools must return a JSON-encoded string. Common patterns include:

// Success response
return json_encode([
    'status' => 'success',
    'data' => $resultData,
    'message' => 'Operation completed successfully',
]);

// Error response
return json_encode([
    'status' => 'error',
    'message' => 'Detailed error message',
    'error_code' => 'SPECIFIC_ERROR',
]);

Working with AgentContext

The AgentContext parameter provides access to session state and conversation history:

public function execute(array $arguments, AgentContext $context): string
{
    // Get session ID
    $sessionId = $context->getSessionId();

    // Access state
    $previousValue = $context->getState('last_order_id');

    // Store state for future use
    $context->setState('last_order_id', $orderId);

    // Access user information if available
    $userId = $context->getState('user_id');

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

Advanced Features

Tool with User Context

class UserOrdersTool implements ToolInterface
{
    public function execute(array $arguments, AgentContext $context): string
    {
        // Get user ID from context
        $userId = $context->getState('user_id');

        if (!$userId) {
            return json_encode([
                'status' => 'error',
                'message' => 'User authentication required',
            ]);
        }

        $user = User::find($userId);
        $orders = $user->orders()
            ->latest()
            ->limit($arguments['limit'] ?? 10)
            ->get();

        return json_encode([
            'status' => 'success',
            'orders' => $orders->toArray(),
        ]);
    }
}

Tool with Session Context

public function execute(array $arguments, AgentContext $context): string
{
    // Access session context
    $previousOrder = $context->getState('last_order_discussed');

    // Store data in session
    $context->setState('current_order', $order->id);

    return json_encode([
        'status' => 'success',
        'order' => $order->toArray(),
    ]);
}

Tool with File Handling

class FileProcessorTool implements ToolInterface
{
    public function definition(): array
    {
        return [
            'name' => 'file_processor',
            'description' => 'Process uploaded files',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'file_content' => [
                        'type' => 'string',
                        'description' => 'Base64 encoded content',
                    ],
                    'filename' => [
                        'type' => 'string',
                    ],
                ],
                'required' => ['file_content', 'filename'],
            ],
        ];
    }

    public function execute(array $arguments, AgentContext $context): string
    {
        $content = base64_decode($arguments['file_content']);
        $path = Storage::put('uploads/' . $arguments['filename'], $content);

        return json_encode([
            'status' => 'success',
            'path' => $path,
            'size' => strlen($content),
        ]);
    }
}

Complete Example

RefundProcessorTool.php

<?php

namespace App\Tools;

use Vizra\VizraADK\Contracts\ToolInterface;
use Vizra\VizraADK\System\AgentContext;
use App\Models\Order;
use App\Services\RefundService;

class RefundProcessorTool implements ToolInterface
{

    public function __construct(
        protected RefundService $refunds
    ) {}

    public function definition(): array
    {
        return [
            'name' => 'process_refund',
            'description' => 'Process a refund for an order',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'order_id' => [
                        'type' => 'string',
                        'description' => 'The order ID to refund',
                    ],
                    'amount' => [
                        'type' => 'number',
                        'description' => 'Refund amount (optional for partial refunds)',
                        'minimum' => 0,
                    ],
                    'reason' => [
                        'type' => 'string',
                        'description' => 'Reason for refund',
                    ],
                ],
                'required' => ['order_id', 'reason'],
            ],
        ];
    }

    public function execute(array $arguments, AgentContext $context): string
    {
        // Validate inputs
        $validator = Validator::make($arguments, [
            'order_id' => 'required|string',
            'amount' => 'nullable|numeric|min:0',
            'reason' => 'required|string',
        ]);

        if ($validator->fails()) {
            return json_encode([
                'status' => 'error',
                'message' => 'Validation failed: ' . $validator->errors()->first(),
            ]);
        }

        // Check user authorization
        $userId = $context->getState('user_id');
        if (!$userId) {
            return json_encode([
                'status' => 'error',
                'message' => 'User authentication required',
            ]);
        }

        try {
            $order = Order::findOrFail($arguments['order_id']);

            // Verify order belongs to user
            if ($order->user_id !== $userId) {
                return json_encode([
                    'status' => 'error',
                    'message' => 'Order not found',
                ]);
            }

            $refund = $this->refunds->process(
                $order,
                $arguments['amount'] ?? $order->total,
                $arguments['reason']
            );

            return json_encode([
                'status' => 'success',
                'refund_id' => $refund->id,
                'amount' => $refund->amount,
                'refund_status' => $refund->status,
                'message' => 'Refund processed successfully',
            ]);

        } catch (\Exception $e) {
            return json_encode([
                'status' => 'error',
                'message' => 'Failed to process refund: ' . $e->getMessage(),
            ]);
        }
    }
}

Tool Best Practices:

Keep tools focused on a single action
Implement the ToolInterface, not extend a base class
Use descriptive names and descriptions
Return JSON-encoded strings from execute()
Use AgentContext for session state management
Validate parameters thoroughly
Handle errors gracefully
Return clear success/error messages

Getting Started

Core Concepts

Agents

Tools

Advanced Features

Integrations

Testing & Observability

API Reference

Tool Class Reference

The Simple Yet Powerful Interface

The Two Magical Methods

definition()

execute()

definition() - Teaching AI How to Use Your Tool

execute()

Parameter Schema Examples

Basic Parameter Types

Complex Parameter Types

Return Value Format

Working with AgentContext

Advanced Features

Tool with User Context

Tool with Session Context

Tool with File Handling

Complete Example

Next Steps

Workflow Class

Tool Concepts

​The Simple Yet Powerful Interface

​The Two Magical Methods

definition()

execute()

​definition() - Teaching AI How to Use Your Tool

​execute()

​Parameter Schema Examples

​Basic Parameter Types

​Complex Parameter Types

​Return Value Format

​Working with AgentContext

​Advanced Features

​Tool with User Context

​Tool with Session Context

​Tool with File Handling

​Complete Example

​Next Steps

Workflow Class

Tool Concepts

The Simple Yet Powerful Interface

The Two Magical Methods

definition() - Teaching AI How to Use Your Tool

execute()

Parameter Schema Examples

Basic Parameter Types

Complex Parameter Types

Return Value Format

Working with AgentContext

Advanced Features

Tool with User Context

Tool with Session Context

Tool with File Handling

Complete Example

Next Steps