ToolCallingService 

class ToolCallingService
Fully qualified name
\Netresearch\NrLlm\Service\Feature\ToolCallingService

Tool-calling chat completion. Depend on ToolCallingServiceInterface rather than this class (or the service manager) — the interface exposes exactly the tool-calling capability, so consumer test doubles stay two methods small (ADR-051).

When no beUserUid is set on the options, the active backend user is resolved and populated automatically so per-user budget enforcement applies.

chatWithTools(array $messages, array $tools, ?ToolOptions $options = null): CompletionResponse

Chat completion with tool calling. The provider is resolved from the options (or the extension's default); the configuration is a model-less transient one.

param array $messages

list of ChatMessage (or legacy {role, content} arrays)

param array $tools

list of ToolSpec (or legacy OpenAI-wire arrays)

param ?ToolOptions $options

Tool choice, provider/model pin, budget fields

Returns

CompletionResponse (toolCalls carries requested calls)

chatWithToolsForConfiguration(array $messages, array $tools, LlmConfiguration $configuration, ?ToolOptions $options = null): CompletionResponse

Chat completion with tool calling against a specific LLM configuration — the adapter is resolved from the configuration's model (vault key, model, pricing), so budget and usage middleware record real cost. Prefer this entry point when a database-backed configuration exists.

param array $messages

list of ChatMessage (or legacy {role, content} arrays)

param array $tools

list of ToolSpec (or legacy OpenAI-wire arrays)

param LlmConfiguration $configuration

The configuration to run on

param ?ToolOptions $options

Tool choice and budget fields

Returns

CompletionResponse (toolCalls carries requested calls)

Usage 

use Netresearch\NrLlm\Domain\ValueObject\ChatMessage;
use Netresearch\NrLlm\Domain\ValueObject\ToolSpec;
use Netresearch\NrLlm\Service\Feature\ToolCallingServiceInterface;
use Netresearch\NrLlm\Service\Option\ToolOptions;

final readonly class WeatherAgent
{
    public function __construct(
        private ToolCallingServiceInterface $toolCalling,
    ) {}

    public function ask(string $question): string
    {
        $response = $this->toolCalling->chatWithTools(
            [ChatMessage::user($question)],
            [ToolSpec::function(
                'get_weather',
                'Get the current weather for a location.',
                [
                    'type' => 'object',
                    'properties' => ['location' => ['type' => 'string']],
                    'required' => ['location'],
                ],
            )],
            ToolOptions::auto(),
        );

        // Dispatch $response->toolCalls and continue the conversation —
        // see :ref:`tool-calling` for the full loop.
        return $response->content;
    }
}
Copied!