Skip to contents

Agent R6 class

Source: R/agent.R
Agent.Rd

A thin, opinionated wrapper around an ellmer::Chat object. Adds identity (name, role), conversation management helpers, and cumulative cost tracking. All LLM logic is delegated to ellmer.

Usage

agent(
  name,
  chat,
  role = NULL,
  instructions = NULL,
  tools = list(),
  handoffs = character(),
  max_retries = 3L,
  retry_wait = 5
)

Arguments

name

Character. Unique identifier for this agent within a workflow.

chat

An ellmer::Chat object (e.g. ellmer::chat_anthropic()).

role

Character or NULL. Short role description.

instructions

Character or NULL. Detailed system instructions.

tools

List of ellmer::tool() objects.

handoffs

Character vector of agent names for handoffs.

max_retries

Integer. Retries on transient API errors (default 3L).

retry_wait

Numeric. Seconds between retries (default 5).

Value

A new Agent object.

The assistant's response as a character string.

Parsed R object matching type.

A coro generator yielding text chunks.

A new Agent with the same configuration but no turns.

List of turn objects from ellmer.

Numeric, total USD spent so far.

Named list with input and output integer elements.

An Agent R6 object.

Functions

Active bindings

name

Agent name (read-only).

role

Agent role description (read-only).

handoffs

Names of agents this agent may hand off to (read-only).

Methods

Public methods

Method new()

Create a new Agent.

Usage

Agent$new(
  name,
  chat,
  role = NULL,
  instructions = NULL,
  tools = list(),
  handoffs = character(),
  max_retries = 3L,
  retry_wait = 5
)

Arguments

name

Character. Unique identifier used in graph node configs.

chat

An ellmer::Chat object (e.g. from ellmer::chat_anthropic()).

role

Character or NULL. Short role description prepended to the system prompt.

instructions

Character or NULL. Detailed instructions appended to the system prompt.

tools

List of ellmer::tool() objects to register on the chat.

handoffs

Character vector of agent names this agent may hand off to.

max_retries

Integer. Number of times to retry a failed API call before raising an error (default 3L). Set to 0L to disable retries.

retry_wait

Numeric. Seconds to wait between retries (default 5).

Method chat()

Send a message to the agent, retrying on transient errors.

Usage

Agent$chat(...)

Arguments

...

Passed to ellmer::Chat$chat().

Method chat_structured()

Send a message and receive a structured response.

Usage

Agent$chat_structured(..., type)

Arguments

...

Passed to ellmer::Chat$chat_structured().

type

An ellmer type specification for the structured output.

Method stream()

Stream a response from the agent.

Usage

Agent$stream(...)

Arguments

...

Passed to ellmer::Chat$stream().

Method clone_fresh()

Create a fresh copy of this agent with empty conversation history.

Usage

Agent$clone_fresh()

Method get_turns()

Return the current conversation turns.

Usage

Agent$get_turns()

Method set_turns()

Replace the conversation turns.

Usage

Agent$set_turns(turns)

Arguments

turns

List of turn objects.

Method get_cost()

Return cumulative cost for this agent.

Usage

Agent$get_cost()

Method get_tokens()

Return cumulative token counts.

Usage

Agent$get_tokens()

Method print()

Print a summary of the agent.

Usage

Agent$print(...)

Arguments

...

Ignored.

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.

Examples

if (FALSE) { # \dontrun{
ag <- agent(
  name        = "researcher",
  chat        = ellmer::chat_anthropic(),
  role        = "Senior researcher",
  instructions = "Be thorough and cite sources.",
  max_retries = 3L,
  retry_wait  = 5
)
} # }