Chat with GitHub Copilot

The main entry point for conversational interaction with Copilot models. Maintains a persistent session across calls. The SDK agent has built-in tools for file operations, code search, and shell commands.

Usage

hal(..., model = NULL, use_env = NULL, reset = FALSE, inspect = FALSE)

Arguments

...: Character strings, concatenated as the user message.
model: Model identifier. If NULL, uses the session/configured default.
use_env: Logical or NULL; if TRUE, snapshots the caller's environment and injects it into the prompt so the model naturally uses eval_r to work with your R objects. If NULL (default), auto-detects: scans the prompt for R identifiers and injects the snapshot only when the prompt mentions an object that exists in the caller's environment. When auto-detect fires, a cli::cli_alert_info() announces the matched names (suppress with hal_configure(session_quiet = TRUE)). Set FALSE to disable.
reset: Logical; if TRUE, starts a fresh session before prompting.
inspect: Logical; if TRUE, returns session info instead of prompting.

Value

The assistant's text response (invisibly when displayed).

Errors in scripts

In an interactive session a transport failure prints an alert and returns invisible(NULL). In non-interactive contexts (scripts, R Markdown) it aborts with a classed condition instead, so programmatic callers can handle hal failures specifically: tryCatch(hal("..."), hal_transport_error = function(e) ...). All hal conditions inherit from hal_error / hal_warning; hal_do() signals hal_do_error / hal_do_warning, and hal_ask() signals hal_ask_warning.

Examples

if (FALSE) { # \dontrun{
# Simple conversation
hal("What is R?")
hal("Can you explain more about data frames?")

# Environment access (auto-detected when objects exist)
df <- mtcars
hal("What's the mean mpg?")   # auto-detects df, injects env snapshot

# Reset and start fresh
hal("Hello", reset = TRUE)

# Inspect session
hal(inspect = TRUE)
} # }