## ----include=FALSE------------------------------------------------------------
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>",
  eval = identical(tolower(Sys.getenv("LLMRAGENT_RUN_VIGNETTES", "false")), "true")
)

## ----setup--------------------------------------------------------------------
# library(LLMRagent)
# cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b", temperature = 0.3)

## ----tool---------------------------------------------------------------------
# lookup_population <- agent_tool(
#   function(city) {
#     pops <- c(Chicago = 2.7, Detroit = 0.6, Austin = 1.0)  # millions
#     pops[[city]] %||% NA_real_
#   },
#   name = "lookup_population",
#   description = "Population of a US city in millions.",
#   parameters = list(city = list(type = "string")),
#   required = "city",
#   side_effects = "read",   # this tool only reads
#   max_calls = 5            # and may run at most five times
# )

## ----use-tool-----------------------------------------------------------------
# demographer <- agent("Demographer", cfg, tools = list(lookup_population),
#                      persona = "Use the lookup tool for any population figure.")
# demographer$chat("Which is larger, Chicago or Austin, and by how much?")

## ----guardrails---------------------------------------------------------------
# no_pii <- guardrail(
#   "no_email_in_output",
#   check = function(payload, context) {
#     if (grepl("[[:alnum:]._]+@[[:alnum:].]+", payload)) "output contains an email address" else TRUE
#   },
#   on_fail = "block",
#   stage = "output"
# )
# 
# careful <- agent("Careful", cfg, guardrails = guardrails(no_pii),
#                  persona = "You answer questions about contacting the registrar.")
# 
# # a normal answer passes; an answer that leaks an address is blocked
# tryCatch(
#   careful$chat("Give me a fake example email for the registrar."),
#   llmragent_guardrail_block = function(e) "blocked: the output guardrail stopped a leak"
# )

## ----gate---------------------------------------------------------------------
# send_email <- agent_tool(
#   function(to, body) paste0("SENT to ", to, ": ", body),
#   name = "send_email",
#   description = "Send an email to a recipient.",
#   parameters = list(to = list(type = "string"), body = list(type = "string")),
#   required = c("to", "body"),
#   side_effects = "external",
#   requires_approval = TRUE
# )
# 
# assistant <- agent("Assistant", cfg, tools = list(send_email),
#                    persona = "You help draft and send short emails.")
# 
# checkpoint <- tryCatch(
#   assistant$chat("Email j.doe@example.edu to confirm Tuesday's meeting."),
#   llmragent_pending_approval = function(e) e$checkpoint
# )
# checkpoint    # shows the pending tool and its arguments

## ----approve------------------------------------------------------------------
# decided <- approve_tool_call(checkpoint, "approve")
# result  <- resume_run(decided)
# result    # the approved call ran, and the agent continued from where it paused