Skip to contents

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_limit rather 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
} # }