Skip to contents

Get Started with llmr

get-started.Rmd

Introduction

The llmr package provides a flexible R interface to large language models (LLMs) with support for multiple providers, conversation management, and tool use. This vignette will get you started with the basics: creating an agent and equipping it with a simple calculator tool.

What You’ll Learn

By the end of this guide, you’ll understand how to:

  • Set up an LLM provider (Anthropic’s Claude)
  • Create an AI agent
  • Add a calculator tool to your agent
  • Have a conversation where the agent can perform calculations

Prerequisites

Before you begin, you’ll need:

  1. An API key from a supported LLM provider (we’ll use Anthropic’s Claude in this example)
  2. The mcpr package installed (for creating tools)
library(llmr)
#> 
#> Attaching package: 'llmr'
#> The following object is masked from 'package:stats':
#> 
#>     step
library(mcpr)
#> 
#> Attaching package: 'mcpr'
#> The following object is masked from 'package:methods':
#> 
#>     initialize
#> The following object is masked from 'package:base':
#> 
#>     write
library(ellmer)

Step 1: Create Your First Agent

An agent is an AI assistant that can use tools to help solve problems. Let’s create a simple calculator agent using Anthropic’s Claude:

# Create an agent with a descriptive name and ellmer chat object
agent <- new_agent("calculator", ellmer::chat_anthropic())
#> Using model = "claude-sonnet-4-20250514".

Important: You’ll need an Anthropic API key for this to work. You can get one from Anthropic’s website. The ellmer package will automatically use the ANTHROPIC_API_KEY environment variable.

That’s it! You now have a basic agent, but it can’t do much yet. Let’s give it some capabilities.

Step 2: Create a Calculator Tool

Tools allow your agent to perform specific actions. We’ll create a calculator tool that can perform basic arithmetic operations:

# Create a calculator tool
calculator <- new_tool(
  name = "calculator",
  description = "Performs basic arithmetic operations",
  input_schema = schema(
    properties = properties(
      operation = property_enum(
        "Operation",
        "Math operation to perform",
        values = c("add", "subtract", "multiply", "divide"),
        required = TRUE
      ),
      a = property_number("First number", "First operand", required = TRUE),
      b = property_number("Second number", "Second operand", required = TRUE)
    )
  ),
  handler = function(params) {
    result <- switch(
      params$operation,
      "add" = params$a + params$b,
      "subtract" = params$a - params$b,
      "multiply" = params$a * params$b,
      "divide" = params$a / params$b
    )
    response_text(result)
  }
)

Let’s break down what this tool does:

  • Name and description: Identifies the tool and explains its purpose
  • Input schema: Defines what parameters the tool expects:
    • operation: Must be one of “add”, “subtract”, “multiply”, or “divide”
    • a and b: The two numbers to operate on
  • Handler function: The actual R code that performs the calculation

Step 4: Add the Tool to Your Agent

Now we need to give our agent access to the calculator tool:

# Add the calculator tool to the agent
agent <- add_tool(agent, calculator)

Your agent is now equipped with calculation capabilities!

Step 5: Have a Conversation

Let’s test our calculator agent by asking it to perform some calculations:

# Ask the agent to perform a calculation
request(agent, "What is 15 multiplied by 7?")
get_last_message(agent)
#> assistant: 15 multiplied by 7 equals 105.

How It Works

When you ask the agent a question that requires calculation:

  1. The agent analyzes your request and determines it needs to perform math
  2. It calls the calculator tool with the appropriate operation and numbers
  3. The tool performs the calculation and returns the result
  4. The agent incorporates the result into a natural language response

This happens automatically - you don’t need to explicitly tell the agent to use the calculator tool.

Step 6: Adding Multiple Tools

Our agent can currently perform calculations, but let’s expand its capabilities by adding a simple text formatter tool. This will demonstrate how a single request can invoke multiple tools when needed.

# Create a text formatter tool
formatter <- new_tool(
  name = "convert",
  description = "Convert a number to Roman numerals",
  input_schema = schema(
    properties = properties(
      value = property_number(
        "Number",
        "The Number to convert",
        required = TRUE
      )
    )
  ),
  handler = function(params) {
    response_text(as.roman(params$value))
  }
)

# Add the formatter tool to our agent
agent <- add_tool(agent, formatter)

Now our agent has two tools at its disposal: a calculator and a text formatter. Let’s ask it a question that requires both tools:

# Ask a question that requires both calculation and text formatting
request(agent, "Calculate 25 times 12, and convert the result to Roman numerals.")
get_last_message(agent)
#> assistant: 25 times 12 equals 300, and 300 in Roman numerals is **CCC**.

How Multiple Tool Use Works

When you send a request that requires multiple tools:

  1. The agent analyzes your request and determines which tools it needs
  2. It can call multiple tools in sequence within a single request:
    • First, it uses the calculator to compute 25 × 4 = 100
    • Then, it uses the formatter to convert “C” (Roman numeral for 100) to uppercase
  3. The agent combines all the results into a coherent response

The beauty of this approach is that you don’t need to manage the tools manually - the agent decides which tools to use and in what order based on the task at hand.

What’s Next?

Now that you understand the basics, you can:

  • Explore other providers: Try using OpenAI instead of Anthropic
  • Create custom tools: Build tools for your specific use cases
  • Combine multiple tools: Give your agent access to several different capabilities
  • Use workflows: Chain multiple agents together for complex tasks

Key Concepts Summary

  • Provider: The LLM service (Anthropic, OpenAI, etc.)
  • Agent: An AI assistant that can use tools
  • Tool: A function that extends your agent’s capabilities
  • Schema: Defines the structure of tool inputs
  • Handler: The R function that actually performs the tool’s work
  • Multiple Tool Use: The ability for an agent to use several tools in a single request

The llmr package makes it easy to create powerful AI agents that can interact with your R environment and perform real work. Start simple with tools like our calculator and formatter, then gradually build more sophisticated capabilities as you become comfortable with the framework.