Apply an Agent over a vector of prompts — agentapply • rtemis.llm

agentapply is the lapply-style entry point for running a single prompt against an Agent repeatedly over a vector of inputs. Pass either a model name (in which case an Agent is built on the fly using backend, system_prompt, tools, use_memory, max_tool_rounds, output_schema) or a pre-built Agent object.

Usage

agentapply(
  x,
  model_or_agent,
  backend = c("ollama", "openai", "anthropic"),
  system_prompt = SYSTEM_PROMPT_DEFAULT,
  tools = NULL,
  use_memory = FALSE,
  max_tool_rounds = 3L,
  output_schema = NULL,
  verbosity = 1L,
  extract_responses = TRUE,
  on_error = c("na", "abort"),
  validate_output = TRUE,
  on_validation_failure = c("warn", "collect", "abort"),
  image_path = NULL,
  ...
)

Arguments

x: Character or list: Values to iterate over.
model_or_agent: Character or Agent: Either the name of a model (a string) or a pre-built Agent object from create_agent.
backend: Character {"ollama", "openai", "anthropic"}: Backend to use when model_or_agent is a string. Ignored when model_or_agent is an Agent object.
system_prompt: Character: System prompt for the on-the-fly Agent.
tools: Optional list of Tool objects: Tools available to the on-the-fly Agent.
use_memory: Logical: Whether the on-the-fly Agent should keep conversation memory.
max_tool_rounds: Integer [1, Inf): Maximum number of tool call rounds per query.
output_schema: Optional Schema: Output schema for the on-the-fly Agent.
verbosity: Integer [0, Inf): Verbosity level.
extract_responses: Logical: If TRUE, return a character vector of assistant responses. If FALSE, return the raw list of lists of Message objects.
on_error: Character {"na", "abort"}: What to do when a single call fails. "na" warns, keeps that element's slot as NA_character_ (or NULL when extract_responses = FALSE), and carries on, so a run of thousands of calls is not lost to one timeout. "abort" propagates the error and discards every result in the batch.
validate_output: Logical: Validate final output locally when a schema is supplied. Disabling this does not disable the schema sent to the model.
on_validation_failure: Character {"warn", "collect", "abort"}: Preserve invalid output and report a styled rtemis.core message (not an R warning), collect silently, or abort with an error carrying output and validation. See validate_output.
image_path: Optional character or list: Local image files to send with the prompts. A character vector sends one image with each element of x; a list of character vectors sends several (a NULL entry sends none). Length 1 is recycled across x, and a single prompt in x is recycled across image_path, so one question can be asked of many images. Every file is checked before the first request. See generate.
...: Additional per-call arguments forwarded to generate.

Value

If extract_responses = TRUE, a character vector the same length as x. Otherwise, a list of lists of Message objects. Under on_error = "na" the result carries an errors attribute: a data.frame of index and message, one row per failed call, so failures can be retried by position rather than found by scanning for NA. With a schema, validation_results retrieves per-input statuses and diagnostics. Invalid outputs remain in place under warn/collect; warn emits one informational summary message for the batch, respecting verbosity.

Details

Unlike llmapply, this function can carry tools and memory. The default is use_memory = FALSE because the common case for vectorized calls is independent queries.

Progress is reported through rtemis.core's nested progress API: one status line labelled with the model name, ticking once per element, with an ETA. Set verbosity = 0L to silence it. When a message sink is set (see rtemis.core::set_msg_sink()), progress is forwarded as structured events instead of being drawn, and nests under any enclosing progress node.

Author

EDG

Examples

# Requires running Ollama server and gemma4:e4b model
if (FALSE) { # \dontrun{
  agentapply(
    c("today", "yesterday", "tomorrow"),
    "gemma4:e4b",
    system_prompt = "Return the date in ISO format",
    tools = list(tool_datetime),
    temperature = 0.2
  )
} # }