Skip to content

Tool Calling & Autonomous Agents ​

jengo/ai features a multi-turn agentic execution loop. The model can autonomously decide to call one or more PHP functions, receive their outputs, and continue reasoning until reaching the final answer.

Method 1: PHP 8 Attribute Discovery (#[AiTool]) ​

Decorate any service or repository methods with #[AiTool] and #[AiParameter]:

php
namespace App\AiTools;

use Jengo\Ai\Attributes\AiTool;
use Jengo\Ai\Attributes\AiParameter;

class StoreAssistant
{
    #[AiTool(
        name: 'searchProducts',
        description: 'Search the product catalog for availability and pricing.'
    )]
    public function searchProducts(
        #[AiParameter(description: 'Search keywords, e.g. "Pixel 8" or "Laptop"')]
        string $query,
        #[AiParameter(description: 'Optional category filter', required: false)]
        ?string $category = null
    ): array {
        return model('ProductModel')
            ->like('name', $query)
            ->findAll();
    }

    #[AiTool(
        name: 'applyCoupon',
        description: 'Validate and calculate discount for a promotional coupon code.'
    )]
    public function applyCoupon(
        #[AiParameter(description: 'The coupon code string, e.g. "VIP50"')]
        string $code,
        #[AiParameter(description: 'The order subtotal amount in USD')]
        float $subtotal
    ): array {
        if ($code === 'VIP50') {
            return ['valid' => true, 'discount' => $subtotal * 0.5, 'final_price' => $subtotal * 0.5];
        }

        return ['valid' => false, 'discount' => 0.0, 'message' => 'Invalid coupon code.'];
    }
}

Attach your tools directly with ->withToolsFrom():

php
use App\AiTools\StoreAssistant;

$response = ai('Do we have any Pixel phones in stock? If so, what is the price after applying coupon VIP50?')
    ->withToolsFrom(new StoreAssistant())
    ->maxSteps(5) // Max recursive agent steps
    ->generate();

echo $response->text();
// The model autonomously calls searchProducts('Pixel'), calculates the discount with applyCoupon('VIP50', 799), and provides a complete final answer!

Dependency Injection & Container Autowiring ​

You can pass class-strings directly to withToolsFrom(). The tool class is instantiated via the PSR-11 container ($this->make() or Services::autowire()), resolving all constructor dependencies automatically:

php
namespace App\AiTools;

use App\Repositories\ProductRepository;
use Jengo\Ai\Attributes\AiTool;
use Jengo\Ai\Attributes\AiParameter;

class InventoryAssistant
{
    public function __construct(
        protected ProductRepository $products
    ) {}

    #[AiTool(name: 'findStock', description: 'Look up product stock levels')]
    public function findStock(#[AiParameter(description: 'SKU or name')] string $query): array
    {
        return $this->products->findBySkuOrName($query);
    }
}

// Pass the class string directly — constructor dependencies are autowired:
$answer = ai('Check stock for SKU-100')
    ->withToolsFrom(InventoryAssistant::class)
    ->text();

Method 2: Fluent Tool Definition ​

You can also register tools programmatically using Tool::make(). Tool handlers also benefit from dependency injection — any parameters not provided by the AI model can be autowired from the container:

php
use Jengo\Ai\Support\Tool;
use App\Services\WeatherService;

$weatherTool = Tool::make('getWeather', 'Get the current weather for a city')
    ->parameter('city', 'string', 'The city name, e.g. London')
    ->parameter('unit', 'string', 'Temperature unit: c or f', required: false)
    ->handler(function (string $city, string $unit = 'c', WeatherService $weather) {
        // $weather is automatically resolved from the DI container!
        return $weather->getForecast($city, $unit);
    });

$answer = ai('What is the weather in Tokyo right now?')
    ->withTools($weatherTool)
    ->text();

Released under the MIT License.