Turn a module into an ellmer tool

as_ellmer_tool() wraps a module as an ellmer tool, so a Chat, or a react() agent, can call it during a conversation. The tool's arguments are the module's input fields, with their types and descriptions.

Usage

as_ellmer_tool(
  module,
  name = NULL,
  description = NULL,
  .llm = NULL,
  annotations = NULL,
  output = c("auto", "json", "text", "raw"),
  copy = c("none", "deep"),
  error = c("reject", "abort", "return"),
  trace_context = list()
)

Arguments

module

A module, such as one created with module() or module_fn().

name

Tool name. Defaults to dsprrr_ followed by the input field names.

description

Tool description for the model. Defaults to the signature's instructions.

.llm

The chat the module uses when the tool is called. With NULL, the module's own chat or the default chat (see get_default_chat()).

annotations

Tool annotations from ellmer::tool_annotations(), which tell a chat or an agent runtime what the tool may do. With NULL (the default), they are inferred from the module. A prediction module, such as one from module() or chain_of_thought(), only sends its inputs to the model provider of its chat and changes nothing, so its tool is marked read-only and closed-world (read_only_hint = TRUE, open_world_hint = FALSE). A module compiled with KNNFewShot() is marked the same way when the module it wraps is; its vectorizer is assumed only to compute embeddings. Other modules get no annotations, because they can run your functions, tools or code: for example module_fn(), react(), code_act(), rlm_module(), flex(), pipelines and wrappers such as refine(). Use list() for no annotations, or pass your own. Agent runtimes may restrict tools without annotations, for example by treating them as destructive or as needing network access.

output

How the tool returns its result:

• "auto" (the default): the module's output with fields in signature order.

• "json": compact JSON with fields in signature order.

• "text": the main output field as text if possible, otherwise JSON.

• "raw": the module's output unchanged.

copy

"none" (the default) calls module itself, so its traces accumulate; "deep" calls a fresh deep copy each time.

error

What happens when the module fails:

• "reject" (the default): the tool returns an error description the model can read and react to. Its $type holds the condition class.

• "abort": the error propagates to the caller.

• "return": a dsprrr_tool_error condition carrying the error description in $payload is signalled, which a withCallingHandlers() handler can inspect.

trace_context

A named, JSON-compatible list recorded in the metadata and traces of every call made through the tool, as in run().

Value

An ellmer tool definition (ToolDef) for Chat$register_tool() or the tools argument of react(). It can also be called directly with the input fields as arguments.

See also

Other integrations: as_dsprrr_metric(), as_dsprrr_traces(), as_vitals_cost(), as_vitals_samples(), as_vitals_solver(), as_vitals_task(), create_search_tool(), llm_predict(), ragnar_tool(), reasoning_effort(), register_dsprrr_engine(), summarize_traces_df(), temperature(), top_p(), use_dsprrr_template(), validate_workflow(), vitals_metrics

Examples

shout <- module_fn("text -> reply", function(text) toupper(text))
shout_tool <- as_ellmer_tool(shout, name = "shout", description = "Upper-case text.")
shout_tool(text = "quiet please")
#> $reply
#> [1] "QUIET PLEASE"
#> 

if (FALSE) { # \dontrun{
sentiment <- module(
  signature("text -> sentiment: enum('positive', 'negative', 'neutral')")
)
sentiment_tool <- as_ellmer_tool(sentiment, name = "analyze_sentiment")

chat <- ellmer::chat_openai(model = "gpt-6-luna")
chat$register_tool(sentiment_tool)
chat$chat("What is the sentiment of: 'I love this product!'")
} # }