Sends messages together with native tool definitions, executes every tool
the model calls, feeds the results back, and repeats until the model
answers in plain text (or max_rounds is reached). Supported for
OpenAI-compatible providers (openai, groq, together, deepseek, xai,
alibaba, zhipu, moonshot, xiaomi, openrouter, meta, ollama) and Anthropic.
Usage
call_llm_tools(
config,
messages,
tools,
max_rounds = 8L,
max_tool_calls = Inf,
verbose = FALSE,
tries = 3L,
wait_seconds = 2
)Arguments
- config
An llm_config for a generative model.
- messages
Messages as in
call_llm().- tools
One
llm_tool()or a list of them.- max_rounds
Maximum model turns (a turn may contain several tool calls). When reached, the last response is returned as-is with a warning.
- max_tool_calls
Maximum tool executions across the whole loop. Exceeding it raises a condition of class
llmr_tool_limitrather than continuing to spend; the default is unlimited. Callers enforcing spend ceilings (e.g. agent frameworks) can catch that class.- verbose
Print each tool invocation as it happens.
- tries, wait_seconds
Retry controls passed to
call_llm_robust().
Value
The final llmr_response. Its messages field contains the full
conversation, including tool results; tool_history is a tibble of
executed calls with columns round, name, arguments (JSON), and
result; and tool_loop is a list with model_calls, sent, rec
(token totals over every internal model call, NA when the provider
reported none), tool_calls, and n_unknown_usage (model calls whose
usage was not reported, and so is missing from sent and rec). The same values remain available as
attributes for backward compatibility. Note that tokens(x) alone covers
only the final model call.
Details
A tool call whose arguments are not a valid JSON object, and every tool call
in a reply cut off by the output-token limit, is not run: the model receives
an error result instead and can call the tool again. Such calls do not count
toward max_tool_calls, and tool_history records their argument text as
received.
Examples
if (FALSE) { # \dontrun{
weather <- llm_tool(
function(city) paste0("22C and clear in ", city),
name = "get_weather",
description = "Current weather for a city.",
parameters = list(city = list(type = "string"))
)
cfg <- llm_config("groq", "openai/gpt-oss-20b", temperature = 0)
r <- call_llm_tools(cfg, "What is the weather in Tunis?", tools = weather)
as.character(r)
r$tool_history
} # }