The Agent class
The Agent class
Details
Construct with agent(). The methods documented here form the public
interface: chat() for stateful exchanges, reply() for stateless ones
(used by conversation()), ask_structured() for schema-shaped answers,
plus accessors for the trace, usage, and transcript.
Public fields
nameDisplay name, used in transcripts.
personaSystem prompt: who the agent is and how it behaves.
configThe LLMR model configuration.
toolsList of
LLMR::llm_tool()objects available to the agent.memoryThe memory object (see memory).
budgetThe
budget()limits.last_responseThe
llmr_responsefrom the most recent call.
Methods
Method new()
Create an agent (prefer the agent() constructor).
Usage
Agent$new(
name,
config,
persona = NULL,
tools = list(),
memory = memory_buffer(),
budget = LLMRagent::budget(),
guardrails = NULL,
quiet = FALSE,
caller = NULL,
stream_caller = NULL
)Arguments
nameDisplay name.
configpersonaSystem prompt; character scalar or NULL.
toolsList of
LLMR::llm_tool()objects (or a single one).memoryA memory object; default
memory_buffer(40).budgetA
budget()object.quietIf TRUE,
chat()does not print replies.callerInternal seam for tests: a function
(config, messages, tools, ...)returning anllmr_response.stream_callerInternal seam for tests: a function
(config, messages, callback, ...)returning anllmr_response.
Method chat()
Stateful exchange: the message and the reply are stored in memory, so consecutive calls form a conversation. Tools (if any) are executed automatically through LLMR's tool loop.
Arguments
textUser message (character scalar).
...Passed to the underlying LLMR call (e.g.
tries).streamIf TRUE, print the reply token by token as it is generated (via
LLMR::call_llm_stream()). Streaming is unavailable when the agent has tools; such calls fall back to the tool loop with a one-time warning.
Method reply()
Stateless exchange: persona and tools apply, but nothing
is written to memory. conversation() uses this so the shared
transcript remains the single source of truth.
Arguments
messagesA character scalar, named character vector, or message list as accepted by
LLMR::call_llm(). The persona is prepended as a system message when the input does not carry one....Passed to the underlying LLMR call.
Method ask_structured()
Ask for a schema-shaped answer, parsed into an R list. Stateless (memory is not written); the reply is parsed locally.
Arguments
textThe question or instruction: a character scalar, or a message list as accepted by
LLMR::call_llm()(the persona is prepended as a system message when the list has none).schemaA JSON Schema (R list).
...Passed to the underlying LLMR call.
Method trace()
The trace: one row per event (model calls, tool runs,
memory compactions, budget stops) with tokens and timing. This is a
projection of the internal span store onto the legacy event vocabulary;
richer event types (guardrail, approval, stream) and span linkage are
available via as_agent_run(agent) and tibble::as_tibble(run, "event").
Method internal_spans()
The internal span store (one row per event, richer than
trace()): the source the run object reads. Mainly for as_agent_run();
most users want trace() or a run object.
Method bind_run()
Bind this agent to an active run so its spans are stamped
with run_id/parent_id (internal; used by the conversation and
delegation machinery). Pass run_id = NULL to unbind.
Method id()
This agent's stable id (assigned at construction; used to attribute spans and to detect shared instances across experiment cells).
Method persona_frame()
The agent's persona_frame() if one was supplied, else NULL
(a plain-string persona). Used by the provenance layer for persona
hashing and scope conditions.
Method reset()
Forget the conversation (memory only; trace and usage counters are kept, since money was spent).
Method restore_accounting()
Restore accounting after load_agent() (internal). Call,
token, and tool counters carry over so budgets stay binding across
sessions; the wall-clock budget restarts.