The `Agent` class defines a modular LLM-based agent capable of responding to prompts using a defined role/instruction. It wraps an OpenAI-compatible chat model via the [`ellmer`](https://github.com/llrs/ellmer) package.
Each agent maintains its own message history and unique identity.
nameThe agent's name.
instructionThe agent's role/system prompt.
llm_objectThe underlying `ellmer::chat_openai` object.
agent_idA UUID uniquely identifying the agent.
model_providerThe name of the entity providing the model (eg. OpenAI)
model_nameThe name of the model to be used (eg. gpt-4.1-mini)
broadcast_historyA list of all past broadcast interactions.
budgetA budget in $ that the agent should not exceed.
budget_policyA list controlling budget behavior: on_exceed and warn_at.
budget_warnedInternal flag indicating whether warn_at notice was emitted.
costThe current cost of the agent
messagesPublic active binding for the conversation history. Assignment is validated automatically.
new()Initializes a new Agent with a specific role/instruction.
Agent$new(name, instruction, llm_object, budget = NA)nameA short identifier for the agent (e.g. `"translator"`).
instructionThe system prompt that defines the agent's role.
llm_objectThe LLM object generate by ellmer (eg. output of ellmer::chat_openai)
budgetNumerical value denoting the amount to set for the budget in US$ to a specific agent, if the budget is reached, an error will be thrown.
# An API KEY is required in order to invoke the Agent
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
) polar_bear_researcher <- Agent$new(
name = "POLAR BEAR RESEARCHER",
instruction = paste0(
"You are an expert in polar bears, ",
"you task is to collect information about polar bears. Answer in 1 sentence max."
),
llm_object = openai_4_1_mini
)
invoke()Sends a user prompt to the agent and returns the assistant's response.
Agent$invoke(prompt)promptA character string prompt for the agent to respond to.
The LLM-generated response as a character string.
\dontrun{
# An API KEY is required in order to invoke the Agent
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "translator",
instruction = "You are an Algerian citizen",
llm_object = openai_4_1_mini
)
agent$invoke("Continue this sentence: 1 2 3 viva")
}
generate_execute_r_code()Generate R code from natural language descriptions and optionally validate/execute it
Agent$generate_execute_r_code(
code_description,
validate = FALSE,
execute = FALSE,
interactive = TRUE,
env = globalenv()
)code_descriptionCharacter string describing the R code to generate
validateLogical indicating whether to validate the generated code syntax
executeLogical indicating whether to execute the generated code (use with caution)
interactiveLogical; if TRUE, ask for user confirmation before executing generated code
envEnvironment in which to execute the code if execute = TRUE. Default to globalenv
A list containing the generated code and validation/execution results
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
r_assistant <- Agent$new(
name = "R Code Assistant",
instruction = paste("You are an expert R programmer",
llm_object = openai_4_1_mini
)
# Generate code for data manipulation
result <- r_assistant$generate_execute_r_code(
code_description = "Calculate the summary of the mtcars dataframe",
validate = TRUE,
execute = TRUE,
interactive = TRUE
)
print(result)
}
set_budget()Set a budget to a specific agent, if the budget is reached, an error will be thrown
Agent$set_budget(amount_in_usd)amount_in_usdNumerical value denoting the amount to set for the budget,
\dontrun{
# An API KEY is required in order to invoke the Agent
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "translator",
instruction = "You are an Algerian citizen",
llm_object = openai_4_1_mini
)
agent$set_budget(amount_in_usd = 10.5) # this is equivalent to 10.5$
}
set_budget_policy()Configure how the agent behaves as it approaches or exceeds its budget. Use `warn_at` (0-1) to emit a one-time warning when spending reaches the specified fraction of the budget. When the budget is exceeded, `on_exceed` controls behavior: abort, warn and proceed, or ask interactively.
Agent$set_budget_policy(on_exceed = "abort", warn_at = 0.8)on_exceedOne of "abort", "warn", or "ask".
warn_atNumeric in (0,1); fraction of budget to warn at. Default 0.8.
\dontrun{
agent$set_budget(5)
agent$set_budget_policy(on_exceed = "ask", warn_at = 0.9)
}
keep_last_n_messages()Keep only the most recent `n` messages, discarding older ones while keeping the system prompt.
Agent$keep_last_n_messages(n = 2)nNumber of most recent messages to keep.
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "capital finder",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
agent$invoke("What is the capital of Algeria")
agent$invoke("What is the capital of Germany")
agent$invoke("What is the capital of Italy")
agent$keep_last_n_messages(n = 2)
}
add_message()Add a pre-formatted message to the conversation history
Agent$add_message(role, content)roleThe role of the message ("user", "assistant", or "system")
contentThe content of the message
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "AI assistant",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
agent$add_message("user", "Hello, how are you?")
agent$add_message("assistant", "I'm doing well, thank you!")
}
clear_and_summarise_messages()Summarises the agent's conversation history into a concise form and appends it to the system prompt. Unlike `update_instruction()`, this method does not override the existing instruction but augments it with a summary for future context.
After creating the summary, the method clears the conversation history and retains only the updated system prompt. This ensures that subsequent interactions start fresh but with the summary preserved as context.
Agent$clear_and_summarise_messages()\dontrun{
# Requires an OpenAI-compatible LLM from `ellmer`
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)agent <- Agent$new( name = "summariser", instruction = "You are a summarising assistant", llm_object = openai_4_1_mini )
agent$invoke("The quick brown fox jumps over the lazy dog.") agent$invoke("This is another example sentence.")
# Summarises and resets history agent$summarise_messages()
# Now only the system prompt (with summary) remains agent$messages }
update_instruction()Update the system prompt/instruction
Agent$update_instruction(new_instruction)new_instructionNew instruction to use. Not that the new instruction will override the old one
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "assistant",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
agent$update_instruction("You are a concise assistant.")
}
get_usage_stats()Get the current token count and estimated cost of the conversation
Agent$get_usage_stats()A list with token counts and cost information
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "assistant",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
agent$set_budget(1)
agent$invoke("What is the capital of Algeria?")
stats <- agent$get_usage_stats()
stats
}
reset_conversation_history()Reset the agent's conversation history while keeping the system instruction
Agent$reset_conversation_history()\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "AI assistant",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
agent$invoke("Hello, how are you?")
agent$invoke("Tell me about machine learning")
agent$reset_conversation_history() # Clears all messages except system prompt
}
export_messages_history()Saves the agent's current conversation history as a JSON file on disk.
Agent$export_messages_history(
file_path = paste0(getwd(), "/", paste0(self$name, "_messages.json"))
)file_pathCharacter string specifying the file path where the JSON file should be saved. Defaults to a file named `"<agent_name>_messages.json"` in the current working directory.
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "capital_finder",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
agent$invoke("What is the capital of Algeria")
agent$invoke("What is the capital of Italy")
agent$export_messages_history()
}
load_messages_history()Load an agent's conversation history as a JSON file from disk.
Agent$load_messages_history(
file_path = paste0(getwd(), "/", paste0(self$name, "_messages.json"))
)file_pathCharacter string specifying the file path where the JSON file is stored. Defaults to a file named `"<agent_name>_messages.json"` in the current working directory.
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "capital_finder",
instruction = "You are an assistant.",
llm_object = openai_4_1_mini
)
# use the export_messages_history to save the interaction first
agent$load_messages_history("path/to/messages.json")
agent$messages
agent$llm_object
}
validate_response()Validates an agent's response against custom criteria using LLM-based validation. This method uses the agent's LLM to evaluate whether a response meets specified validation criteria (e.g., accuracy, completeness, tone, format).
Agent$validate_response(
prompt,
response,
validation_criteria,
validation_score = 0.8
)promptThe prompt used to generate the response.
responseThe response text to validate.
validation_criteriaThe criteria for validation. (e.g., "The response should be accurate and complete", "The response must be under 100 words").
validation_scoreA numeric from 0 to 1 denoting the score to consider for the evaluation. During the evaluation, the agent will provide a score from 0 to 1, a provided score greater or equal to the `validation_score` will result in a `valid` response. Defaults to 0.8.
list object
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "fact_checker",
instruction = "You are a factual assistant.",
llm_object = openai_4_1_mini
)
prompt <- "What is the capital of Algeria?"
response <- agent$invoke(prompt)
validation <- agent$validate_response(
response = response,
prompt = prompt,
validation_criteria = "The response must be accurate and mention Algiers",
validation_score = 0.8
)
print(validation)
}
clone_agent()Create a copy of the agent with the same instruction and configuration but a new unique ID. Useful for creating multiple instances of the same agent type.
Agent$clone_agent(new_name = NULL)new_nameOptional character string to assign a new name to the cloned agent. If NULL, the cloned agent retains the original name.
A new Agent instance with the same configuration but a unique ID.
\dontrun{
openai_4_1_mini <- ellmer::chat(
name = "openai/gpt-4.1-mini",
api_key = Sys.getenv("OPENAI_API_KEY"),
echo = "none"
)
agent <- Agent$new(
name = "translator",
instruction = "You are a translator.",
llm_object = openai_4_1_mini
)
# Clone with same name
agent_copy <- agent$clone_agent()
}
clone()The objects of this class are cloneable with this method.
Agent$clone(deep = FALSE)deepWhether to make a deep clone.
[load_messages_history()] for reloading a saved message history.
[export_messages_history()] for exporting the messages object to json.