Skip to contents

The Agent class

The Agent class

Details

Construct with agent(), the package's only supported constructor. The methods documented here form the working interface of a constructed agent: 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. The generator itself is internal; its constructor arguments are not a public contract.

The token columns sum the counts providers reported. n_unknown_usage counts model calls and embedding operations whose sent or received count was not reported; it is NA when the agent was restored from accounting, or resumed from an approval checkpoint, that did not keep this count. The counters include tool-loop rounds and embedding operations that have no call record of their own, so they need not equal diagnostics() over the agent's call level.

Public fields

name

Display name, used in transcripts.

persona

System prompt: who the agent is and how it behaves.

config

The LLMR model configuration.

tools

List of LLMR::llm_tool() objects available to the agent.

memory

The memory object (see memory).

budget

The budget() limits.

last_response

The llmr_response from 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

name

Display name.

config

An LLMR::llm_config().

persona

System prompt; character scalar or NULL.

tools

List of LLMR::llm_tool() objects (or a single one).

memory

A memory object; default memory_buffer(40).

budget

A budget() object.

guardrails

Optional guardrails() checks on inputs, outputs, and tool calls.

quiet

If TRUE, chat() does not print replies.

caller

Internal seam for tests: a function (config, messages, tools, ...) returning an llmr_response.

stream_caller

Internal seam for tests: a function (config, messages, callback, ...) returning an llmr_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.

Usage

Agent$chat(text, ..., stream = FALSE)

Arguments

text

User message (character scalar).

...

Passed to the underlying LLMR call (e.g. tries).

stream

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

Returns

The reply text, invisibly. The full llmr_response of the last exchange is available as $last_response.


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.

Usage

Agent$reply(messages, ...)

Arguments

messages

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

Returns

The reply text (character scalar).


Method ask_structured()

Ask for a schema-shaped answer, parsed into an R list. Stateless (memory is not written); the reply is parsed locally.

Usage

Agent$ask_structured(text, schema, ...)

Arguments

text

The 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).

schema

A JSON Schema (R list).

...

Passed to the underlying LLMR call.

Returns

The parsed object (list), or NULL when parsing failed; the raw reply stays available in $last_response.


Method trace()

The trace: one row per event (model calls, tool runs, memory compactions, retrieval embeddings, 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").

Usage

Agent$trace()


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.

Usage

Agent$internal_spans()


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.

Usage

Agent$bind_run(run_id = NULL, parent = NA_character_)

Arguments

run_id

The active run's id, or NULL to unbind.

parent

A parent span id for nesting (e.g. a supervisor's tool span).


Method id()

This agent's stable id (assigned at construction; used to attribute spans and to detect shared instances across experiment cells).

Usage

Agent$id()


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.

Usage

Agent$persona_frame()


Method guardrail_set()

The agent's guardrails() object, or NULL when none are attached. Used by the persistence and approval-checkpoint layers so a rebuilt agent keeps its policy.

Usage

Agent$guardrail_set()


Method usage()

Totals: calls made, tokens spent, tool calls, elapsed time, and the number of operations whose usage was not reported.

Usage

Agent$usage()

Returns

A one-row tibble with calls, tokens_sent, tokens_received, tokens_total, tool_calls, seconds, and n_unknown_usage.


Method transcript()

The agent's own conversation memory as a tibble.

Usage

Agent$transcript()


Method reset()

Forget the conversation (memory only; trace and usage counters are kept, since money was spent).

Usage

Agent$reset()


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. Accounting saved without n_unknown_usage restores that count as NA.

Usage

Agent$restore_accounting(usage = NULL, spans = NULL, agent_id = NULL)

Arguments

usage

A list or one-row frame with calls, tokens_sent, tokens_received, tool_calls, and optionally n_unknown_usage.

spans

A list of span records as returned by $internal_spans().

agent_id

The agent's persisted id (so a reloaded agent keeps its identity for leakage checks).

Returns

The agent, invisibly.


Method print()

Compact printout. When some usage was not reported, a line says that the token totals include only recorded usage.

Usage

Agent$print(...)

Arguments

...

Ignored.

Returns

The agent, invisibly.


Method clone()

The objects of this class are cloneable with this method.

Usage

Agent$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.