Define a governed tool

Like LLMR::llm_tool(), but the tool also declares how it behaves as a research instrument: whether it reads, writes, or reaches outside the session; whether a human must approve each call; and hard per-tool limits on the number of calls, wall-clock time, and result size. The returned object is an ordinary llmr_tool, so it passes to agent() and the tool loop exactly as a plain tool does; the governance is carried alongside and enforced on every call.

Usage

agent_tool(
  fn,
  name,
  description,
  parameters = NULL,
  required = NULL,
  side_effects = c("read", "write", "external", "none"),
  requires_approval = FALSE,
  timeout_s = NULL,
  max_calls = Inf,
  max_bytes = Inf
)

Arguments

fn

The R function to expose. Called with the model's arguments by name, exactly as in LLMR::llm_tool().

name

Tool name shown to the model.

description

One or two sentences for the model.

parameters

A named list of JSON-Schema properties, or a full schema object (as in LLMR::llm_tool()).

required

Character vector of required argument names.

side_effects

What the tool does in the world: "read" (default), "write", "external" (reaches a network or service), or "none".

requires_approval

If TRUE, each call pauses for human sign-off (see human_gate()); the agent then runs a controllable tool loop so the pause is possible. Default FALSE.

timeout_s

Optional wall-clock limit per call (seconds); needs the R.utils package to enforce, otherwise it is recorded but not enforced.

max_calls

Maximum times this tool object may run (Inf by default). A call beyond the limit is refused (the model is told, not the tool executed). The counter lives in the tool object, so it is shared if the same agent_tool() object is reused across agents or experiment cells; build a fresh tool per independent cell (as you would a fresh agent) when each cell should get its own budget.

max_bytes

Maximum result size; a larger result is truncated and flagged.

Value

An llmr_tool carrying a "governance" attribute.

Details

Governance is provenance. A tool's policy is folded into the study manifest via hash_tool_spec(), so tightening a limit (a different apparatus) changes the manifest hash. Each invocation is recorded with the hashes of its arguments and result, its status, and its duration, surfaced at the "tool" level of as_agent_run().

See also

LLMR::llm_tool(), hash_tool_spec(), guardrail(), human_gate()

Examples

lookup <- agent_tool(
  function(city) paste0("22C in ", city),
  name = "get_weather", description = "Current weather for a city.",
  parameters = list(city = list(type = "string")),
  side_effects = "external", max_calls = 5
)