(Perl) Streaming AI with Manual AI Tool Function Calling

See more AI Examples

Note: This example requires Chilkat v11.4.0 or greater.

For more information, see https://www.chilkatsoft.com/ai_tool_function_caling_briefly_explained.asp

Chilkat Perl Downloads Perl Module for Windows, MacOS, Linux, Alpine Linux

use chilkat();

$success = 0;

# Create the following JSON to define tool functions available for the AI to use.
# Note: You'll use the following JSON format regardless of the AI provider, whether
# it be ChatGPT, Gemini, Claude, Grok, etc.  Chilkat automatically converts to the required
# format needed for a given AI provider.

# In this example, the application is providing a single function the AI may choose to call.

# {
#   "tools": [
#     {
#       "name": "get_horoscope",
#       "description": "Get today's horoscope for an astrological sign.",
#       "parameters": {
#         "properties": {
#           "sign": {
#             "type": "string",
#             "description": "An astrological sign like Taurus or Aquarius"
#           }
#         }
#       }
#     }
#   ]
# }

$jsonTools = chilkat::CkJsonObject->new();

$toolIdx = 0;

$jsonTools->put_I($toolIdx);
$jsonTools->UpdateString("tools[i].name","get_horoscope");
$jsonTools->UpdateString("tools[i].description","Get today's horoscope for an astrological sign.");
$jsonTools->UpdateString("tools[i].parameters.properties.sign.type","string");
$jsonTools->UpdateString("tools[i].parameters.properties.sign.description","An astrological sign like Taurus or Aquarius");
# More tools can be added as desired..

$jsonTools->put_EmitCompact(0);
print $jsonTools->emit() . "\r\n";

$ai = chilkat::CkAi->new();

# Register the tools that will be made available to the AI.
$ai->RegisterManualTools($jsonTools);

# The provider can be "openai", "google", "claude", "grok", "mistral", "custom", etc.
$ai->put_Provider("openai");
# Use your provider's API key.
$ai->put_ApiKey("MY_API_KEY");
# Choose a model.
$ai->put_Model("gpt-5-mini");

# Tool function calling must always occur within a conversation.
$conversation_name = "convo_astrology";
$sysMessage = "You are a helpful astrologer";
$devMessage = "Respond only with markdown.";
$ai->NewConvo($conversation_name,$sysMessage,$devMessage);

# Provide inputs
$ai->InputAddText("What is my horoscope? I am an Aquarius.");

# Get the response in streaming mode.
$ai->put_Streaming(1);

# In streaming mode, if we receive an AI event that is a request for tool use,
# we'll need to make the call to the JavaScript and then continue with a followup Ask,
# until the final response is received.

$sbEventName = chilkat::CkStringBuilder->new();
$sbDelta = chilkat::CkStringBuilder->new();
$sbFullResponse = chilkat::CkStringBuilder->new();

# When PollAi returns with an event, it's highly unlikely the
# call to NextAiEvent does not immediately return.  Setting a max
# timeout is just a precaution..
$maxWaitMs = 5000;

$jsonFn = chilkat::CkJsonObject->new();

$finished = 0;
$numAsks = 0;
# Set a max # of followup Asks to prevent any unexpected infinite looping.
while (!$finished and ($numAsks < 10)) {

    # Send the request to the AI model.
    $success = $ai->Ask("text");
    if ($success == 0) {
        print $ai->lastErrorText() . "\r\n";
        exit;
    }

    $madeFunctionCalls = 0;
    $streamingDone = 0;

    while (!$streamingDone) {
        $result = $ai->PollAi(0);
        if ($result < 0) {
            print $ai->lastErrorText() . "\r\n";
            print "Failed." . "\r\n";
            exit;
        }

        if ($result > 0) {
            # We have an event..
            $success = $ai->NextAiEvent($maxWaitMs,$sbEventName,$sbDelta);
            if ($success == 0) {
                print $ai->lastErrorText() . "\r\n";
                exit;
            }

            # Is this an event where the AI is requesting a function call?
            if ($sbEventName->ContentsEqual("function_call",1)) {
                $jsonFn->LoadSb($sbDelta);

                # Note: Chilkat will convert responses from all AI providers to this format:

                # {
                #   "function_call": [
                #     {
                #       "name": "get_horoscope",
                #       "call_id": "call_RYmeysYQFocFc7Z2ofkv61dW",
                #       "arguments": "{\"sign\":\"Aquarius\"}",
                #       "args": {
                #         "sign": "Aquarius"
                #       }
                #     }
                #   ]
                # }

                $numFnCalls = $jsonFn->SizeOfArray("function_call");
                $fn_idx = 0;
                while (($fn_idx < $numFnCalls)) {
                    $jsonFn->put_I($fn_idx);

                    $sbFnName = chilkat::CkStringBuilder->new();
                    $jsonFn->StringOfSb("function_call[i].name",$sbFnName);
                    $callId = $jsonFn->stringOf("function_call[i].call_id");

                    if ($sbFnName->ContentsEqual("get_horoscope",1) == 1) {

                        # The get_horoscope function (as defined above) has one argument named "sign".
                        $zodiac_sign = $jsonFn->stringOf("function_call[i].args.sign");
                        print "zodiac_sign = " . $zodiac_sign . "\r\n";

                        # Insert application code here to call your app's get_horoscope function, passing the zodiac_sign to it..

                        # For this example, we'll pretend the app's get_horoscope function returned the following:
                        $applicationFnCallResult = "Aquarius: Next Tuesday you will befriend a baby otter.";

                        # Provide the tool call result as an input for the followup Ask.
                        $ai->InputAddFnResult($callId,$applicationFnCallResult);

                        $madeFunctionCalls = 1;
                    }

                    # Your application would add code to check for and handle each possible function call.

                    $fn_idx = $fn_idx + 1;
                }

            }
            else {
                if (!$sbEventName->ContentsEqual("empty",1)) {
                    $sbFullResponse->AppendSb($sbDelta);

                    if ($sbEventName->ContentsEqual("null_terminator",1)) {
                        $streamingDone = 1;
                    }

                }

            }

        }
        else {
            # No event arrived, so wait a short time rather than spin in a loop..
            $ai->SleepMs(100);
        }

    }

    if (!$madeFunctionCalls) {
        $finished = 1;
    }

    $numAsks = $numAsks + 1;
}

print "Full Response:" . "\r\n";
print $sbFullResponse->getAsString() . "\r\n";