Skip to contents

deputy

ellmer lets a language model call your R functions as tools. Deputy turns that loop into an agent you can leave running: it checks each tool call against a permission policy before it runs, stops the run at the limits you set, and hands back a record of everything that happened.

Installation

Deputy is not on CRAN yet. Install the development version from GitHub:

# install.packages("pak")
pak::pak("JamesHWade/deputy")

Example

Run this from the root of an R package. It uses OpenAI, so set OPENAI_API_KEY first, or use any other ellmer chat.

library(deputy)

agent <- Agent$new(
  chat = ellmer::chat("openai/gpt-6-luna"),
  tools = tools_preset("minimal"),
  permissions = permissions_readonly(),
  usage_limits = UsageLimits(max_requests = 6, max_tool_calls = 8)
)

result <- agent$run_sync(
  "Read DESCRIPTION and list R/. What does this package do? Cite the files you used."
)
result$response

The agent can list directories and read any file your R session can read. It can’t write files or run code, and it stops after six model requests or eight tool calls, whichever comes first. The result tells you how the run went:

result$stop_reason        # "complete", or the limit that stopped the run
result$usage              # requests, tool calls, tokens and cost
result_tool_calls(result) # each tool call the model made, with its arguments

Get started walks through this example, then gives an agent permission to write a file and shows how to undo what it wrote.

What Deputy adds to ellmer

  • Tools for reading, searching and editing files, reading data, fetching web pages and running code. Any R function wrapped with ellmer::tool() works too.
  • Permissions and limits: presets from read-only to full access, writes confined to one directory, and callbacks that decide individual calls. Cap requests, tool calls, tokens or cost per run. You can narrow an agent’s permissions later, never widen them.
  • Hooks that run your R code before and after tool calls, to log, block or ask a person.
  • Approvals that pause a run before a tool executes and resume it once someone decides, even from a new R session.
  • File checkpoints that undo changes made by Deputy’s write and edit tools.
  • Structured output: finish a task with tools, then extract a typed R value from the conversation.
  • Compaction and saved conversations for conversations that outgrow the model’s context window.
  • Shiny: an agent works anywhere shinychat expects an ellmer chat.
  • Subagents with their own prompts, tools, permissions and budgets.
  • Sandboxed code execution through mcp-repl and MCP Console, and tools from any MCP server.
  • Trusted results: guarantee that the results you show a user come from a designated tool, never from model text.
  • Fallback chats for provider outages, OpenTelemetry tracing, and background jobs that survive the R session that queued them.

Run it from a terminal

Deputy includes a command-line app built with Rapp. Run it once with ir’s rx, or install a launcher:

uv tool install r-lib-ir
rx --from github::JamesHWade/deputy deputy --help
rx --from github::JamesHWade/deputy deputy --tools minimal \
  "Summarize the R files in this project"

ir tool install github::JamesHWade/deputy
deputy --tools minimal

The app uses OpenAI’s gpt-5.6-luna unless you pass --model, or --provider to switch provider (for example --provider anthropic).

Status

Deputy is experimental, and its API still changes. Please report bugs and ideas in GitHub Issues.

License

MIT © James Wade