Turn: A user, assistant, or system turn

In ellmer: Chat with Large Language Models

A user, assistant, or system turn

Description

Every conversation with a chatbot consists of pairs of user and assistant turns, corresponding to an HTTP request and response. These turns are represented by the Turn object, which contains a list of Contents representing the individual messages within the turn. These might be text, images, tool requests (assistant only), or tool responses (user only).

UserTurn, AssistantTurn, and SystemTurn are specialized subclasses of Turn for different types of conversation turns. AssistantTurn includes additional metadata about the API response.

Note that a call to ⁠$chat()⁠ and related functions may result in multiple user-assistant turn cycles. For example, if you have registered tools, ellmer will automatically handle the tool calling loop, which may result in any number of additional cycles. Learn more about tool calling in vignette("tool-calling").

Usage

Turn(role = NULL, contents = list(), tokens = NULL)

UserTurn(contents = list())

SystemTurn(contents = list())

AssistantTurn(
  contents = list(),
  json = list(),
  tokens = c(NA_real_, NA_real_, NA_real_),
  cost = NA_real_,
  duration = NA_real_,
  finish_reason = NA_character_
)

AssistantPartialTurn(
  contents = list(),
  json = list(),
  tokens = c(NA_real_, NA_real_, NA_real_),
  cost = NA_real_,
  duration = NA_real_,
  finish_reason = NA_character_,
  reason = "interrupted"
)

Arguments

role	For system, user and assistant turns, use SystemTurn(), UserTurn(), and AssistantTurn(), respectively.
contents	A list of Content objects.
tokens	A numeric vector of length 3 representing the number of input tokens (uncached), output tokens, and input tokens (cached) used in this turn.
json	The serialized JSON corresponding to the underlying data of the turns. This is useful if there's information returned by the provider that ellmer doesn't otherwise expose.
cost	The cost of the turn in dollars.
duration	The duration of the request in seconds.
finish_reason	Why the model stopped generating. Standardized across providers to one of: "success", "tool_use", "max_tokens", "stop_sequence", "content_filter", or "context_window". Unrecognized provider-specific reasons are passed through as-is. NA when not available.
reason	A character string describing why the turn was interrupted. Defaults to "interrupted".

Value

An S7 Turn object

An S7 AssistantTurn object

An S7 AssistantPartialTurn object

Examples

UserTurn(list(ContentText("Hello, world!")))

ellmer documentation built on July 14, 2026, 1:07 a.m.