Skip to contents

Create an agent

Source: R/agent.R
agent.Rd

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$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.

tools

A LLMR::llm_tool() or list of them. Tool calls the model makes are executed automatically and fed back until it answers.

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.

See also

budget(), memory, agent_as_tool(), agent_pipeline(), conversation(), agent_experiment()

Examples

if (FALSE) { # \dontrun{
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$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()
} # }