Skip to contents

An agent is a persona plus a model: it remembers its conversation (see memory), can call R functions you expose as tools (via LLMR::llm_tool()), and refuses further calls when its budget() runs out. Use agent$chat() for a stateful conversation, agent$reply() for an exchange that leaves memory unchanged, agent$ask_structured() for schema-shaped answers, and pass agents to conversation(), debate(), focus_group(), interview(), or deliberate() for multi-agent work.

Usage

agent(
  name,
  config,
  persona = NULL,
  tools = list(),
  memory = memory_buffer(),
  budget = LLMRagent::budget(),
  guardrails = NULL,
  quiet = FALSE
)

Arguments

name

Display name (used in transcripts).

config

An LLMR::llm_config() for a generative model.

persona

Optional system prompt: who this agent is, what it wants, how it speaks. For social-science personas, write it like a character brief: background, dispositions, speech style. A persona_frame() is accepted too.

tools

A LLMR::llm_tool() or list of them. Tool calls the model makes are executed automatically and fed back until it answers. A call whose arguments are not a JSON object, or that comes from a reply cut off by the output-token limit, is not run: the model receives an error result and can call the tool again, and the call is recorded with status "refused" without counting toward max_tool_calls.

memory

A memory object; default keeps the last 40 messages.

budget

A budget(); default unlimited.

guardrails

Optional guardrails() to check the agent's inputs, outputs, and tool calls. A blocked check raises llmragent_guardrail_block and is recorded as an event; default NULL means no guardrails.

quiet

If TRUE, chat() does not echo replies to the console.

Value

An Agent (R6) object.

Details

Two design decisions worth knowing:

  • Failures are errors, not replies. If a call fails, the typed LLMR condition propagates; nothing is written into memory, so an API hiccup is never stored as something the model said.

  • Budgets are checked at every call boundary. Call and tool-call limits stop the next round. The token limit stops the next round once recorded use reaches it; one response can cross that threshold.

A reply that arrives but whose call record cannot be built is kept: the agent warns and records the exchange as an event with status "unrecorded", with the reason in its note. agent$usage() sums the token counts providers reported and counts, in n_unknown_usage, the calls whose usage was not reported; see Agent for its columns.

Examples

cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b", temperature = 0.7)
ada <- agent("Ada", cfg,
             persona = "You are Ada, a meticulous statistician. Be brief.")
ada
ada$usage()

if (FALSE) { # \dontrun{
ada$chat("In one sentence: what is overfitting?")
ada$chat("And how would you detect it?")   # remembers the thread
ada$chat("Walk me through cross-validation.", stream = TRUE)  # live tokens
ada$usage()
} # }