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 towardmax_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 raisesllmragent_guardrail_blockand is recorded as an event; defaultNULLmeans 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()
} # }