Chat: The Chat object
In ellmer: Chat with Large Language Models
Chat R Documentation
The Chat object
Description
A Chat is a sequence of user and assistant Turns sent
to a specific Provider. A Chat is a mutable R6 object that takes care of
managing the state associated with the chat; i.e. it records the messages
that you send to the server, and the messages that you receive back.
If you register a tool (i.e. an R function that the assistant can call on
your behalf), it also takes care of the tool loop.
You should generally not create this object yourself,
but instead call chat_openai() or friends instead.
Value
A Chat object
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Chat$new()
Usage
Chat$new(provider, system_prompt = NULL, echo = "none")
Arguments
providerA provider object.
system_promptSystem prompt to start the conversation with.
echoOne of the following options:
-
none: don't emit any output (default when running in a function).
-
output: echo text and tool-calling output as it streams in (default
when running at the console).
-
all: echo all input and output.
Note this only affects the chat() method. You can override the default
by setting the ellmer_echo option.
Chat$get_turns()
Retrieve the turns that have been sent and received so far
(optionally starting with the system prompt, if any).
Usage
Chat$get_turns(include_system_prompt = FALSE)
Arguments
include_system_promptWhether to include the system prompt in the
turns (if any exists).
Chat$set_turns()
Replace existing turns with a new list.
Usage
Chat$set_turns(value)
Arguments
valueA list of Turns.
Chat$add_turn()
Add a pair of turns to the chat.
Usage
Chat$add_turn(user, assistant, log_tokens = TRUE)
Arguments
userThe user Turn.
assistantThe system Turn.
log_tokensShould tokens used in the turn be logged to the
session counter?
Chat$get_system_prompt()
If set, the system prompt, it not, NULL.
Usage
Chat$get_system_prompt()
Chat$get_model()
Retrieve the model name
Usage
Chat$get_model()
Chat$set_model()
Update the model name. Note that unlike some of the
chat_*() functions, the model name is not validated against available
models for the provider.
Usage
Chat$set_model(model)
Arguments
modelA single string giving the new model name.
Chat$set_system_prompt()
Update the system prompt
Usage
Chat$set_system_prompt(value)
Arguments
valueA character vector giving the new system prompt
Chat$get_tokens()
A data frame with token usage and cost data. There are four
columns: input, output, cached_input, and cost. There is one
row for each assistant turn, because token counts and costs are only
available when the API returns the assistant's response.
Usage
Chat$get_tokens(include_system_prompt = deprecated())
Arguments
include_system_prompt![[Deprecated]](../help/figures/lifecycle-deprecated.svg)
Chat$get_cost()
The cost of this chat
Usage
Chat$get_cost(include = c("all", "last"))
Arguments
includeThe default, "all", gives the total cumulative cost
of this chat. Alternatively, use "last" to get the cost of just the
most recent turn. Incomplete turns (from cancelled or interrupted
streams) are excluded because they lack token data.
Chat$last_turn()
The last turn returned by the assistant.
Usage
Chat$last_turn(role = c("assistant", "user", "system"))
Arguments
roleOptionally, specify a role to find the last turn with
for the role.
Returns
Either a Turn or NULL, if no turns with the specified
role have occurred.
Chat$chat()
Submit input to the chatbot, and return the response as a
simple string (probably Markdown).
Usage
Chat$chat(..., echo = NULL)
Arguments
...The input to send to the chatbot. Can be strings or images
(see content_image_file() and content_image_url().
echoWhether to emit the response to stdout as it is received. If
NULL, then the value of echo set when the chat object was created
will be used.
Chat$chat_structured()
Extract structured data.
Note: tool calling is disabled during structured data extraction. See
vignette("structured-data") for details and workarounds.
Usage
Chat$chat_structured(..., type, echo = "none", convert = TRUE)
Arguments
...The input to send to the chatbot. This is typically the text
you want to extract data from, but it can be omitted if the data is
obvious from the existing conversation.
typeA type specification for the extracted data. Should be
created with a type_() function.
echoWhether to emit the response to stdout as it is received.
Set to "text" to stream JSON data as it's generated (not supported by
all providers).
convertAutomatically convert from JSON lists to R data types
using the schema. For example, this will turn arrays of objects into
data frames and arrays of strings into a character vector.
Chat$chat_structured_async()
Extract structured data, asynchronously. Returns a promise
that resolves to an object matching the type specification.
Usage
Chat$chat_structured_async(..., type, echo = "none", convert = TRUE)
Arguments
...The input to send to the chatbot. Will typically include
the phrase "extract structured data".
typeA type specification for the extracted data. Should be
created with a type_() function.
echoWhether to emit the response to stdout as it is received.
Set to "text" to stream JSON data as it's generated (not supported by
all providers).
convertAutomatically convert from JSON lists to R data types
using the schema. For example, this will turn arrays of objects into
data frames and arrays of strings into a character vector.
Chat$chat_async()
Submit input to the chatbot, and receive a promise that
resolves with the response all at once. Returns a promise that resolves
to a string (probably Markdown).
Usage
Chat$chat_async(..., tool_mode = c("concurrent", "sequential"))
Arguments
...The input to send to the chatbot. Can be strings or images.
tool_modeWhether tools should be invoked one-at-a-time
("sequential") or concurrently ("concurrent"). Sequential mode is
best for interactive applications, especially when a tool may involve
an interactive user interface. Concurrent mode is the default and is
best suited for automated scripts or non-interactive applications.
Chat$stream()
Submit input to the chatbot, returning streaming results.
Returns A coro generator
that yields strings. While iterating, the generator will block while
waiting for more content from the chatbot.
Usage
Chat$stream(..., stream = c("text", "content"), controller = NULL)
Arguments
...The input to send to the chatbot. Can be strings or images.
streamWhether the stream should yield only "text" or ellmer's
rich content types. When stream = "content", stream() yields
Content objects.
controllerAn optional stream_controller() used to cancel the
stream from outside the iteration loop.
Chat$stream_async()
Submit input to the chatbot, returning asynchronously
streaming results. Returns a coro async generator that
yields string promises.
Usage
Chat$stream_async(
...,
tool_mode = c("concurrent", "sequential"),
stream = c("text", "content"),
controller = NULL
)
Arguments
...The input to send to the chatbot. Can be strings or images.
tool_modeWhether tools should be invoked one-at-a-time
("sequential") or concurrently ("concurrent"). Sequential mode is
best for interactive applications, especially when a tool may involve
an interactive user interface. Concurrent mode is the default and is
best suited for automated scripts or non-interactive applications.
streamWhether the stream should yield only "text" or ellmer's
rich content types. When stream = "content", stream() yields
Content objects.
controllerAn optional stream_controller() used to cancel the
stream from outside the iteration loop.
Chat$register_tool()
Register a tool (an R function) that the chatbot can use.
Learn more in vignette("tool-calling").
Usage
Chat$register_tool(tool)
Arguments
toolA tool definition created by tool().
Chat$register_tools()
Register a list of tools.
Learn more in vignette("tool-calling").
Usage
Chat$register_tools(tools)
Arguments
toolsA list of tool definitions created by tool().
Chat$get_provider()
Get the underlying provider object. For expert use only.
Usage
Chat$get_provider()
Chat$get_tools()
Retrieve the list of registered tools.
Usage
Chat$get_tools()
Chat$set_tools()
Sets the available tools. For expert use only; most users
should use register_tool().
Usage
Chat$set_tools(tools)
Arguments
toolsA list of tool definitions created with tool().
Chat$on_tool_request()
Register a callback for a tool request event.
Usage
Chat$on_tool_request(callback)
Arguments
callbackA function to be called when a tool request event occurs,
which must have request as its only argument.
Returns
A function that can be called to remove the callback.
Chat$on_tool_result()
Register a callback for a tool result event.
Usage
Chat$on_tool_result(callback)
Arguments
callbackA function to be called when a tool result event occurs,
which must have result as its only argument.
Returns
A function that can be called to remove the callback.
Chat$clone()
The objects of this class are cloneable with this method.
Usage
Chat$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
chat <- chat_openai()
chat$chat("Tell me a funny joke")
ellmer documentation built on July 14, 2026, 1:07 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Chat | R Documentation |
The Chat object
Description
A Chat is a sequence of user and assistant Turns sent
to a specific Provider. A Chat is a mutable R6 object that takes care of
managing the state associated with the chat; i.e. it records the messages
that you send to the server, and the messages that you receive back.
If you register a tool (i.e. an R function that the assistant can call on
your behalf), it also takes care of the tool loop.
You should generally not create this object yourself,
but instead call chat_openai() or friends instead.
Value
A Chat object
Methods
Public methods
Chat$new()
Usage
Chat$new(provider, system_prompt = NULL, echo = "none")
Arguments
providerA provider object.
system_promptSystem prompt to start the conversation with.
echoOne of the following options:
-
none: don't emit any output (default when running in a function). -
output: echo text and tool-calling output as it streams in (default when running at the console). -
all: echo all input and output.
Note this only affects the
chat()method. You can override the default by setting theellmer_echooption.-
Chat$get_turns()
Retrieve the turns that have been sent and received so far (optionally starting with the system prompt, if any).
Usage
Chat$get_turns(include_system_prompt = FALSE)
Arguments
include_system_promptWhether to include the system prompt in the turns (if any exists).
Chat$set_turns()
Replace existing turns with a new list.
Usage
Chat$set_turns(value)
Arguments
valueA list of Turns.
Chat$add_turn()
Add a pair of turns to the chat.
Usage
Chat$add_turn(user, assistant, log_tokens = TRUE)
Arguments
userThe user Turn.
assistantThe system Turn.
log_tokensShould tokens used in the turn be logged to the session counter?
Chat$get_system_prompt()
If set, the system prompt, it not, NULL.
Usage
Chat$get_system_prompt()
Chat$get_model()
Retrieve the model name
Usage
Chat$get_model()
Chat$set_model()
Update the model name. Note that unlike some of the
chat_*() functions, the model name is not validated against available
models for the provider.
Usage
Chat$set_model(model)
Arguments
modelA single string giving the new model name.
Chat$set_system_prompt()
Update the system prompt
Usage
Chat$set_system_prompt(value)
Arguments
valueA character vector giving the new system prompt
Chat$get_tokens()
A data frame with token usage and cost data. There are four
columns: input, output, cached_input, and cost. There is one
row for each assistant turn, because token counts and costs are only
available when the API returns the assistant's response.
Usage
Chat$get_tokens(include_system_prompt = deprecated())
Arguments
include_system_prompt
Chat$get_cost()
The cost of this chat
Usage
Chat$get_cost(include = c("all", "last"))
Arguments
includeThe default,
"all", gives the total cumulative cost of this chat. Alternatively, use"last"to get the cost of just the most recent turn. Incomplete turns (from cancelled or interrupted streams) are excluded because they lack token data.
Chat$last_turn()
The last turn returned by the assistant.
Usage
Chat$last_turn(role = c("assistant", "user", "system"))
Arguments
roleOptionally, specify a role to find the last turn with for the role.
Returns
Either a Turn or NULL, if no turns with the specified
role have occurred.
Chat$chat()
Submit input to the chatbot, and return the response as a simple string (probably Markdown).
Usage
Chat$chat(..., echo = NULL)
Arguments
...The input to send to the chatbot. Can be strings or images (see
content_image_file()andcontent_image_url().echoWhether to emit the response to stdout as it is received. If
NULL, then the value ofechoset when the chat object was created will be used.
Chat$chat_structured()
Extract structured data.
Note: tool calling is disabled during structured data extraction. See
vignette("structured-data") for details and workarounds.
Usage
Chat$chat_structured(..., type, echo = "none", convert = TRUE)
Arguments
...The input to send to the chatbot. This is typically the text you want to extract data from, but it can be omitted if the data is obvious from the existing conversation.
typeA type specification for the extracted data. Should be created with a
type_()function.echoWhether to emit the response to stdout as it is received. Set to "text" to stream JSON data as it's generated (not supported by all providers).
convertAutomatically convert from JSON lists to R data types using the schema. For example, this will turn arrays of objects into data frames and arrays of strings into a character vector.
Chat$chat_structured_async()
Extract structured data, asynchronously. Returns a promise that resolves to an object matching the type specification.
Usage
Chat$chat_structured_async(..., type, echo = "none", convert = TRUE)
Arguments
...The input to send to the chatbot. Will typically include the phrase "extract structured data".
typeA type specification for the extracted data. Should be created with a
type_()function.echoWhether to emit the response to stdout as it is received. Set to "text" to stream JSON data as it's generated (not supported by all providers).
convertAutomatically convert from JSON lists to R data types using the schema. For example, this will turn arrays of objects into data frames and arrays of strings into a character vector.
Chat$chat_async()
Submit input to the chatbot, and receive a promise that resolves with the response all at once. Returns a promise that resolves to a string (probably Markdown).
Usage
Chat$chat_async(..., tool_mode = c("concurrent", "sequential"))
Arguments
...The input to send to the chatbot. Can be strings or images.
tool_modeWhether tools should be invoked one-at-a-time (
"sequential") or concurrently ("concurrent"). Sequential mode is best for interactive applications, especially when a tool may involve an interactive user interface. Concurrent mode is the default and is best suited for automated scripts or non-interactive applications.
Chat$stream()
Submit input to the chatbot, returning streaming results. Returns A coro generator that yields strings. While iterating, the generator will block while waiting for more content from the chatbot.
Usage
Chat$stream(..., stream = c("text", "content"), controller = NULL)
Arguments
...The input to send to the chatbot. Can be strings or images.
streamWhether the stream should yield only
"text"or ellmer's rich content types. Whenstream = "content",stream()yields Content objects.controllerAn optional
stream_controller()used to cancel the stream from outside the iteration loop.
Chat$stream_async()
Submit input to the chatbot, returning asynchronously streaming results. Returns a coro async generator that yields string promises.
Usage
Chat$stream_async(
...,
tool_mode = c("concurrent", "sequential"),
stream = c("text", "content"),
controller = NULL
)
Arguments
...The input to send to the chatbot. Can be strings or images.
tool_modeWhether tools should be invoked one-at-a-time (
"sequential") or concurrently ("concurrent"). Sequential mode is best for interactive applications, especially when a tool may involve an interactive user interface. Concurrent mode is the default and is best suited for automated scripts or non-interactive applications.streamWhether the stream should yield only
"text"or ellmer's rich content types. Whenstream = "content",stream()yields Content objects.controllerAn optional
stream_controller()used to cancel the stream from outside the iteration loop.
Chat$register_tool()
Register a tool (an R function) that the chatbot can use.
Learn more in vignette("tool-calling").
Usage
Chat$register_tool(tool)
Arguments
toolA tool definition created by
tool().
Chat$register_tools()
Register a list of tools.
Learn more in vignette("tool-calling").
Usage
Chat$register_tools(tools)
Arguments
toolsA list of tool definitions created by
tool().
Chat$get_provider()
Get the underlying provider object. For expert use only.
Usage
Chat$get_provider()
Chat$get_tools()
Retrieve the list of registered tools.
Usage
Chat$get_tools()
Chat$set_tools()
Sets the available tools. For expert use only; most users
should use register_tool().
Usage
Chat$set_tools(tools)
Arguments
toolsA list of tool definitions created with
tool().
Chat$on_tool_request()
Register a callback for a tool request event.
Usage
Chat$on_tool_request(callback)
Arguments
callbackA function to be called when a tool request event occurs, which must have
requestas its only argument.
Returns
A function that can be called to remove the callback.
Chat$on_tool_result()
Register a callback for a tool result event.
Usage
Chat$on_tool_result(callback)
Arguments
callbackA function to be called when a tool result event occurs, which must have
resultas its only argument.
Returns
A function that can be called to remove the callback.
Chat$clone()
The objects of this class are cloneable with this method.
Usage
Chat$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
chat <- chat_openai()
chat$chat("Tell me a funny joke")
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.