Tool Use

Overview

ToolUse class automates the process of using tools by LLM, i.e.: - calling LLM with provided context (message sequence), - extracting tool calls requested by LLM from the response, - calling the requested tool and storing its results, - constructing message sequence with the result of call, - sending updated message sequence back to LLM.

This cycle is repeated until one of the exit criteria is met: - LLM no longer requests any tool calls, - specified maximum number of iterations is reached, - specified token usage limit is reached - there are any errors during the process (e.g. LLM requested a tool that is not available).

ToolUse class provides 3 ways to iterate through the process: - manual control - code is responsible for checking hasNextStep() and calling nextStep() in a loop, - using iterator - code uses foreach loop to iterate through the steps (internally it checks hasNextStep() and calls nextStep()), - just get final step - you only get the final step, iteration process is done internally.

Example

This example demonstrates 3 ways to use ToolUse class to allow LLM call functions if needed to answer simple math question. We provide 2 functions (add_numbers and subtract_numbers) as tools available to LLM and specify the task in plain language. The LLM is expected to call the functions in the correct order to get the final result.

<?php
require 'examples/boot.php';

use Cognesy\Addons\StepByStep\Continuation\ContinuationCriteria;
use Cognesy\Addons\StepByStep\Continuation\Criteria\ExecutionTimeLimit;
use Cognesy\Addons\StepByStep\Continuation\Criteria\RetryLimit;
use Cognesy\Addons\StepByStep\Continuation\Criteria\StepsLimit;
use Cognesy\Addons\StepByStep\Continuation\Criteria\TokenUsageLimit;
use Cognesy\Addons\ToolUse\Collections\Tools;
use Cognesy\Addons\ToolUse\Data\ToolUseState;
use Cognesy\Addons\ToolUse\Data\ToolUseStep;
use Cognesy\Addons\ToolUse\Drivers\ReAct\ContinuationCriteria\StopOnFinalDecision;
use Cognesy\Addons\ToolUse\Tools\FunctionTool;
use Cognesy\Addons\ToolUse\ToolUseFactory;
use Cognesy\Messages\Messages;

function add_numbers(int $a, int $b) : int { return $a + $b; }
function subtract_numbers(int $a, int $b) : int { return $a - $b; }

$toolUse = ToolUseFactory::default(
    tools: new Tools(
        FunctionTool::fromCallable(add_numbers(...)),
        FunctionTool::fromCallable(subtract_numbers(...))
    ),
    continuationCriteria: new ContinuationCriteria(
        new StepsLimit(6, fn(ToolUseState $state) => $state->stepCount()),
        new TokenUsageLimit(8192, fn(ToolUseState $state) => $state->usage()->total()),
        new ExecutionTimeLimit(60, fn(ToolUseState $state) => $state->startedAt()),
        new RetryLimit(2, fn(ToolUseState $state) => $state->steps(), fn(ToolUseStep $step) => $step->hasErrors()),
        new StopOnFinalDecision(),
    ),
);

//
// PATTERN #1 - manual control
//
echo "\nPATTERN #1 - manual control\n";
$state = (new ToolUseState)
    ->withMessages(Messages::fromString('Add 2455 and 3558 then subtract 4344 from the result.'));

// iterate until no more steps
while ($toolUse->hasNextStep($state)) {
    $state = $toolUse->nextStep($state);
    $step = $state->currentStep();
    print("STEP - tokens used: " . ($step->usage()?->total() ?? 0)  . ' [' . $step->toString() . ']' . "\n");
}

// print final response
$result = $state->currentStep()->outputMessages()->toString();
print("RESULT: " . $result . "\n");


//
// PATTERN #2 - using iterator
//
echo "\nPATTERN #2 - using iterator\n";
$state = (new ToolUseState)
    ->withMessages(Messages::fromString('Add 2455 and 3558 then subtract 4344 from the result.'));

// iterate until no more steps
foreach ($toolUse->iterator($state) as $currentState) {
    $step = $currentState->currentStep();
    print("STEP - tokens used: " . ($step->usage()?->total() ?? 0)  . ' [' . $step->toString() . ']' . "\n");
    $state = $currentState; // keep the latest state
}

// print final response
$result = $state->currentStep()->outputMessages()->toString();
print("RESULT: " . $result . "\n");



//
// PATTERN #3 - just get final step (fast forward to it)
//
echo "\nPATTERN #3 - get only final result\n";
$state = (new ToolUseState)
    ->withMessages(Messages::fromString('Add 2455 and 3558 then subtract 4344 from the result.'));

// print final response
$finalState = $toolUse->finalStep($state);
$result = $finalState->currentStep()->outputMessages()->toString();
print("RESULT: " . $result . "\n");
?>