Run an agent in this R session

peter() is the single entry point. Give it a quoted prompt and, optionally, the objects the agent should work on; it returns the agent session, which you can print, query ($text, $value, $usage) and continue with the pipe. Models, modes, skills, plugins, extensions and tools may be written as bare names.

Usage

peter(..., model = NULL, mode = NULL, skills = NULL, plugins = NULL,
      extensions = NULL, tools = NULL, agents = NULL, parallel = NULL,
      choices = NULL, levels = NULL, threshold = 0.5,
      min_confidence = NULL, uncertain = NULL,
      prompt = NULL, envir = parent.frame(), background = FALSE,
      budget = NULL, replay = NULL, .opts = list(), .run = TRUE,
      .stdin = FALSE)

Arguments

...: A session to continue, the prompt, and context objects.
model: A model name (sonnet, "anthropic/claude-sonnet-5-5"), a provider or router spec such as gptr_fake_provider(), or NULL for the configured default.
mode: One of plan, manual, edits, auto; NULL for the configured default.
skills, plugins, extensions: Names (bare or quoted) of skills to preload, plugins and extensions to enable for this session; extensions also takes function(gptr) factories and file paths.
tools: Tool names, "+name"/"-name" modifiers, a preset name, or gptr_tool() specs.
agents: A named list of agent definitions for a team (agent() means gptr_agent()).
parallel: Fan one list-like context object out over this many concurrent sub-agents.
choices, levels, threshold, min_confidence, uncertain: System 1 answer shape and abstention.
prompt: An explicit prompt; wins over positional selection.
envir: Where the agent evaluates R code and creates objects.
background: Experimental: return the running session at once (needs later).
budget: list(tokens =, cost =, turns =) limits for this call.
replay: Document replay mode: "auto", "replay", "live" or "record".
.opts: Rare switches such as thinking, max_turns, context, returns, images, preset, and entries named by a plugin namespace.
.run: FALSE builds the session with the prompt queued and returns it (see gptr_step()).
.stdin: Drive the console from piped standard input.

Value

A gptr_session for agent work (invisibly when its answer was streamed to the console), or a typed System 1 vector for classifier models.

Details

Conversational agents compute in memory: their R tools use the objects already loaded in envir, and later turns can reuse fitted models and intermediate results without saving and reloading the dataset. Model context contains bounded descriptions and requested results; R computes on the full local object. Ordinary R allocations, file-backed inputs, checkpoints and worker transfers still have their usual costs. See vignette("execution-model", package = "gptr") for these boundaries.

The dots take, in order: at most one leading session to continue, the prompt (the first unnamed string literal, else the first unnamed length-1 character value), and context objects (unnamed ones are labeled by their expression, named ones by name). Conversational context bindings refer to objects where they live; descriptions are budgeted separately from in-memory R computation. Every other argument is matched by its exact name only.

A literal prompt gets {name} interpolation from envir (atomic vectors of 1 to 50 values; {{ and }} are literal braces); .opts = list(interpolate = FALSE) switches it off.

Terminal statuses become conditions carrying the session as $session: error signals gptr_error_provider, blocked gptr_error_permission, budget gptr_error_budget_<kind> and max_turns gptr_error_max_turns. peter() with no prompt opens the console when someone can answer, and signals gptr_error_noninteractive otherwise.

A new interactive console without an explicit or configured model first offers CLI selection or manual API/Ollama instructions. Selecting an available CLI saves its default at user scope; cancellation or manual setup returns without starting a session. Existing sessions, explicit or configured models and .stdin = TRUE skip setup. CLI-reported login is not proof of online access or subscription billing. See vignette("interactive-console", package = "gptr").

The name honors Peter Cathcart Wason, whose research with Jonathan Evans distinguished processes underlying reasoning and introspection, and Peter Naur of the Backus-Naur form, in the spirit of recording sessions as readable, replayable documents. A user object named peter hides the gateway; call gptr::peter() then.

The interactive console

peter() without a prompt opens a console when someone can answer (interactive R or IRkernel); peter(.stdin = TRUE) reads its input from standard input, and session |> peter() opens it on session. With no explicit or configured model, the interactive console first offers Codex CLI, Claude Code CLI or API configuration instructions. Choosing an available CLI saves its default model at user scope; cancelling returns to R. Piped input skips this setup. Each input is one of:

a prompt, sent as session |> peter("...") with {name} interpolation; @file adds the head of a file (at most 40 lines) and @object attaches an object by name;
!code: R code run in the session's environment; the code and its output go with the next prompt (at most 300 estimated tokens). !!code omits that note. Both execute your own R immediately, without the model's permission gate or a model request. Workspace changes remain visible to later calls, and enabled transcripts can record the code; !! is not a privacy boundary. A fenced R block works like !code, a """ block is a multi-line prompt, and a trailing backslash continues a line;
a slash command such as /model, /mode, /cost or /exit; /help lists them all.

Ctrl-C while an answer runs opens a pause menu in supported terminal front ends: [s]teer (delivered after the current tool results), [f]ollow-up, [c]ontinue, [a]bort and, for a foreground call (including a chat turn) when available, [b]ackground; a second Ctrl-C aborts. Backgrounding returns to the chat prompt; use !!gptr::gptr_wait(gptr::gptr_last()) there to wait for completion. Returning to the prompt does not guarantee progress while the chat waits for input. Under Rscript, background runs advance only inside blocking gptr calls. Front ends that cannot resume use an abort fallback. /exit, two consecutive interrupts at the prompt or the end of piped input return the session invisibly, so session = peter() keeps the conversation. Use Ctrl-C in a terminal; RStudio, R.app, RGui and Positron use Esc.

Options: gptr.verbose (0 silent, 1 progress, 2 streamed console, 3 debug; default 0 in knitr and testthat, 1 under Rscript, 2 at the console), gptr.max_turns_console (turns per console prompt, default 200) and gptr.history (console inputs to R's history, default TRUE). Ordinary progress uses normal output; actual errors use stderr. vignette("interactive-console", package = "gptr") gives input examples and the complete built-in command table.

Sessions and results

A pipe such as session |> peter("Explain the result.") adds work to the same session and kept workspace. Use gptr_fork() to branch explicitly. The final answer is session$text; session$value is the R value selected by gptr_return() during a tool call. Agent-created objects remain in envir.

Examples

fake = gptr_fake_provider(list("The data has 32 rows.", "The data has 11 columns."))
session = peter("How many rows does the data have?", mtcars, model = fake)
#> gptr: thinking
#> gptr: done · 1 turn · 1.6k tokens · $0.0000
session$text
#> [1] "The data has 32 rows."
session |> peter("And how many columns?")
#> gptr: thinking
#> gptr: done · 2 turns · 1.7k tokens · $0.0000
#> The data has 11 columns.
#> idle · fake/fake-1 · 2 turns · 3.3k tokens · $0.0000 · s5504b20efb
identical(gptr_last(), session)
#> [1] TRUE