R6 class representing a stateful chat session. Automatically manages conversation history, supports tool execution, and provides persistence.
new()Initialize a new ChatSession.
ChatSession$new(
model = NULL,
system_prompt = NULL,
tools = NULL,
hooks = NULL,
history = NULL,
max_steps = 10,
registry = NULL,
memory = NULL,
metadata = NULL,
envir = NULL,
agent = NULL
)modelA LanguageModelV1 object or model string ID (e.g., "openai:gpt-4o").
system_promptOptional system prompt for the conversation.
toolsOptional list of Tool objects for function calling.
hooksOptional HookHandler object for event hooks.
historyOptional initial message history (list of message objects).
max_stepsMaximum steps for tool execution loops. Default 10.
registryOptional ProviderRegistry for model resolution.
memoryOptional initial shared memory (list). For multi-agent state sharing.
metadataOptional session metadata (list). Used for channel/runtime state.
envirOptional shared R environment. For multi-agent data sharing.
agentOptional Agent object. If provided, the session inherits the agent's tools and system prompt.
send()Send a message and get a response.
ChatSession$send(prompt, ...)promptThe user message to send.
...Additional arguments passed to generate_text.
The GenerateResult object from the model.
send_stream()Send a message with streaming output.
ChatSession$send_stream(prompt, callback, ...)promptThe user message to send.
callbackFunction called for each chunk: callback(text, done).
...Additional arguments passed to stream_text.
Invisible NULL (output is via callback).
append_message()Append a message to the history.
ChatSession$append_message(role, content, reasoning = NULL)roleMessage role: "user", "assistant", "system", or "tool".
contentMessage content.
reasoningOptional reasoning text to attach to the message.
get_history()Get the conversation history.
ChatSession$get_history()A list of message objects.
get_last_response()Get the last response from the assistant.
ChatSession$get_last_response()The content of the last assistant message, or NULL.
clear_history()Clear the conversation history.
ChatSession$clear_history(keep_system = TRUE)keep_systemIf TRUE, keeps the system prompt. Default TRUE.
switch_model()Switch to a different model.
ChatSession$switch_model(model)modelA LanguageModelV1 object or model string ID.
get_model_id()Get current model identifier.
ChatSession$get_model_id()Model ID string.
stats()Get token usage statistics.
ChatSession$stats()A list with token counts and message stats.
pathFile path (supports .rds or .json extension).
formatOptional format override: "rds" or "json". Auto-detected from path.
as_list()Export session state as a list (for serialization).
ChatSession$as_list()A list containing session state.
restore()Restore session from a file.
ChatSession$restore(path, format = NULL)pathFile path (supports .rds or .json extension).
formatOptional format override: "rds" or "json". Auto-detected from path.
restore_from_list()Restore session state from a list.
ChatSession$restore_from_list(data)dataA list exported by as_list().
get_memory()Get a value from shared memory.
ChatSession$get_memory(key, default = NULL)keyThe key to retrieve.
defaultDefault value if key not found. Default NULL.
The stored value or default.
set_memory()Set a value in shared memory.
ChatSession$set_memory(key, value)keyThe key to store.
valueThe value to store.
Invisible self for chaining.
list_memory()List all keys in shared memory.
ChatSession$list_memory()Character vector of memory keys.
get_metadata()Get a value from session metadata.
ChatSession$get_metadata(key, default = NULL)keyThe metadata key to retrieve.
defaultDefault value if key is not present.
The stored metadata value or default.
set_metadata()Set a value in session metadata.
ChatSession$set_metadata(key, value)keyThe metadata key to set.
valueThe value to store.
Invisible self for chaining.
merge_metadata()Merge a named list into session metadata.
ChatSession$merge_metadata(values)valuesNamed list of metadata values.
Invisible self for chaining.
list_metadata()List metadata keys.
ChatSession$list_metadata()Character vector of metadata keys.
clear_memory()Clear shared memory.
ChatSession$clear_memory(keys = NULL)keysOptional specific keys to clear. If NULL, clears all.
Invisible self for chaining.
get_envir()Get the shared R environment.
ChatSession$get_envir()This environment is shared across all agents using this session. Agents can store and retrieve data frames, models, and other R objects.
An environment object.
eval_in_session()Evaluate an expression in the session environment.
ChatSession$eval_in_session(expr)exprAn expression to evaluate.
The result of the evaluation.
list_envir()List objects in the session environment.
ChatSession$list_envir()Character vector of object names.
checkpoint()Save a memory snapshot to a file (checkpoint for Mission resume).
ChatSession$checkpoint(path = NULL)pathFile path (.rds). If NULL, uses a temp file and returns the path.
Invisible file path.
restore_checkpoint()Restore memory and history from a checkpoint file.
ChatSession$restore_checkpoint(path)pathFile path to a checkpoint created by checkpoint().
Invisible self for chaining.
clone()The objects of this class are cloneable with this method.
ChatSession$clone(deep = FALSE)deepWhether to make a deep clone.