Chat Sessions

A ChatSession is the central object for managing stateful conversations. It handles message history, tool execution state, model switching, and serialization.

Creating a Session

You can create a session directly or through an agent.

library(aisdk)

model <- create_openai()$language_model("gpt-4o")

# Option 1: Direct creation
session <- ChatSession$new(
  model = model,
  system_prompt = "You are a helpful R expert."
)

# Option 2: From an agent (inherits agent's tools and persona)
# coder <- create_coder_agent()
# session <- coder$create_session(model = model)

Basic Interaction

Use $send() for standard requests and $send_stream() for streaming responses.

# Send a message
response <- session$send("How do I use R6 classes?")
cat(response$text)

# The session automatically remembers the history
response2 <- session$send("Can you give me a code example?")
cat(response2$text)

Model Switching

You can switch the underlying model at any point. The conversation history remains intact.

# Switch to a different model mid-session
session$switch_model("anthropic:claude-3-5-sonnet-20241022")

# Continue the conversation with the new model
session$send("Now rewrite that example using S4.")

State Management

Sessions provide a shared environment and a “memory” list, which are essential for multi-agent systems where agents need to share data.

Shared Environment (.envir)

This is a real R environment where agents can store and retrieve data frames, models, and other objects.

env <- session$get_envir()
env$data <- iris

# Agents with tool access can now see 'data'

Shared Memory

A simple key-value store for metadata or state flags.

session$set_memory("current_status", "processing_data")
status <- session$get_memory("current_status")

Persistence

Sessions can be saved to disk as RDS or JSON files and restored later.

# Save session state
session$save("my_analysis.json")

# Restore session in a new process
new_session <- ChatSession$new(model = model)
new_session$restore("my_analysis.json")

Console Chat

For a quick interactive REPL experience in the R console, use console_chat(). It is built on top of the same session model, so you can chat interactively, switch models, inspect history, and persist state without leaving the terminal.

# Starts an interactive chat loop in the console
# console_chat(model = "openai:gpt-4o")

Key capabilities:

  • clean, inspect, and debug view modes for different levels of output detail
  • inline tool execution summaries for agent-driven turns
  • an inspector overlay for the latest turn or a specific tool
  • session persistence with /save and /load
  • model switching with /model <id>
  • optional local execution mode with /local [on|off]

Useful commands during a session:

  • /inspect on: switch to inspect mode
  • /inspect turn: open the latest turn in the inspector overlay
  • /inspect tool <index>: inspect a specific tool
  • /inspect next / /inspect prev: move between tools in the inspector
  • /debug on: enable detailed troubleshooting output
  • /stats: review session usage statistics
  • /history: show the conversation history

For a deeper terminal walkthrough, including inspect/debug modes and overlay navigation, see the Console Chat vignette. For more details on how agents interact with sessions, see the Agents vignette.